Invoke-WebRequest

语法

Default （默认值）

Invoke-WebRequest
    [-UseBasicParsing]
    [-Uri] <Uri>
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-Method <WebRequestMethod>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [<CommonParameters>]

说明

示例

示例 1：发送 Web 请求

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

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

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

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the Form.
$Form.fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective Form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method POST -Body $Form.Fields
$R.StatusDescription

示例 3：从网页获取链接

(Invoke-WebRequest -Uri "https://devblogs.microsoft.com/powershell/").Links.Href

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

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

404

参数

-Body

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

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

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

当正文是窗体，或者它是 Invoke-WebRequest 调用的输出时，PowerShell 会将请求内容设置为窗体字段。 例如：

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms\[0\].Name = "MyName" $r.Forms\[0\].Password = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $r

• 或 -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[0\]

参数属性

参数集

-Certificate

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

若要查找证书，请使用 Get-PfxCertificate 或使用 Get-ChildItem（）驱动器中的 Cert: cmdlet。 如果证书无效或没有足够的颁发机构，命令将失败。

参数属性

参数集

-CertificateThumbprint

指定有权发送请求的用户帐户的数字公钥证书（X509）。 输入证书的证书指纹。证书用于基于客户端证书的身份验证。 它们只能映射到本地用户帐户;它们不适用于域帐户。

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

参数属性

参数集

-ContentType

指定 Web 请求的内容类型。

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

参数属性

参数集

-Credential

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

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

参数属性

参数集

-DisableKeepAlive

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

参数属性

参数集

-Headers

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

若要设置 UserAgent 标头，请使用 UserAgent 参数。 不能使用此参数来指定 UserAgent 或 cookie 标头。

参数属性

参数集

-InFile

从文件获取 Web 请求的内容。

输入路径和文件名。 如果省略路径，则默认值为当前位置。

参数属性

参数集

-MaximumRedirection

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

参数属性

参数集

-Method

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

• 违约
• 删除
• 获取
• 头
• 合并
• 选项
• 补丁
• 发布
• Put
• 跟踪

参数属性

参数集

-OutFile

指定此 cmdlet 保存响应正文的输出文件。 输入路径和文件名。 如果省略路径，则默认值为当前位置。

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

参数属性

参数集

-PassThru

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

参数属性

参数集

-Proxy

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

参数属性

参数集

-ProxyCredential

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

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

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

参数属性

参数集

-ProxyUseDefaultCredentials

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

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

参数属性

参数集

-SessionVariable

指定此 cmdlet 为其创建 Web 请求会话并将其保存在值的变量。 输入没有美元符号（$）符号的变量名称。

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

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

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

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

参数属性

参数集

-TimeoutSec

指定请求在超时之前可以等待多长时间。以秒为单位输入值。 默认值为0，指定无限期超时。

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

参数属性

参数集

-TransferEncoding

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

• Chunked
• 压缩
• Deflate
• GZip
• 身份

参数属性

参数集

-Uri

指定 Web 请求发送到的 Internet 资源的统一资源标识符（URI）。 输入 URI。 此参数支持 HTTP、HTTPS、FTP 和 FILE 值。

此参数是必需的。

参数属性

参数集

-UseBasicParsing

指示该 cmdlet 在不使用文档对象模型（DOM）分析的情况下对 HTML 内容使用响应对象。 如果未在计算机上安装 Internet Explorer，例如在 Windows Server 操作系统的服务器核心安装上，则需要此参数。

参数属性

参数集

-UseDefaultCredentials

指示 cmdet 使用当前用户的凭据发送 Web 请求。

参数属性

参数集

-UserAgent

指定 Web 请求的用户代理字符串。 默认用户代理类似于 Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0，每个操作系统和平台都有细微的变化。

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

参数属性

参数集

-WebSession

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

若要替代 Web 请求会话中的值，请使用 cmdlet 参数，例如 UserAgent 或 Credential。 参数值优先于 Web 请求会话中的值。

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

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

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

参数属性

参数集

CommonParameters

输入

Object

输出

HtmlWebResponseObject

相关链接

• Invoke-RestMethod
• ConvertFrom-Json
• ConvertTo-Json