调用 WebRequest (Microsoft.PowerShell.Utility)

Invoke-WebRequest

从 Internet 上的网页获取内容。

句法

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

描述

Invoke-WebRequest cmdlet 向网页或 Web 服务发送 HTTP 和 HTTPS 请求。它解析响应并返回链接、图像和其他重要 HTML 元素的集合。

此 cmdlet 是在 PowerShell 3.0 中引入的。

从 PowerShell 7.0 开始，Invoke-WebRequest 支持由环境变量定义的代理配置。请参阅本文的注释部分。

这很重要

本文中的示例引用 contoso.com 域中的主机。这是 Microsoft 用作示例的虚构域。这些示例旨在展示如何使用 cmdlet。但是，由于 contoso.com 网站不存在，因此这些示例不起作用。使示例适应您环境中的主机。

从 PowerShell 7.4 开始，请求的字符编码默认为 UTF-8 而不是 ASCII。如果需要不同的编码，则必须在 Content-Type 标头中设置 charset 属性。

示例

示例 1：发送 Web 请求

此示例使用 Invoke-WebRequest cmdlet 向 Bing.com 网站发送 Web 请求。

$Response = Invoke-WebRequest -URI https://www.bing.com/search?q=how+many+feet+in+a+mile
$Response.InputFields | Where-Object {
    $_.name -like "* Value*"
} | Select-Object Name, Value

name       value
----       -----
From Value 1
To Value   5280

第一个命令发出请求并将响应保存在 $Response 变量中。

第二个命令获取任何 InputField，其中 Name 属性类似于 "* Value"。筛选结果通过管道传送到 Select-Object 以选择 Name 和 Value 属性。

示例 2：使用有状态 Web 服务

此示例演示如何将 Invoke-WebRequest cmdlet 与有状态 Web 服务结合使用。

$LoginParameters = @{
    Uri             = 'https://www.contoso.com/login/'
    SessionVariable = 'Session'
    Method          = 'POST'
    Body            = @{
        User     = 'jdoe'
        Password = 'P@S$w0rd!'
    }
}
$LoginResponse = Invoke-WebRequest @LoginParameters
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

第一次调用 Invoke-WebRequest 会发送登录请求。该命令为SessionVariable 参数的值指定Session 值。命令完成后，$LoginResponse 变量包含一个 BasicHtmlWebResponseObject，$Session 变量包含一个 WebRequestSession 对象。这将使用户登录到该站点。

对 Invoke-WebRequest 的第二次调用会获取用户的个人资料，这需要用户登录网站。存储在 $Session 变量中的会话数据为登录期间创建的站点提供会话 cookie。

示例3：从网页获取链接

此示例获取网页中的链接。它使用 Invoke-WebRequest cmdlet 来获取网页内容。然后，它使用 Invoke-WebRequest 返回的 BasicHtmlWebResponseObject 的 Links 属性，以及每个链接的 Href 属性。

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

示例 4：使用请求页面中定义的编码将响应内容写入文件

此示例使用 Invoke-WebRequest cmdlet 检索 PowerShell 文档页面的网页内容。

$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
    $Stream.Write($Response.Content)
} finally {
    $Stream.Dispose()
}

第一个命令检索页面并将响应对象保存在 $Response 变量中。

第二个命令创建一个 StreamWriter 用于将响应内容写入文件。响应对象的 Encoding 属性用于设置文件的编码。

最后几个命令将 Content 属性写入文件，然后释放 StreamWriter。

请注意，如果 Web 请求不返回文本内容，则 Encoding 属性为 null。

示例 5：提交 multipart/form-data 文件

此示例使用 Invoke-WebRequest cmdlet 上传文件作为 multipart/form-data 提交。文件 c:\document.txt 作为表单字段 document 提交，Content-Type 为 text/plain.

$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'

$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)

$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)

$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'

示例 6：简化的多部分/表单数据提交

