Invoke-WebRequest

参考

模块:: Microsoft.PowerShell.Utility

从 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 将 HTTP 和 HTTPS 请求发送到网页或 Web 服务。它将分析响应并返回链接、图像和其他重要 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 将 Web 请求发送到 Bing.com 网站。

$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 变量中。

第二个命令获取 Name 属性类似于 "* Value" 的任何 InputField。筛选后的结果通过管道传递给 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：提交多部分/表单数据文件

此示例使用 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      = 'john.doe@contoso.com'
    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 和 hobbies。 API 需要 avatar 域中提供用户个人资料图像。该 API 还将接受多个要以同一形式提交的 hobbies 条目。

创建 $Form HashTable 时，键名称将用作表单域名称。默认情况下，HashTable 的值将转换为字符串。如果存在 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
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-AllowUnencryptedAuthentication

允许通过未加密的连接发送凭据和机密。默认情况下，提供不以 https:// 开头的 Uri 的 Credential 或任何 Authentication 选项都将导致错误，请求将中止，以防止无意中通过未加密的连接以纯文本方式传达机密。若要自行重写此行为，请提供 AllowUnencryptedAuthentication 参数。

警告

此参数并不安全，不建议使用。它仅用于与无法提供加密连接的旧系统兼容。使用时需要自控风险。

此功能在 PowerShell 6.0.0 中添加。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-Authentication

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

可用的身份验证选项：

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

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

此功能在 PowerShell 6.0.0 中添加。

类型:	WebAuthenticationType
接受的值:	None, Basic, Bearer, OAuth
Position:	Named
默认值:	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 中添加。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	True
接受通配符:	False

-Certificate

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

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

类型:	X509Certificate
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-CertificateThumbprint

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

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

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

注意

此功能仅在 Windows OS 平台上受支持。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ConnectionTimeoutSeconds

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

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

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

类型:	Int32
别名:	TimeoutSec
Position:	Named
默认值:	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
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Credential

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

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

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

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

注意

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

类型:	PSCredential
Position:	Named
默认值:	Current user
必需:	False
接受管道输入:	False
接受通配符:	False

-CustomMethod

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

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

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

此功能在 PowerShell 6.0.0 中添加。

类型:	String
别名:	CM
Position:	Named
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-DisableKeepAlive

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

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-Form

将字典转换为 multipart/form-data 提交。 Form 不能与 Body 一起使用。如果使用 ContentType，则会忽略它。

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

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

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

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

$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

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

此功能在 PowerShell 6.1.0 中添加。

类型:	IDictionary
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Headers

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

为 Body 提供 MultipartFormDataContent 对象时，将重写与内容相关的标头（如 Content-Type）。

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

类型:	IDictionary
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-HttpVersion

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

有效值为：

类型:	Version
Position:	Named
默认值:	1.1
必需:	False
接受管道输入:	False
接受通配符:	False

-InFile

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

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumRedirection

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

类型:	Int32
Position:	Named
默认值:	5
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumRetryCount

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

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

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

类型:	WebRequestMethod
接受的值:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-NoProxy

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

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	True
接受管道输入:	False
接受通配符:	False

-OperationTimeoutSeconds

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

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

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-OutFile

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

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

从 PowerShell 7.4 开始，可以指定不包含文件名的文件夹路径。执行此操作时，该命令会在任何重定向后使用解析 URI 的最后一段的文件名。如果为 OutFile 指定了文件夹路径，则不能使用 Resume 参数。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-PassThru

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

注意

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

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-PreserveAuthorizationOnRedirect

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

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

此功能在 PowerShell 6.0.0 中添加。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-PreserveHttpMethodOnRedirect

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

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

此功能在 PowerShell 7.4 中添加。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-Proxy

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

类型:	Uri
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ProxyCredential

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

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

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

类型:	PSCredential
Position:	Named
默认值:	Current user
必需:	False
接受管道输入:	False
接受通配符:	False

-ProxyUseDefaultCredentials

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

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

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-Resume

尽最大努力继续下载部分文件。 Resume 需要 OutFile。

Resume 仅对本地文件和远程文件的大小进行操作，而不执行本地文件与远程文件相同的其他验证。

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

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

如果本地文件大小大于远程文件大小，则将替代本地文件，并重新下载整个远程文件。此行为与在没有 Resume 的情况下使用 OutFile 相同。

如果远程服务器不支持下载恢复，则会替代本地文件并重新下载整个远程文件。此行为与在没有 Resume 的情况下使用 OutFile 相同。

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

此功能在 PowerShell 6.1.0 中添加。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-RetryIntervalSec

指定当收到 400 到 599（包括 400 和 599）或 304 之间的故障代码时连接重试之间的间隔。另请参阅 MaximumRetryCount 参数，了解如何指定重试次数。该值必须在 1 和 [int]::MaxValue 之间。

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

类型:	Int32
Position:	Named
默认值:	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
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-SkipCertificateCheck

跳过证书验证检查。这包括所有验证，例如过期、吊销、受信任根机构等。

警告

此参数并不安全，不建议使用。此开关仅用于使用自签名证书对已知主机进行测试。使用时需要自控风险。

此功能在 PowerShell 6.0.0 中添加。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-SkipHeaderValidation

指示 cmdlet 应在未验证的情况下向请求添加标头。

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

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

此功能在 PowerShell 6.0.0 中添加。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-SkipHttpErrorCheck

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

在 PowerShell 7 中引入了此参数。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-SslProtocol

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

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

注意

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

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

类型:	WebSslProtocol
接受的值:	Default, Tls, Tls11, Tls12
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Token

要包含在请求中的 OAuth 或持有者令牌。某些 Authentication 选项需要 Token。它不能单独使用。

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

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

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

类型:	SecureString
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

类型:	String
接受的值:	chunked, compress, deflate, gzip, identity
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-UnixSocket

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

此参数已在 PowerShell 7.4 中添加。

类型:	UnixDomainSocketEndPoint
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Uri

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

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

类型:	Uri
Position:	0
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-UseBasicParsing

此参数已弃用。从 PowerShell 6.0.0 开始，所有 Web 请求仅使用基本分析。此参数仅用于后向兼容性，任何对它的使用都不会影响 cmdlet 的运行。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-UseDefaultCredentials

指示此 cmdlet 使用当前用户的凭据来发送 Web 请求。这不能与 Authentication 或 Credential 一起使用，并且可能不是所有平台都支持。

类型:	SwitchParameter
Position:	Named
默认值:	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
Position:	Named
默认值:	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 参数。

类型:	WebRequestSession
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

Object

可以通过管道将 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 压缩算法的支持。

通过

Invoke-WebRequest

语法

说明

示例

示例 1：发送 Web 请求

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

示例 3：从网页获取链接

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

示例 5：提交多部分/表单数据文件

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

示例 7：从 Invoke-WebRequest 捕获非成功消息

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

示例 9：跳过标头验证

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

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

参数

-AllowInsecureRedirect

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ConnectionTimeoutSeconds

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-HttpVersion

-InFile

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OperationTimeoutSeconds

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-PreserveHttpMethodOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-Token

-TransferEncoding

-UnixSocket

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

输出

备注

相关链接

其他资源