Invoke-RestMethod
将 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>]
说明
cmdlet 将 Invoke-RestMethod
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 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]
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-Item
Windows 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 请求的方法。 此参数的可接受值为:
- Default
- 删除
- 获取
- 头
- 合并
- 选项
- 修补程序
- 邮递
- 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 秒的值,则可能需要 15 秒或更多时间才能引发 WebException,并且请求超时。
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 请求会话不是持续性连接。 它是一个包含有关连接和请求的信息的对象,包括 Cookie、凭据、最大重定向值和用户代理字符串。 可用于共享 Web 请求之间的状态和数据。
若要创建 Web 请求会话,请在命令的 参数Invoke-RestMethod
值-SessionVariable
中输入不带美元符号 (变量名称) 。
Invoke-RestMethod
创建会话并将其保存在 变量中。
在后续命令中,使用 变量作为 参数的值 -WebSession
。
不能在同一 -SessionVariable
命令中使用 和 -WebSession
参数。
Type: | WebRequestSession |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
输入
可以通过管道将 Web 请求的正文传递给 Invoke-RestMethod
。
输出
System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String
此 cmdlet 的输出取决于检索内容的格式。
PSObject
如果请求返回 JSON 字符串, Invoke-RestMethod
则返回表示字符串的 PSObject。