某些 API 需要提交 multipart/form-data 才能上传文件和混合内容。此示例演示更新用户配置文件。

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = '[email protected]'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-WebRequest -Uri $Uri -Method Post -Form $Form

个人资料表单需要以下字段：firstName、lastName、email、avatar、birthday > 和爱好。 API 期望在 avatar 字段中提供用户个人资料图片的图像。该 API 还接受以同一表单提交的多个爱好条目。

创建 $Form 哈希表时，键名称用作表单字段名称。默认情况下，哈希表的值会转换为字符串。如果存在 System.IO.FileInfo 值，则提交文件内容。如果存在数组或列表等集合，则表单字段会被多次提交。

使用avatar 键上的Get-Item，将FileInfo 对象设置为值。结果是jdoe.png的图像数据被提交。

通过向 hobbies 键提供列表，hobbies 字段会在每个列表项的提交中出现一次。

示例 7：捕获来自 Invoke-WebRequest 的非成功消息

当 Invoke-WebRequest 遇到不成功的 HTTP 消息（404、500 等）时，它不会返回任何输出并引发终止错误。要捕获错误并查看 StatusCode，您可以将执行包含在 try/catch 块中。

try
{
    $Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
} catch {
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

终止错误由 catch 块捕获，该块从 Exception 对象中检索 StatusCode。

示例8：同时下载多个文件

Invoke-WebRequest cmdlet 一次只能下载一个文件。以下示例使用 Start-ThreadJob 创建多个线程作业以同时下载多个文件。

$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
        OutFile = 'PowerShell-7.2.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
        OutFile = 'PowerShell-7.2.5-win-x64.zip'
    }
)

$jobs = @()

foreach ($file in $files) {
    $jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
        $params = $using:file
        Invoke-WebRequest @params
    }
}

Write-Host "Downloads started..."
Wait-Job -Job $jobs

foreach ($job in $jobs) {
    Receive-Job -Job $job
}

示例 9：跳过标头验证

默认情况下，Invoke-WebRequest cmdlet 验证具有标准定义值格式的众所周知标头的值。以下示例展示了此验证如何引发错误，以及如何使用 SkipHeaderValidation 参数来避免验证允许无效格式值的端点的值。

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation

Invoke-WebRequest: The format of value '12345' is invalid.

StatusCode        : 200
StatusDescription : OK
Content           : {
                      "headers": {
                        "Host": "httpbin.org",
                        "If-Match": "12345",
                        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.19044; en-US) PowerShell/7.2.5",
                        "X-Amzn-Trace-Id": �
RawContent        : HTTP/1.1 200 OK
                    Date: Mon, 08 Aug 2022 16:24:24 GMT
                    Connection: keep-alive
                    Server: gunicorn/19.9.0
                    Access-Control-Allow-Origin: *
                    Access-Control-Allow-Credentials: true
                    Content-Type: application�
Headers           : {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Access-Control-Allow-Origin, System.String[]]�}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 249
RelationLink      : {}

httpbin.org 是一项返回有关 Web 请求和响应的信息以进行故障排除的服务。 $Uri 变量分配给服务的 /headers 端点，该端点返回请求的标头作为其响应中的内容。

If-Match 请求标头在 RFC-7232 第 3.1 节中定义，并要求使用引号定义该标头的值。 $InvalidHeaders 变量被分配了一个哈希表，其中 If-Match 的值无效，因为它被定义为 12345 而不是 ” 12345”。

使用无效标头调用 Invoke-WebRequest 会返回错误，报告格式化值无效。请求不会发送到端点。

使用 SkipHeaderValidation 参数调用 Invoke-WebRequest 会忽略验证失败并将请求发送到端点。由于端点容忍不合规的标头值，因此 cmdlet 返回响应对象而不会出现错误。

示例 10：使用 HTTP 2.0 发送请求

