Invoke-RestMethod

参考

模块:: Microsoft.PowerShell.Utility

将 HTTP 或 HTTPS 请求发送到 RESTful Web 服务。

语法

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] 对象。

注意

当 REST 终结点返回多个对象时，对象将作为数组接收。如果通过管道将输出从 Invoke-RestMethod 传递给另一个命令，则会将其作为单个 [Object[]] 对象发送。该数组的内容不会为管道上的下一个命令枚举。

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

注意

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

示例

示例 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

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

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

当输入是一个 GET 请求且正文是 IDictionary（通常情况下是一个哈希表）时，会将正文作为查询参数添加到 URI 中。对于其他请求类型（如 POST），将正文按标准的“名称=值”格式设置为请求正文的值。

警告

POST 正文的详细输出将以 with -1-byte payload 结尾，即使正文的大小已知并在 Content-Length HTTP 标头中发送也是如此。

类型:	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-RestMethod 会将内容类型设置为“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
默认值:	Current user
必需:	False
接受管道输入:	False
接受通配符:	False

-DisableKeepAlive

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

类型:	SwitchParameter
Position:	Named
默认值:	KeepAlive
必需:	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

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

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

-OutFile

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

默认情况下，Invoke-RestMethod 将结果返回到管道。

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

-PassThru

仅当命令中还使用了 OutFile 参数时，此参数才有效。目的是将结果写入文件并写入管道。

注意

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

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

-ProxyUseDefaultCredentials

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

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

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

-SessionVariable

创建包含 Web 请求会话的变量。输入一个不带美元符号 ($) 的变量名称。

指定会话变量后，Invoke-RestMethod 将创建一个 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
默认值:	0
必需:	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)。此参数支持 HTTP、HTTPS、FTP 和 FILE 值。

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

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

-UseBasicParsing

指示 cmdlet 使用基本分析。该 cmdlet 返回 String 对象中的原始 HTML。

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

-UseDefaultCredentials

使用当前用户的凭据来发送 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、Internet Explorer、Opera 和 Safari。

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

-WebSession

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

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

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

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

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

输入

Object

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

输出

Int64

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

String

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

XmlDocument

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

PSObject

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

备注

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

irm

通过