Invoke-RestMethod

语法

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

说明

Invoke-RestMethod cmdlet 将 HTTP 和 HTTPS 请求发送到返回丰富结构化数据的具象状态传输 (REST) Web 服务。

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

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

示例

示例 1：获取 PowerShell RSS 源

Invoke-RestMethod -Uri https://devblogs.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 cmdlet 获取来自 PowerShell 博客 RSS 源的信息。 此命令使用 Format-Table cmdlet 来显示 Title 的值和表中每篇博客的 pubDate 属性。

示例 2

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

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as
# the output mode, and specifies a time period for returned data that starts two days ago and ends
# one day ago. The body variable specifies values for parameters that apply to the particular REST
# API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file
# name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

示例 3：传递多个标头

此示例演示了如何将多个标头从 hash-table 传递到 REST API。

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

API 通常需要传递的标头来进行身份验证和验证等操作。

示例 3：提交表单数据

当正文是一个表单或是另一个 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.Forms[0]

示例 4：枚举管道上返回的项

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

参数

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

Object

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

输出

Int64

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

String

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

XmlDocument

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

PSObject

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

备注

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

• irm

相关链接

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest