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 向返回丰富结构化数据的代表性状态传输 （REST） Web 服务发送 HTTP 和 HTTPS 请求。

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

注意

当 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 在表格中显示每个博客的 标题 和 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 （Get-ChildItem） 驱动器中的 Cert: 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 请求的内容类型。

如果 ContentType 的值包含编码格式（如 charset），则 cmdlet 使用该格式对 Web 请求的正文进行编码。 如果 ContentType 未指定编码格式，则改用默认编码格式。 一种具有编码格式的 ContentType 的示例是 text/plain; charset=iso-8859-5，它指定了 拉丁文/西里尔文 字母表。

如果省略参数，则内容类型可能因使用的 HTTP 方法而异：

• 对于 POST 方法，内容类型 application/x-www-form-urlencoded
• 对于 PUT 方法，内容类型 application/json
• 对于其他方法，在请求中未指定内容类型

如果使用 InFile 参数上传文件，则应设置内容类型。 通常，类型应 application/octet-stream。 但是，需要根据终结点的要求设置内容类型。

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

-Credential

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

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

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

注意

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

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

-DisableKeepAlive

将 HTTP 标头中的 KeepAlive 值设置为 False。 默认情况下，KeepAlive 为 True。 KeepAlive 建立与服务器的持久连接，以促进后续请求。

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

-Headers

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

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

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

-InFile

从文件获取 Web 请求正文的内容。 输入路径和文件名。 如果省略路径，则默认值为当前位置。

还需要设置请求的内容类型。 例如，若要上传文件，应设置内容类型。 通常，类型应 application/octet-stream。 但是，需要根据终结点的要求设置内容类型。

类型:	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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0，每个操作系统和平台都有细微的变化。

若要使用大多数 Internet 浏览器使用的标准用户代理字符串测试网站，请使用 PSUserAgent 类的属性，例如 Chrome、Firefox、InternetExplorer、Opera 和 Safari。

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

-WebSession

指定 Web 请求会话。 输入变量名称，包括美元符号（$）。

若要替代 Web 请求会话中的值，请使用 cmdlet 参数，例如 UserAgent 或 Credential。 参数值优先于 Web 请求会话中的值。

与远程会话不同，Web 请求会话不是永久性连接。 它是一个对象，其中包含有关连接和请求的信息，包括 Cookie、凭据、最大重定向值和用户代理字符串。 可以使用它在 Web 请求之间共享状态和数据。

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

相关链接

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