Invoke-WebRequest

模块:

Microsoft.PowerShell.Utility

从 Internet 上的网页中获取内容。

语法

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>]

说明

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

此 cmdlet 是在 Windows PowerShell 3.0 中引入的。

注意

默认情况下，在分析网页来填充 ParsedHtml 属性时，可能会运行网页中的脚本代码。 使用 -UseBasicParsing 开关取消此操作。

重要

本文中的示例引用 contoso.com 域中的主机。 这是 Microsoft 在示例中使用的虚构域。 这些示例旨在说明如何使用 cmdlet。 但是，由于 contoso.com 网站不存在，因此这些示例不起作用。 将示例调整为你的环境中的主机。

示例

示例 1：发送 Web 请求

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

$Response = Invoke-WebRequest -UseBasicParsing -URI https://www.bing.com?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

返回 Invoke-WebRequest 的数据存储在变量中 $Response 。 响应的 InputFields 属性包含窗体字段。 Where-Object用于将窗体字段筛选为名称属性类似于“* 值”的窗体字段。 筛选后的结果通过管道传递给 Select-Object，用来选择 name 和 value 属性。

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

此示例显示了如何将 Invoke-WebRequest cmdlet 用于有状态的 Web 服务，例如 Facebook。

$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

第一个命令使用 Invoke-WebRequest cmdlet 发送登录请求。 该命令为 SessionVariable 参数的值指定值“FB”，并将结果保存在 $R 变量中。 完成该命令后，$R 变量将包含一个 HtmlWebResponseObject，$FB 变量将包含一个 WebRequestSession 对象。

Invoke-WebRequest cmdlet 登录到 Facebook 后，$R 变量中 Web 响应对象的 StatusDescription 属性将指示用户已成功登录。

示例 3：从网页获取链接

此命令将获取网页中的链接。

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

Invoke-WebRequest cmdlet 获取网页内容。 然后，返回的 HtmlWebResponseObject 的 Links 属性用于显示每个链接的 Href 属性。

示例 4：从 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
}

注意

若要使用 Start-ThreadJob cmdlet，必须从 PowerShell 库安装 ThreadJob 模块。

参数

-Body

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

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

当输入是一个 GET 请求且正文是 IDictionary（通常情况下是一个哈希表）时，会将正文作为查询参数添加到 URI 中。 对于其他请求类型（如 POST），将正文按标准的 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

• or -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[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

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

-ContentType

指定 Web 请求的内容类型。

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

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

-Credential

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

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

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

注意

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

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

-DisableKeepAlive

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

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

-Headers

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

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

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

-InFile

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

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

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

-MaximumRedirection

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

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

-Method

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

• Default
• Delete
• Get
• Head
• Merge
• Options
• Patch
• Post
• Put
• Trace

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

-OutFile

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

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

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

-PassThru

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

注意

使用 PassThru 参数时，输出将写入管道，但文件为空。 有关详细信息，请参阅 PowerShell 问题 #15409。

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

-ProxyUseDefaultCredentials

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

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

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

-SessionVariable

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

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

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

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

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

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

-TimeoutSec

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

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

类型:	Int32
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

-Uri

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

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

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

-UseBasicParsing

指示此 cmdlet 使用 HTML 内容的响应对象而不进行文档对象模型 (DOM) 解析。 当 Internet Explorer 未安装在计算机上（例如在 Windows Server 操作系统安装 Server Core）时，此参数是必需的。

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

-UseDefaultCredentials

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

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

-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 的用户代理字符串：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 请求会话中的值。

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

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

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

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

输入

Object

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

输出

HtmlWebResponseObject

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

备注

Windows PowerShell 包含 Invoke-WebRequest 的以下别名：

• iwr

相关链接

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