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

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

-Certificate

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

若要查找证书，请使用 Get-PfxCertificate 或使用 Certificate (Cert:) 驱动器中的 Get-ChildItem 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

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。否则，将不会在调用中指定内容类型。

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

-Credential

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

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

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

注意

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

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
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

-Headers

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

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

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

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

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

-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

-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 对象，例如由 Get-Credential cmdlet 生成的用户名。

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

Type:	PSCredential
Position:	Named
Default value:	None
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

-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

-TimeoutSec

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

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

Type:	Int32
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、FTP 和 FILE 值。

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

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

-UseBasicParsing

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

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; 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)

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

-WebSession

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

若要在 Web 请求会话中重写某个值，请使用 cmdlet 参数，如 UserAgent 或 Credential。参数值优先于 Web 请求会话中的值。

若要创建 Web 请求会话，请在 Invoke-WebRequest 命令的 SessionVariable 参数的值中输入变量名称（不带美元符号）。 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。

输出

HtmlWebResponseObject

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

备注

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

iwr

通过

Invoke-WebRequest

语法

说明

示例

示例 1：发送 Web 请求

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

示例 3：从网页获取链接

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

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

参数

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

输出

备注

反馈

其他资源

通过

Invoke-WebRequest

语法

说明

示例

示例 1：发送 Web 请求

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

示例 3：从网页获取链接

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

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

参数

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

输出

备注

相关链接

反馈

其他资源