Invoke-RestMethod

Invoke-RestMethod
    [-Uri] <Uri>
    [-Method <WebRequestMethod>]
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-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-RestMethod
    [-Uri] <Uri>
    -NoProxy
    [-Method <WebRequestMethod>]
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-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-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-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-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-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-RestMethod cmdlet 向返回丰富结构化数据的代表性状态传输 （REST） Web 服务发送 HTTP 和 HTTPS 请求。

PowerShell 基于数据类型设置响应的格式。 对于 RSS 或 ATOM 源，PowerShell 返回项或条目 XML 节点。 对于 JavaScript 对象表示法（JSON）或 XML，PowerShell 会将内容转换为 [PSCustomObject] 对象或反序列化。

此 cmdlet 在 Windows PowerShell 3.0 中引入。

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

此示例使用 Invoke-RestMethod cmdlet 从 PowerShell 博客 RSS 源获取信息。 该命令使用 Format-Table cmdlet 在表格中显示每个博客的 标题 和 pubDate 属性的值。

Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
  Format-Table -Property Title, pubDate

Title                                                                pubDate
-----                                                                -------
Join the PowerShell 10th Anniversary Celebration!                    Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release                               Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016                       Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources                                    Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery                                       Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon                                      Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release                                   Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934             Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source!                                 Thu, 18 Aug 2016 15:32:02 +0000

在此示例中，用户运行 Invoke-RestMethod 在用户的 Intranet 网站上执行 POST 请求。

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

系统会提示凭据输入凭据，然后存储在 中 $Cred ，并且将在 中定义将要访问的 URL 在 中 $Url定义。

$Body 变量描述搜索条件，将 CSV 指定为输出模式，并指定两天前开始且一天前结束的返回数据的时间段。 正文变量指定应用于 Invoke-RestMethod 通信的特定 REST API 的参数的值。

Invoke-RestMethod 命令将随所有变量一起运行，为生成的 CSV 输出文件指定路径和文件名。

根据 RFC5988，一些 REST API 支持通过关系链接进行分页。 可以让 cmdlet 执行此操作，而不是分析标头以获取下一页的 URL。 此示例从 PowerShell GitHub 存储库返回前两页的问题。

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

某些 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-RestMethod -Uri $Uri -Method Post -Form $Form

个人资料表单需要以下字段：firstName、lastName、email、avatar、birthday和 hobbies。 API 需要 avatar 域中提供用户个人资料图像。 API 还将接受以同一表单提交的多个 hobbies 条目。

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

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

通过向 hobbies 键提供列表， hobbies 该字段将出现在每个列表项的提交中一次。

API 通常需要传递的标头来进行身份验证或验证等操作。 此示例演示如何将多个标头从 hash-table 传递到 REST API。

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

GitHub 返回数组中的多个对象。 如果将输出通过管道传递给另一个命令，则会将其作为单个 [Object[]]对象发送。

若要将对象枚举到管道中，请通过管道将结果传递给 Write-Output 或用括号包装 cmdlet。 以下示例计算 GitHub 返回的对象数。 然后，对枚举到管道的对象数进行计数。

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1

$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30

$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30

默认情况下， Invoke-RestMethod cmdlet 验证具有标准定义值格式的已知标头的值。 以下示例演示如何此验证引发错误，以及如何使用 SkipHeaderValidation 参数来避免验证允许无效格式值的终结点的值。

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org 是一项服务，用于返回有关 Web 请求和响应的信息，以便进行故障排除。 $Uri 变量将分配给服务的 /headers 终结点，该终结点将请求的标头作为响应中的内容返回。

If-Match 请求标头在 RFC-7232 第 3.1 节 中定义，并要求使用周围引号定义该标头的值。 为 $InvalidHeaders 变量分配一个哈希表，其中 If-Match 的值无效，因为它被定义为 12345 而不是 "12345"。

调用具有无效标头的 Invoke-RestMethod 将返回错误报告，格式化值无效。 请求不会发送到终结点。

使用 Invoke-RestMethod 参数调用 将忽略验证失败并将请求发送到终结点。 由于终结点容忍不合规的标头值，因此 cmdlet 返回响应对象而不出错。

此示例使用 HTTP 2.0 协议查询 GitHub 问题。

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

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

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

当请求返回整数时，此 cmdlet 将返回该整数。

当请求返回字符串时，此 cmdlet 将返回该字符串。

当请求返回有效的 XML 时，此 cmdlet 将其作为 XmlDocument返回。

当请求返回 JSON 字符串时，此 cmdlet 返回表示数据的 PSObject。

PowerShell 包含以下与 Invoke-RestMethod相关的别名：

• 所有平台：
  • irm

某些功能可能无法在所有平台上使用。

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