此示例使用 HTTP 2.0 协议获取网页中的链接。它使用 Invoke-WebRequest cmdlet 来获取网页内容。然后，它使用 Invoke-WebRequest 返回的 BasicHtmlWebResponseObject 的 Links 属性，以及每个链接的 Href 属性。

(Invoke-WebRequest -Uri 'https://aka.ms/pscore6-docs' -HttpVersion 2.0).Links.Href

示例 11：向 Unix 套接字应用程序发送请求

某些应用程序（例如 Docker）公开 Unix 套接字以进行通信。此示例使用 Docker API 查询 Docker 映像列表。该 cmdlet 使用 Unix 套接字连接到 Docker 守护程序。

Invoke-WebRequest -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

参数

-AllowInsecureRedirect

允许从 HTTPS 重定向到 HTTP。默认情况下，从 HTTPS 重定向到 HTTP 的任何请求都会导致错误，并且请求将被中止，以防止通过未加密的连接无意中以纯文本方式进行通信。要覆盖此行为（风险自负），请使用 AllowInsecureRedirect 参数。

此参数是在 PowerShell 7.4 中添加的。

SwitchParameter

命名

False

False

False

False

-AllowUnencryptedAuthentication

允许通过未加密的连接发送凭据和机密。默认情况下，提供凭据或任何身份验证选项，其Uri不以https://开头导致错误并且请求被中止，以防止通过未加密的连接无意中以纯文本形式传达秘密。要覆盖此行为（风险自负），请提供 AllowUnencryptedAuthentication 参数。

警告

使用此参数不安全，不建议使用。提供它只是为了与无法提供加密连接的旧系统兼容。使用风险自负。

此功能是在 PowerShell 6.0.0 中添加的。

SwitchParameter

命名

False

False

False

False

-Authentication

指定用于请求的显式身份验证类型。默认值为无。 Authentication 参数不能与 UseDefaultCredentials 参数一起使用。

可用的身份验证选项：

• 无：当未提供身份验证时，这是默认选项。不使用显式身份验证。
• 基本：需要凭据。凭据以 RFC 7617 基本身份验证 Authorization: Basic 标头的形式发送，格式为 base64(user:password)。
• Bearer：需要Token参数。使用提供的令牌发送 RFC 6750 Authorization: Bearer 标头。
• OAuth：需要Token参数。使用提供的令牌发送 RFC 6750 Authorization: Bearer 标头。

提供 Authentication 会覆盖提供给 Headers 或包含在 WebSession 中的任何 Authorization 标头。

此功能是在 PowerShell 6.0.0 中添加的。

Web认证类型

无、基本、不记名、OAuth

命名

None

False

False

False

-Body

指定请求的正文。正文是标头后面的请求内容。您还可以通过管道将正文值传递给 Invoke-WebRequest。

Body 参数可用于指定查询参数列表或指定响应内容。对于查询参数，cmdlet 使用 System.Net.WebUtility.UrlEncode 方法对键值对进行编码。有关 URL 字符串编码的更多信息，请参阅 UrlEncode() 方法参考。

当输入是 POST 请求并且正文是 String 时，第一个等号 (=) 左侧的值将设置为表单数据中的键并将剩余文本设置为值。要指定多个键，请为 Body 使用 IDictionary 对象，例如哈希表。

当输入是 GET 请求且正文是 IDictionary（通常是哈希表）时，正文将作为查询参数添加到 URI。对于其他请求类型（例如 PATCH），正文设置为标准 name=value 格式的请求正文值，并且值经过 URL 编码。

当输入是 System.Xml.XmlNode 对象并且 XML 声明指定编码时，该编码将用于请求中的数据，除非被 ContentType 参数覆盖。

Body 参数还接受 System.Net.Http.MultipartFormDataContent 对象。这有助于 multipart/form-data 请求。当为 Body 提供 MultipartFormDataContent 对象时，任何与内容相关的标头提供给 ContentType、Headers 或 WebSession 参数被 MultipartFormDataContent 对象的内容标头覆盖。此功能是在 PowerShell 6.0.0 中添加的。

