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 服务。

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

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

注意

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

示例

示例 1：获取 PowerShell RSS 源

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 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：传递多个标头

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

API 通常需要通过的标头进行身份验证、验证等。

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

参数

-Body

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

该 -Body 参数可用于指定查询参数列表或指定响应的内容。

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

警告： POST 正文的详细输出将结束 with -1-byte payload，即使正文的大小都是已知并在 HTTP 标头中发送的 Content-Length 。

当正文是窗体或它是另一Invoke-WebRequest个调用的输出时，Windows PowerShell将请求内容设置为窗体字段。

例如：

$R = Invoke-WebRequest $R.Forms https://website.com/login.aspx [0]。Name = “MyName” $R.Forms[0]。Password = “MyPassword” Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Certificate

指定用于安全的 Web 请求的客户端证书。输入一个包含证书的变量，或可获取该证书的命令或表达式。

若要查找证书，请使用 Get-PfxCertificate 或使用 Get-ChildItem 证书 () Cert: 驱动器中的 cmdlet。如果证书无效或不具有足够的权限，则该命令将失败。

Type:	X509Certificate
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CertificateThumbprint

指定有权发送请求的用户帐户的数字公钥证书 (X509)。输入证书的证书指纹。

在基于客户端证书的身份验证中使用证书。证书只能映射到本地用户帐户，而不适用于域帐户。

若要获取证书指纹，请使用Get-ItemWindows PowerShell () Cert: 驱动器中的或Get-ChildItem命令。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContentType

指定 Web 请求的内容类型。

如果省略此参数并且请求方法为 POST， Invoke-RestMethod 请将内容类型设置为“application/x-www-form-urlencoded”。否则，将不会在调用中指定内容类型。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

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

键入用户名，如“User01”或“Domain01\User01”；或输入 PSCredential 对象，如 Get-Credential cmdlet 生成的一个 PSCredential 对象。

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableKeepAlive

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

Type:	SwitchParameter
Position:	Named
Default value:	KeepAlive
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Headers

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

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

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InFile

从文件中获取 Web 请求的内容。

请输入路径和文件名。如果省略路径，则默认路径为当前位置。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRedirection

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

Type:	Int32
Position:	Named
Default value:	5
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Method

指定用于 Web 请求的方法。此参数的可接受值为：

默认
删除
获取
头
合并
选项
修补程序
邮递
Put
跟踪

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	Default
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutFile

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

默认情况下， Invoke-RestMethod 将结果返回到管道。若要将结果发送到文件和管道，请使用 -Passthru 参数。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

除了将结果写入文件外，还将返回结果。仅当命令中还使用了 -OutFile 参数时，此参数才有效。

Type:	SwitchParameter
Position:	Named
Default value:	No output
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Proxy

使用该请求的代理服务器，而不是直接连接到 Internet 资源。输入网络代理服务器的 URI。

Type:	Uri
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyCredential

指定有权使用参数指定的代理服务器的 -Proxy 用户帐户。默认为当前用户。

键入用户名，如“User01”或“Domain01\User01”；或输入 PSCredential 对象，如 Get-Credential cmdlet 生成的一个 PSCredential 对象。

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

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyUseDefaultCredentials

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

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionVariable

创建一个 Web 请求会话，并将其保存在指定变量的值中。输入没有美元符号的变量名称 ($) 符号。

指定会话变量时，Invoke-RestMethod创建 Web 请求会话对象，并将其分配给Windows PowerShell会话中具有指定名称的变量。命令完成后可以立即在会话中使用该变量。

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

若要在后续 Web 请求中使用 Web 请求会话，请在参数的值 -WebSession 中指定会话变量。在建立新连接时，Windows PowerShell 将使用 Web 请求会话对象中的数据。若要替代 Web 请求会话中的值，请使用 cmdlet 参数，例如 -UserAgent 或 -Credential。参数值优先于 Web 请求会话中的值。

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

Type:	String
Aliases:	SV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TimeoutSec

指定请求在超时之前可以挂起多长时间。以秒为单位输入值。默认值 0 指定无限超时。

域名系统 (DNS) 查询最多可能需要 15 秒才能返回或超时。如果请求包含需要解析的主机名，并且将 TimeoutSec 设置为大于零的值，但小于 15 秒，则引发 WebException 之前可能需要 15 秒或更长的时间，并且请求超时。

Type:	Int32
Position:	Named
Default value:	0
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TransferEncoding

指定传输编码 HTTP 响应头的值。此参数的可接受值为：

分块
压缩
Deflate
GZip
标识

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

指定将 Web 请求发送到的 Internet 资源的统一资源标识符 (URI)。此参数支持 HTTP、HTTPS、FTP 和 FILE 值。

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

Type:	Uri
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UseBasicParsing

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseDefaultCredentials

使用当前用户的凭据来发送 Web 请求。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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。

例如，以下命令将用户代理字符串用于 Internet

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]：：InternetExplorer)

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WebSession

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

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

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