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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

说明

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

此 cmdlet 是在 PowerShell 3.0 中引入的。

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

重要

本文中的示例引用域中的 contoso.com 主机。这是 Microsoft 用于示例的虚构域。这些示例旨在演示如何使用 cmdlet。但是，由于 contoso.com 站点不存在，因此这些示例不起作用。根据环境中的主机改编示例。

示例

示例 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 。

第二个命令获取 Name 属性类似于 "* Value"的任何 InputField。筛选的结果通过管道传递到 Select-Object 以选择 “名称” 和“ 值” 属性。

示例 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 获取网页内容。然后，它使用返回的 BasicHtmlWebResponseObjectInvoke-WebRequest 的 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 upload a file 作为 multipart/form-data 提交。文件 c:\document.txt 作为表单字段 document 提交，其中为 Content-Typetext/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、emailavatar、 birthday和 hobbies。 API 要求在字段中提供 avatar 用户配置文件图片的图像。 API 还接受以同一窗体提交的多个 hobbies 条目。

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

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

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

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

当遇到不成功的 HTTP 消息 (404、500 等 ) 时 Invoke-WebRequest ，它将不返回任何输出并引发终止错误。若要捕获错误并查看 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 获取网页内容。然后，它使用返回的 BasicHtmlWebResponseObjectInvoke-WebRequest 的 Links 属性和每个链接的 Href 属性。

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

参数

-AllowUnencryptedAuthentication

允许通过未加密的连接发送凭据和机密。默认情况下，使用不以 https:// 开头的 URI 提供凭据或任何身份验证选项会导致错误和请求中止，以防止无意中通过未加密的连接以纯文本形式传达机密。若要自担风险替代此行为，请提供 AllowUnencryptedAuthentication 参数。

警告

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

此功能已在 PowerShell 6.0.0 中添加。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Authentication

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

可用的身份验证选项：

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

提供身份验证会Authorization替代提供给标头或包含在 WebSession 中的任何标头。

此功能已在 PowerShell 6.0.0 中添加。

Type:	WebAuthenticationType
Accepted values:	None, Basic, Bearer, OAuth
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Body

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

可以将 Body 参数用于指定查询参数的列表，或用于指定响应的内容。

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

当输入是 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 参数的任何与 Content 相关的标头将被 MultipartFormDataContent 对象的 Content 标头覆盖。此功能已在 PowerShell 6.0.0 中添加。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Certificate

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

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

Type:	X509Certificate
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CertificateThumbprint

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

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

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

注意

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContentType

指定 Web 请求的内容类型。

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

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

为 Body 提供 MultipartFormDataContent 对象时，将重写 ContentType。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

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

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

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

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

注意

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

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CustomMethod

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

以下示例向 TEST API 发出 HTTP 请求：

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

此功能已在 PowerShell 6.0.0 中添加。

Type:	String
Aliases:	CM
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableKeepAlive

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Form

将字典转换为 multipart/form-data 提交。窗体不能与正文一起使用。如果使用 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' }

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

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

在上面的示例中，字段tags在窗体中提供三次，每个、和 2017各VacationItaly提供一次。该 pictures 字段还会为文件夹中的每个文件 2017-Italy 提交一次。该文件夹中文件的二进制内容作为值提交。

此功能已在 PowerShell 6.1.0 中添加。

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Headers

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

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

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HttpVersion

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

有效值为：

Type:	Version
Position:	Named
Default value:	1.1
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InFile

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRedirection

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

Type:	Int32
Position:	Named
Default value:	5
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRetryCount

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

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

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

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-NoProxy

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-OutFile

指定此 cmdlet 保存响应正文的输出文件。输入路径和文件名。如果省略路径，则默认路径为当前位置。该名称被视为文本路径。包含方括号 ([]) 的名称必须用单引号括起来 (') 。

默认情况下， Invoke-WebRequest 将结果返回给管道。若要将这些结果发送到文件和管道，请使用 Passthru 参数。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PreserveAuthorizationOnRedirect

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

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

此功能已在 PowerShell 6.0.0 中添加。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Proxy

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

Type:	Uri
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyCredential

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

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

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

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyUseDefaultCredentials

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

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Resume

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

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

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

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

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

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

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

此功能已在 PowerShell 6.1.0 中添加。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RetryIntervalSec

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

Type:	Int32
Position:	Named
Default value:	5
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 参数。

Type:	String
Aliases:	SV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipCertificateCheck

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

警告

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

此功能已在 PowerShell 6.0.0 中添加。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipHeaderValidation

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

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

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

此功能已在 PowerShell 6.0.0 中添加。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipHttpErrorCheck

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

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SslProtocol

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

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

注意

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

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

Type:	WebSslProtocol
Accepted values:	Default, Tls, Tls11, Tls12
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TimeoutSec

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

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

Type:	Int32
Position:	Named
Default value:	0
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Token

要包含在请求中的 OAuth 或持有者令牌。某些身份验证选项需要令牌。不能单独使用。

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

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

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

Type:	SecureString
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

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

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

Type:	Uri
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UseBasicParsing

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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)

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WebSession

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

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

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

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

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

Type:	WebRequestSession
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 和 HTTPS 请求的代理服务器的主机名或 IP 地址，以防 HTTP_PROXY 或 HTTPS_PROXY 未定义。
NO_PROXY：应从代理中排除的主机名的逗号分隔列表。

通过

Invoke-WebRequest

语法

说明

示例

示例 1：发送 Web 请求

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

示例 3：从网页获取链接

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

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

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

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

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

示例 9：跳过标头验证

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

参数

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-HttpVersion

-InFile

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-TimeoutSec

-Token

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

输出

备注

相关链接

其他资源