目的

命名

None

False

True

False

-Certificate

指定用于安全 Web 请求的客户端证书。输入包含证书的变量或获取证书的命令或表达式。

要查找证书，请使用 Get-PfxCertificate 或使用证书 (Cert:) 驱动器中的 Get-ChildItem cmdlet。如果证书无效或没有足够的权限，该命令将失败。

X509证书

命名

None

False

False

False

-CertificateThumbprint

指定有权发送请求的用户帐户的数字公钥证书 (X509)。输入证书的证书指纹。

证书用于基于客户端证书的身份验证。证书只能映射到本地用户帐户，不能映射到域帐户。

要查看证书指纹，请使用 Get-Item 或 Get-ChildItem 命令在 Cert:\CurrentUser\My 中查找证书。

笔记

此功能仅在 Windows 操作系统平台上受支持。

String

命名

None

False

False

False

-ConnectionTimeoutSeconds

指定请求在超时之前可以挂起的时间。输入一个以秒为单位的值。默认值 0 指定无限期的超时。

域名系统 (DNS) 查询最多可能需要 15 秒才能返回或超时。如果您的请求包含需要解析的主机名，并且您将 ConnectionTimeoutSeconds 设置为大于零但小于 15 秒的值，则可能需要 15 秒或更长时间才会出现 WebException 抛出，并且您的请求超时。

此参数替换了 PowerShell 7.4 中的 TimeoutSec 参数。您可以使用 TimeoutSec 作为 ConnectionTimeoutSeconds 的别名。

整数32

TimeoutSec

命名

None

False

False

False

-ContentType

指定 Web 请求的内容类型。

如果 ContentType 的值包含编码格式（如 charset），则 cmdlet 使用该格式对 Web 请求正文进行编码。如果 ContentType 未指定编码格式，则使用默认编码格式。具有编码格式的 ContentType 示例是 text/plain； charset=iso-8859-5，指定拉丁/西里尔字母。

如果省略此参数并且请求方法为 POST 或 PUT，则 Invoke-WebRequest 将内容类型设置为 application/x-www-form-urlencoded。否则，调用中不会指定内容类型。

当为 Body 提供 MultipartFormDataContent 对象时，ContentType 将被覆盖。

从 PowerShell 7.4 开始，如果您同时使用此参数和 Headers 参数来定义 Content-Type 标头，则在 ContentType 中指定的值> 使用参数。

String

命名

None

False

False

False

-Credential

指定有权发送请求的用户帐户。默认为当前用户。

输入用户名，例如 User01 或 Domain01\User01，或输入由 Get-Credential cmdlet。

凭据可以单独使用，也可以与某些身份验证参数选项结合使用。单独使用时，它仅在远程服务器发送身份验证质询请求时才向远程服务器提供凭据。与身份验证选项一起使用时，将显式发送凭据。

凭证存储在 PSCredential 对象中，密码存储为 SecureString。

笔记

有关 SecureString 数据保护的更多信息，请参阅 SecureString 的安全性如何？。

PS凭证

命名

当前用户

False

False

False

-CustomMethod

指定用于 Web 请求的自定义方法。如果端点所需的请求方法不是方法上的可用选项，则可以使用此选项。 方法和自定义方法不能一起使用。

此示例向 API 发出 TEST HTTP 请求：

Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

此功能是在 PowerShell 6.0.0 中添加的。

String

CM

命名

None

True

False

False

-DisableKeepAlive

指示 cmdlet 将 HTTP 标头中的 KeepAlive 值设置为 False。默认情况下，KeepAlive 为True。 KeepAlive 建立与服务器的持久连接以方便后续请求。

SwitchParameter

命名

False

False

False

False

-Form

将字典转换为 multipart/form-data 提交。 表单不得与正文一起使用。如果使用 ContentType，它将被忽略。

