Invoke-WebRequest

参考

模块:: Microsoft.PowerShell.Utility

从 Internet 上的网页获取内容。

语法

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-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>
      [-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>
      [-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>
      [-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 将 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 以选择 “名称” 和“ 值” 属性。

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

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

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

$Session

$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

$ProfileResponse

对的第一次调用 Invoke-WebRequest 发送登录请求。命令为 -SessionVariable 参数的值指定“Session”值，并将结果保存在变量中 $LoginResponse 。命令完成后，$LoginResponse变量包含，BasicHtmlWebResponseObject$Session变量包含 WebRequestSession 对象。这会将用户记录到站点中。

对 $Session 的调用本身显示 WebRequestSession 变量中的对象。

对的第二次 Invoke-WebRequest 调用提取用户的配置文件，这要求用户登录到站点。变量中存储的 $Session 会话数据用于向登录期间创建的站点提供会话 Cookie。结果保存在变量中 $ProfileResponse 。

对 $ProfileResponse 的调用本身会在变量中显示 BasicHtmlWebResponseObject 。

示例 3：从网页获取链接

此示例获取网页中的链接。它使用 Invoke-WebRequest cmdlet 获取网页内容。然后，它使用返回的 LinksBasicHtmlWebResponseObjectInvoke-WebRequest 属性和每个链接的 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、emailavatar、 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。

参数

-AllowUnencryptedAuthentication

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

警告

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

此功能已在 PowerShell 6.0.0 中添加。

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

-Authentication

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

可用的身份验证选项：

None：这是未提供 身份验证 时的默认选项。不会使用显式身份验证。
Basic：需要凭据。凭据将用于以格式base64(user:password)发送 RFC 7617 基本身份验证Authorization: Basic标头。
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 参数用于指定查询参数的列表，或用于指定响应的内容。

当输入为 GET 请求且正文通常为 IDictionary (哈希表) 时，会将正文作为查询参数添加到 URI 中。对于其他请求类型 (（如 POST) ），正文设置为标准 name=value 格式的请求正文的值。

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)。输入证书的证书指纹。

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

若要获取证书指纹，请在 PowerShell Cert: 驱动器中使用 Get-Item 或 Get-ChildItem 命令。

注意

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

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

-ContentType

指定 Web 请求的内容类型。

如果省略此参数并且请求方法是 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:	None
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 请求的标头。输入哈希表或字典。

若要设置 UserAgent 标头，请使用 UserAgent 参数。不能使用此参数指定 User-Agent 或 Cookie 标头。

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

Type:	IDictionary
Position:	Named
Default value:	None
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:	None
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:	None
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:	None
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， User@Domain.Com或输入 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:	None
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:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RetryIntervalSec

指定收到失败代码 400 到 599（含 400 到 599）或 304 时连接重试的间隔。另请参阅用于指定重试次数的 MaximumRetryCount 参数。

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

-SessionVariable

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

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

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

若要在后续的 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:	None
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:	None
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 响应头的值。此参数的可接受值为：

区块
压缩
Deflate
GZip
标识

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:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	None
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 请求的正文传递给 Invoke-WebRequest。

输出

BasicHtmlWebResponseObject

备注

从 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：应从代理中排除的主机名的逗号分隔列表。

Share via

Invoke-WebRequest

语法

说明

示例

示例 1：发送 Web 请求

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

示例 3：从网页获取链接

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

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

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

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

参数

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-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

输入

输出

备注

相关链接

其他资源