Invoke-WebRequest

Invoke-WebRequest
    [-Uri] <Uri>
    [-UseBasicParsing]
    [-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
    [-Uri] <Uri>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    [-UseBasicParsing]
    [-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>]
    [-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
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

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

PowerShell 3.0 中引入了此 cmdlet。

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

此示例使用 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 属性类似于 的任何 InputField"* Value"。 筛选后的结果通过管道传递给 Select-Object，用来选择 Name 和 Value 属性。

此示例显示如何将 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 调用本身在变量中显示 the BasicHtmlWebResponseObject 。

此示例获取网页中的链接。 它使用 Invoke-WebRequest cmdlet 获取网页内容。 然后，它使用返回的 的 BasicHtmlWebResponseObjectInvoke-WebRequestLinks 属性和每个链接的 Href 属性。

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

此示例使用 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。

此示例使用 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'

某些 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、email、avatar、birthday和 hobbies。 API 需要 avatar 域中提供用户个人资料图像。 该 API 还接受以同一形式提交多个 hobbies 条目。

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

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

将一个列表提供给 hobbies 键后，提交中每个列表项都会显示一次 hobbies 字段。

当 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。

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。

可以通过管道将 Web 请求的正文传递给 Invoke-WebRequest。

从 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 请求 HTTP_PROXY 上使用的代理服务器的主机名或 IP 地址，以防是否 HTTPS_PROXY 定义或未定义。
• NO_PROXY：应从代理中排除的主机名的逗号分隔列表。