字典的键用作表单字段名称。默认情况下，表单值会转换为字符串值。

如果该值为 System.IO.FileInfo 对象，则提交二进制文件内容。文件名作为 filename 属性提交。 MIME 类型设置为application/octet-stream。 Get-Item 可用于简化提供 System.IO.FileInfo 对象。

$Form=@{ 简历=Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

如果值是集合类型，例如数组或列表，则for字段会被多次提交。默认情况下，列表的值被视为字符串。如果该值为 System.IO.FileInfo 对象，则提交二进制文件内容。不支持嵌套集合。

$Form=@{ 标签='假期', '意大利', '2017' 图片=Get-ChildItem 'c:\Users\jdoe\Pictures\2017-意大利' }

在上面的示例中，tags 字段在表单中提供了三次，分别为 Vacation、Italy 和 2017。对于 2017-Italy 文件夹中的每个文件，pictures 字段也会提交一次。该文件夹中文件的二进制内容作为值提交。

此功能是在 PowerShell 6.1.0 中添加的。

词典

命名

None

False

False

False

-Headers

指定 Web 请求的标头。输入哈希表或字典。

当为 Body 提供 MultipartFormDataContent 对象时，与内容相关的标头（例如 Content-Type）将被覆盖。

从 PowerShell 7.4 开始，如果使用此参数定义 Content-Type 标头并使用 ContentType 参数，则在 ContentType 参数中指定的值被使用。

词典

命名

None

False

False

False

-HttpVersion

指定用于请求的 HTTP 版本。默认值为 1.1。

有效值为：

• 1.0
• 1.1
• 2.0
• 3.0

版本

命名

1.1

False

False

False

-InFile

从文件中获取 Web 请求的内容。输入路径和文件名。如果省略路径，则默认为当前位置。

String

命名

None

False

False

False

-MaximumRedirection

指定在连接失败之前 PowerShell 将连接重定向到备用统一资源标识符 (URI) 的次数。默认值为 5。值 0（零）会阻止所有重定向。

整数32

命名

5

False

False

False

-MaximumRetryCount

指定当收到 400 到 599（含）或 304 之间的故障代码时 PowerShell 重试连接的次数。另请参阅 RetryIntervalSec 参数以指定重试次数。

整数32

命名

None

False

False

False

-Method

指定用于 Web 请求的方法。该参数可接受的值为：

Default

Delete

Get

Head

Merge

Options

Patch

Post

Put

Trace

CustomMethod 参数可用于上面未列出的请求方法。

Web请求方法

默认、获取、标题、发布、放置、删除、跟踪、选项、合并、修补

命名

None

False

False

False

-NoProxy

指示 cmdlet 不应使用代理来到达目标。当您需要绕过环境中配置的代理时，请使用此开关。此功能是在 PowerShell 6.0.0 中添加的。

SwitchParameter

命名

False

True

False

False

-OperationTimeoutSeconds

此超时适用于流内的数据读取，而不适用于整个流时间。默认值 0 指定无限期超时。

将该值设置为 30 秒意味着流中数据之间任何超过 30 秒的延迟都会终止请求。除非流停止超过 30 秒，否则需要几分钟下载的大文件不会终止。

整数32

命名

None

False

False

False

-OutFile

默认情况下，Invoke-WebRequest 将结果返回到管道。当您使用OutFile参数时，结果将保存到指定文件中，并且不会返回到管道。输入路径和文件名。要将结果发送到文件和管道，请添加 Passthru 参数。

如果省略路径，则默认为当前位置。该名称被视为文字路径。包含方括号 ([]) 的名称必须用单引号 (') 括起来。

从 PowerShell 7.4 开始，您可以指定不带文件名的文件夹路径。执行此操作后，该命令将使用任何重定向后解析的 URI 最后一段的文件名。当您为 OutFile 指定文件夹路径时，无法使用 Resume 参数。

String

命名

None

False

False

False

-PassThru

指示 cmdlet 除了将结果写入文件之外还返回结果。仅当命令中同时使用OutFile参数时，该参数才有效。

笔记

当您使用 PassThru 参数时，输出将写入管道，但不会创建文件。此问题已在 PowerShell 7.5-preview.4 中修复。有关详细信息，请参阅 PowerShell 问题 #15409。

SwitchParameter

命名

False

False

False

False

-PreserveAuthorizationOnRedirect

指示 cmdlet 应跨重定向保留 Authorization 标头（如果存在）。

默认情况下，cmdlet 在重定向之前删除 Authorization 标头。对于需要将标头发送到重定向位置的情况，指定此参数会禁用此逻辑。

此功能是在 PowerShell 6.0.0 中添加的。

SwitchParameter

命名

False

False

False

False

-PreserveHttpMethodOnRedirect

指示 cmdlet 应保留跨重定向的请求方法。

默认情况下，cmdlet 在重定向时将方法更改为 GET。指定此参数会禁用此逻辑，以确保预期的方法可以与重定向一起使用。

此功能是在 PowerShell 7.4 中添加的。

SwitchParameter

命名

False

False

False

False

-Proxy

为请求指定代理服务器，而不是直接连接到 Internet 资源。输入网络代理服务器的 URI。

乌里

命名

None

False

False

False

-ProxyCredential

指定有权使用Proxy参数指定的代理服务器的用户帐户。默认为当前用户。

键入用户名，例如 User01 或 Domain01\User01，或输入 PSCredential 对象，例如由 Get 生成的对象-Credential cmdlet。

仅当命令中同时使用Proxy参数时，该参数才有效。您不能在同一命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 参数。

PS凭证

命名

当前用户

False

False

False

-ProxyUseDefaultCredentials

指示 cmdlet 使用当前用户的凭据访问 Proxy 参数指定的代理服务器。

仅当命令中同时使用Proxy参数时，该参数才有效。您不能在同一命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 参数。

SwitchParameter

命名

False

False

False

False

-Resume

尽最大努力尝试恢复下载部分文件。 恢复需要OutFile。

恢复仅对本地文件和远程文件的大小进行操作，并且不执行其他验证本地文件和远程文件是否相同的操作。

如果本地文件大小小于远程文件大小，则 cmdlet 会尝试恢复下载文件并将剩余字节附加到文件末尾。

如果本地文件大小与远程文件大小相同，则不执行任何操作，并且 cmdlet 假定下载已完成。

如果本地文件大小大于远程文件大小，则覆盖本地文件并重新下载整个远程文件。此行为与使用不带 Resume 的 OutFile 相同。

如果远程服务器不支持断点续传，则覆盖本地文件并重新下载整个远程文件。此行为与使用不带 Resume 的 OutFile 相同。

如果本地文件不存在，则创建本地文件并下载整个远程文件。此行为与使用不带 Resume 的 OutFile 相同。

此功能是在 PowerShell 6.1.0 中添加的。

SwitchParameter

命名

False

False

False

False

-RetryIntervalSec

指定收到 400 到 599（含）之间的失败代码或 304 时重试连接的时间间隔。另请参阅 MaximumRetryCount 参数以指定重试次数。该值必须介于 1 和 [int]::MaxValue 之间。

当失败代码为 429 并且响应在其标头中包含 Retry-After 属性时，cmdlet 会使用该值作为重试间隔，即使指定了此参数也是如此。

整数32

命名

5

False

False

False

-SessionVariable

指定此 cmdlet 为其创建 Web 请求会话并将其保存在值中的变量。输入不带美元符号 ($) 的变量名称。

当您指定会话变量时，Invoke-WebRequest 会创建一个 Web 请求会话对象，并将其分配给 PowerShell 会话中具有指定名称的变量。命令完成后，您就可以在会话中使用该变量。

在 PowerShell 7.4 之前，Web 请求会话不是持久连接。它是一个对象，包含有关连接和请求的信息，包括 cookie、凭据、最大重定向值和用户代理字符串。您可以使用它在 Web 请求之间共享状态和数据。

从 PowerShell 7.4 开始，只要会话的属性在后续请求中未被覆盖，Web 请求会话就会持续存在。当它们出现时，cmdlet 将使用新值重新创建会话。持久会话减少了重复请求的开销，使请求速度更快。

要在后续 Web 请求中使用 Web 请求会话，请在 WebSession 参数的值中指定会话变量。 PowerShell 在建立新连接时使用 Web 请求会话对象中的数据。要覆盖 Web 请求会话中的值，请使用 cmdlet 参数，例如 UserAgent 或 Credential。参数值优先于 Web 请求会话中的值。

您不能在同一命令中使用 SessionVariable 和 WebSession 参数。

String

SV

命名

None

False

False

False

-SkipCertificateCheck

跳过证书验证检查。这包括所有验证，例如过期、撤销、受信任的根权限等。

警告

使用此参数不安全，不建议使用。此开关仅适用于使用自签名证书进行测试的已知主机。使用风险自负。

此功能是在 PowerShell 6.0.0 中添加的。

SwitchParameter

命名

False

False

False

False

-SkipHeaderValidation

指示 cmdlet 应向请求添加标头而不进行验证。

此开关应用于需要不符合标准的标头值的站点。指定此开关将禁用验证以允许值未经检查地传递。指定后，将添加所有标头而不进行验证。

此开关禁用对传递给 ContentType、Headers 和 UserAgent 参数的值进行验证。

此功能是在 PowerShell 6.0.0 中添加的。

SwitchParameter

命名

False

False

False

False

-SkipHttpErrorCheck

此参数使 cmdlet 忽略 HTTP 错误状态并继续处理响应。错误响应被写入管道，就像它们成功一样。

此参数是在 PowerShell 7 中引入的。

SwitchParameter

命名

False

False

False

False

-SslProtocol

设置 Web 请求允许的 SSL/TLS 协议。默认情况下，允许系统支持的所有 SSL/TLS 协议。 SslProtocol 允许出于合规性目的限制特定协议。

这些值被定义为基于标志的枚举。您可以使用此参数将多个值组合在一起以设置多个标志。这些值可以作为值数组或这些值的逗号分隔字符串传递到 SslProtocol 参数。该 cmdlet 使用二进制 OR 运算组合这些值。将值作为数组传递是最简单的选项，并且还允许您对值使用制表符补全。您可能无法在所有平台上定义多个选项。

笔记

在非 Windows 平台上，可能无法提供 Tls 或 Tls12 作为选项。并非所有操作系统都支持 Tls13，需要根据每个操作系统进行验证。

PowerShell 6.0.0 中添加了此功能，PowerShell 7.1 中添加了对 Tls13 的支持。

WebSSL协议

默认、Tls、Tls11、Tls12

命名

None

False

False

False

-Token

要包含在请求中的 OAuth 或承载令牌。某些身份验证选项需要令牌。它不能独立使用。

Token 采用包含令牌的 SecureString。要手动提供令牌，请使用以下命令：

Invoke-WebRequest -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

此参数是在 PowerShell 6.0 中引入的。

SecureString

命名

None

False

False

False

-TransferEncoding

指定传输编码 HTTP 响应标头的值。该参数可接受的值为：

Chunked

Compress

Deflate

GZip

Identity

String

分块、压缩、放气、gzip、身份

命名

None

False

False

False

-UnixSocket

指定要连接的 Unix 套接字的名称。基于 Unix 的系统和 Windows 版本 1803 及更高版本支持此参数。有关 Windows 对 Unix 套接字的支持的更多信息，请参阅 Windows/WSL Interop with AF_UNIX 博客文章。

此参数是在 PowerShell 7.4 中添加的。

UnixDomainSocketEndPoint

命名

None

False

False

False

-Uri

指定 Web 请求发送到的 Internet 资源的统一资源标识符 (URI)。输入 URI。该参数仅支持HTTP或HTTPS。

此参数是必需的。参数名称 Uri 是可选的。

乌里

0

None

True

False

False

-UseBasicParsing

该参数已被弃用。从 PowerShell 6.0.0 开始，所有 Web 请求仅使用基本解析。包含此参数只是为了向后兼容，对其的任何使用都不会影响 cmdlet 的操作。

SwitchParameter

命名

False

False

False

False

-UseDefaultCredentials

指示 cmdlet 使用当前用户的凭据发送 Web 请求。这不能与身份验证或凭据一起使用，并且可能并非所有平台都支持。

SwitchParameter

命名

False

False

False

False

-UserAgent

指定 Web 请求的用户代理字符串。

默认用户代理类似于 Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0，每个操作系统和平台略有不同。

要使用大多数 Internet 浏览器使用的标准用户代理字符串测试网站，请使用 PSUserAgent 类的属性，例如 Chrome、FireFox、InternetExplorer、Opera 和 Safari。

例如，以下命令使用 Internet Explorer 的用户代理字符串：Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

String

命名

None

False

False

False

-WebSession

指定 Web 请求会话。输入变量名称，包括美元符号 ($)。

要覆盖 Web 请求会话中的值，请使用 cmdlet 参数，例如 UserAgent 或 Credential。参数值优先于 Web 请求会话中的值。当为 Body 提供 MultipartFormDataContent 对象时，与内容相关的标头（例如 Content-Type）也会被覆盖。

与远程会话不同，Web 请求会话不是持久连接。它是一个对象，包含有关连接和请求的信息，包括 cookie、凭据、最大重定向值和用户代理字符串。您可以使用它在 Web 请求之间共享状态和数据。

要创建 Web 请求会话，请在 Invoke-WebRequest 命令的 SessionVariable 参数值中输入变量名称（不带美元符号）。 Invoke-WebRequest 创建会话并将其保存在变量中。在后续命令中，使用该变量作为 WebSession 参数的值。

您不能在同一命令中使用 SessionVariable 和 WebSession 参数。

网络请求会话

命名

None

False

False

False

输入

对象

您可以通过管道将 Web 请求正文传递给此 cmdlet。

输出

BasicHtmlWebResponseObject

此 cmdlet 返回表示 Web 请求结果的响应对象。

笔记

PowerShell 包含以下 Invoke-WebRequest 别名：

• 所有平台：

  iwr

从 PowerShell 6.0.0 开始 Invoke-WebRequest 仅支持基本解析。

有关详细信息，请参阅BasicHtmlWebResponseObject。

由于 .NET Core 3.1 中的更改，PowerShell 7.0 及更高版本使用 HttpClient.DefaultProxy 属性来确定代理配置。

该属性的值由您的平台决定：

• 对于 Windows：从环境变量中读取代理配置。如果未定义这些变量，则该属性将从用户的代理设置派生。
• 对于 macOS：从环境变量中读取代理配置。如果未定义这些变量，则该属性将从系统的代理设置派生。
• 对于 Linux：从环境变量中读取代理配置。如果未定义这些变量，则该属性将初始化绕过所有地址的未配置实例。

Windows 和基于 Unix 的平台上用于 DefaultProxy 初始化的环境变量是：

• HTTP_PROXY：HTTP 请求中使用的代理服务器的主机名或 IP 地址。
• HTTPS_PROXY：HTTPS 请求上使用的代理服务器的主机名或 IP 地址。
• ALL_PROXY：在未定义 HTTP_PROXY 或 HTTPS_PROXY 的情况下，在 HTTP 和 HTTPS 请求上使用的代理服务器的主机名或 IP 地址。
• NO_PROXY：应从代理中排除的主机名的逗号分隔列表。

PowerShell 7.4 添加了对 Brotli 压缩算法的支持。