Invoke-RestMethod
将 HTTP 或 HTTPS 请求发送到 RESTful Web 服务。
语法
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
说明
cmdlet Invoke-RestMethod
将 HTTP 和 HTTPS 请求发送到返回丰富结构化数据的 REST) Web 服务的代表性状态传输 (。
PowerShell 根据数据类型设置响应格式。 对于 RSS 或 ATOM 源,PowerShell 返回 Item 或 Entry XML 节点。 对于 javaScript 对象表示法 (JSON) 或 XML,PowerShell 会将内容 [PSCustomObject]
转换为对象或将其反序列化。
注意
当 REST 终结点返回多个对象时,对象将作为数组接收。 如果将 的 Invoke-RestMethod
输出通过管道传递给另一个命令,则它将作为单个 [Object[]]
对象发送。 不会为管道上的下一个命令枚举该数组的内容。
此 cmdlet 是在 Windows PowerShell 3.0 中引入的。
从 PowerShell 7.0 开始, Invoke-RestMethod
支持环境变量定义的代理配置。 请参阅本文的 “备注 ”部分。
示例
示例 1:获取 PowerShell RSS 源
此示例使用 Invoke-RestMethod
cmdlet 从 PowerShell 博客 RSS 源获取信息。 命令使用 Format-Table
cmdlet 在表中显示每个博客的 Title 和 pubDate 属性的值。
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
示例 2:运行 POST 请求
在此示例中,用户运行 Invoke-RestMethod
以在用户组织的 Intranet 网站上执行 POST 请求。
$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
output_mode = "csv"
earliest_time = "-2d@d"
latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv
系统会提示输入凭据,然后将凭据存储在 中 $Cred
,并且将在 中 $Url
定义要访问的 URL。
变量 $Body
描述搜索条件,将 CSV 指定为输出模式,并指定两天前开始到一天前结束的返回数据的时间段。 body 变量指定参数的值,这些参数适用于与之 Invoke-RestMethod
通信的特定 REST API。
该 Invoke-RestMethod
命令使用所有变量就地运行,为生成的 CSV 输出文件指定路径和文件名。
示例 3:关注关系链接
某些 REST API 支持通过每个 RFC5988的关系链接进行分页。 可以让 cmdlet 为你执行此操作,而不是分析标头以获取下一页的 URL。 此示例返回 PowerShell GitHub 存储库中的前两页问题。
$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2
示例 4:简化的多部分/表单数据提交
某些 API 需要 multipart/form-data
提交才能上传文件和混合内容。 此示例演示如何更新用户的配置文件。
$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
firstName = 'John'
lastName = 'Doe'
email = 'john.doe@contoso.com'
avatar = Get-Item -Path 'c:\Pictures\jdoe.png'
birthday = '1980-10-15'
hobbies = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form
配置文件窗体需要以下字段:firstName
、、lastName
、email
avatar
、 birthday
和 hobbies
。 API 要求在 字段中提供 avatar
用户配置文件图片的图像。 API 还将接受要以同一窗体提交的多个 hobbies
条目。
创建 $Form
HashTable 时,键名称用作窗体字段名称。 默认情况下,HashTable 的值将转换为字符串。 如果存在 System.IO.FileInfo
值,则将提交文件内容。 如果存在数组或列表等集合,则将多次提交表单字段。
Get-Item
通过在 键上使用 avatar
,FileInfo
对象将设置为 值。 结果是将提交 的图像 jdoe.png
数据。
通过向 hobbies
键提供列表,字段 hobbies
将出现在每个列表项的提交中一次。
示例 5:传递多个标头
API 通常需要传递的标头进行身份验证或验证。 此示例演示如何将多个标头从 hash-table
传递到 REST API。
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
示例 6:枚举管道上返回的项
GitHub 在数组中返回多个对象。 如果通过管道将输出传递给另一个命令,则会将其作为单个 [Object[]]
对象发送。
若要将对象枚举到管道中,请通过管道将结果传递给 Write-Output
cmdlet,或用括号将 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
示例 7:跳过标头验证
默认情况下, Invoke-RestMethod
cmdlet 验证具有标准定义值格式的已知标头的值。 以下示例演示此验证如何引发错误,以及如何使用 SkipHeaderValidation 参数来避免验证允许无效格式值的终结点的值。
$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
'If-Match' = '12345'
}
Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders
Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
Format-List
Invoke-RestMethod: The format of value '12345' is invalid.
headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
10.0.19044; en-US) PowerShell/7.2.5; X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}
httpbin.org 是一项服务,可返回有关 Web 请求和响应的信息,以便进行故障排除。 变量 $Uri
分配给 /headers
服务的 终结点,该终结点将请求的标头作为其响应中的内容返回。
请求 If-Match
标头在 RFC-7232 第 3.1 节 中定义,并要求使用括在引号中定义该标头的值。 变量 $InvalidHeaders
被赋予一个哈希表,其中 的值 If-Match
无效,因为它定义为 12345
而不是 "12345"
。
使用无效标头调用 Invoke-RestMethod
将返回错误,报告格式化的值无效。 请求不会发送到终结点。
使用 SkipHeaderValidation 参数调用 Invoke-RestMethod
将忽略验证失败并将请求发送到终结点。 由于终结点允许不合规的标头值,因此 cmdlet 返回响应对象而不会出错。
示例 8:使用 HTTP 2.0 发送请求
此示例使用 HTTP 2.0 协议查询 GitHub 问题。
$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck
参数
-AllowUnencryptedAuthentication
允许通过未加密的连接发送凭据和机密。 默认情况下,使用不以 https://
开头的 URI 提供凭据或任何身份验证选项将导致错误,并且请求将中止,以防止无意中通过未加密的连接以纯文本形式传达机密。 若要自担风险替代此行为,请提供 AllowUnencryptedAuthentication 参数。
警告
使用此参数不安全,不建议使用。 它仅用于与无法提供加密连接的旧系统兼容。 使用风险自担。
此功能已在 PowerShell 6.0.0 中添加。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Authentication
指定要用于请求的显式身份验证类型。 默认值为“无”。 Authentication 参数不能与 UseDefaultCredentials 参数一起使用。
可用的身份验证选项:
None
:如果未提供 身份验证 ,这是默认选项。 不会使用显式身份验证。Basic
:需要 凭据。 凭据将用于发送格式为 的base64(user:password)
RFC 7617 基本身份验证Authorization: Basic
标头。Bearer
:需要 Token 参数。 使用提供的令牌发送 RFC 6750Authorization: Bearer
标头。OAuth
:需要 Token 参数。 使用提供的令牌发送 RFC 6750Authorization: Bearer
标头。
提供身份验证会Authorization
替代提供给标头或包含在 WebSession 中的任何标头。
此功能已在 PowerShell 6.0.0 中添加。
Type: | WebAuthenticationType |
Accepted values: | None, Basic, Bearer, OAuth |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Body
指定请求的正文。 正文是请求的内容,位于标头之后。
还可以通过管道将正文值传递给 Invoke-RestMethod
。
可以将 Body 参数用于指定查询参数的列表,或用于指定响应的内容。
当输入为 POST 请求且正文为 String 时,第一个等号左侧的值 (=
) 设置为表单数据中的键,其余文本设置为值。 若要指定多个键,请将 IDictionary 对象(如哈希表)用于 Body。
如果输入是 GET 请求,并且正文是 IDictionary (通常为哈希表) ,则正文将作为查询参数添加到 URI 中。 对于其他请求类型 ((如 PATCH) ),正文设置为标准 name=value
格式的请求正文的值,值 URL 编码。
当输入为 System.Xml 时。XmlNode 对象和 XML 声明指定一个编码,该编码用于请求中的数据,除非由 ContentType 参数重写。
当正文是窗体,或者它是另一个 Invoke-WebRequest
调用的输出时,PowerShell 会将请求内容设置为表单字段。
Body 参数还可以接受 System.Net.Http.MultipartFormDataContent 对象。 这将促进 multipart/form-data
请求。 为 Body 提供 MultipartFormDataContent 对象时,提供给 ContentType、Headers 或 WebSession 参数的任何内容相关标头将由对象的内容标头MultipartFormDataContent
替代。 此功能已在 PowerShell 6.0.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
或 Get-ChildItem
命令在 中 Cert:\CurrentUser\My
查找证书。
注意
此功能目前仅在 Windows OS 平台上受支持。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ContentType
指定 Web 请求的内容类型。
如果 ContentType 的值包含 (为 charset
) 的编码格式,则 cmdlet 使用该格式对 Web 请求的正文进行编码。 如果 ContentType 未指定编码格式,则改用默认编码格式。 具有编码格式的 ContentType 的一个示例是 text/plain; charset=iso-8859-5
,它指定 拉丁文/西里尔文 字母表。
如果省略此参数并且请求方法是 POST, Invoke-RestMethod
则将内容类型设置为 application/x-www-form-urlencoded
。 否则,不会在调用中指定内容类型。
为 Body 提供 对象时MultipartFormDataContent
,将重写 ContentType。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Credential
指定有权发送请求的用户帐户。 默认为当前用户。
键入用户名,例如 User01 或 Domain01\User01,或输入 cmdlet Get-Credential
生成的 PSCredential 对象。
凭据 可以单独使用,也可以与某些 身份验证 参数选项结合使用。 单独使用时,仅当远程服务器发送身份验证质询请求时,它才会向远程服务器提供凭据。 与 身份验证 选项一起使用时,将显式发送凭据。
凭据存储在 PSCredential 对象中,密码存储为 SecureString。
注意
有关 SecureString 数据保护的详细信息,请参阅 SecureString 的安全性如何?。
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CustomMethod
指定用于 Web 请求的自定义方法。 这可以用于终结点所需的请求方法不是 方法上的可用选项。 方法和CustomMethod 不能一起使用。
例如:
Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
这会向 API 发出 TEST
HTTP 请求。
此功能已在 PowerShell 6.0.0 中添加。
Type: | String |
Aliases: | CM |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-DisableKeepAlive
指示 cmdlet 将 HTTP 标头中的 KeepAlive 值设置为 False。 默认情况下,KeepAlive 为 True。 KeepAlive 建立到服务器的持续性连接,以促进后续请求。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FollowRelLink
指示 cmdlet 应遵循关系链接。
某些 REST API 支持通过每个 RFC5988的关系链接进行分页。 可以让 cmdlet 为你执行此操作,而不是分析标头以获取下一页的 URL。 若要设置跟踪关系链接的次数,请使用 MaximumFollowRelLink 参数。
使用此开关时,cmdlet 返回结果页的集合。 每页结果可能包含多个结果项。
此功能已在 PowerShell 6.0.0 中添加。
Type: | SwitchParameter |
Aliases: | FL |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Form
将字典转换为 multipart/form-data
提交。 Form 不能与 Body 一起使用。
如果 将忽略 ContentType 。
字典的键将用作窗体字段名称。 默认情况下,窗体值将转换为字符串值。
如果值为 System.IO.FileInfo 对象,则将提交二进制文件内容。
文件的名称将作为 filename
提交。 MIME 将设置为 application/octet-stream
。 Get-Item
可用于简化 System.IO.FileInfo 对象的提供。
$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
如果值是集合类型(如 Array 或 List),则将多次提交 for 字段。 默认情况下,列表的值将被视为字符串。 如果值为 System.IO.FileInfo 对象,则将提交二进制文件内容。 不支持嵌套集合。
$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
在上面的示例中, tags
字段将在 窗体中提供三次,每个 、 和 2017
各Vacation
Italy
提供一次。 该 pictures
字段还将为文件夹中的每个文件 2017-Italy
提交一次。 该文件夹中文件的二进制内容将作为值提交。
此功能已在 PowerShell 6.1.0 中添加。
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Headers
指定 Web 请求的标头。 输入哈希表或字典。
为 Body 提供对象时MultipartFormDataContent
,将重写内容相关的标头,例如 Content-Type
。
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-HttpVersion
指定用于请求的 HTTP 版本。 默认为 1.1
。
有效值为:
- 1.0
- 1.1
- 2.0
- 3.0
Type: | Version |
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 |
-MaximumFollowRelLink
指定在使用 FollowRelLink 时跟踪关系链接的次数。 如果 REST API 由于请求过多而受到限制,则可能需要较小的值。 默认值为 [Int32]::MaxValue
。 值为 0 (零) 会阻止以下关系链接。
Type: | Int32 |
Aliases: | ML |
Position: | Named |
Default value: | Int32.MaxValue |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
指定在连接失败之前 PowerShell 将连接重定向到备用统一资源标识符 (URI) 的次数。 默认值为 5。 值为 0(零)将阻止所有重定向。
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRetryCount
指定收到 400 到 599(含或 304)之间的失败代码时 PowerShell 重试连接的次数。 另请参阅 RetryIntervalSec 参数,以指定两次重试的秒数。
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Method
指定用于 Web 请求的方法。 此参数的可接受值为:
Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace
CustomMethod 参数可用于上面未列出的请求方法。
Type: | WebRequestMethod |
Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoProxy
指示 cmdlet 不会使用代理到达目标。
如果需要绕过 Internet Explorer 中配置的代理或环境中指定的代理,请使用此开关。
此参数是在 PowerShell 6.0 中引入的。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutFile
将响应正文保存在指定的输出文件中。 输入路径和文件名。 如果省略路径,则默认路径为当前位置。 该名称被视为文本路径。 包含方括号 ([]
) 的名称必须用单引号括起来 ('
) 。
默认情况下, Invoke-RestMethod
将结果返回到管道。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
仅当命令中还使用了 OutFile 参数时,此参数才有效。 目的是将结果写入文件和管道。
注意
使用 PassThru 参数时,输出将写入管道,但不会创建文件。 有关详细信息,请参阅 PowerShell 问题 #15409。
Type: | SwitchParameter |
Position: | Named |
Default value: | No output |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
指示 cmdlet 应在存在时跨重定向保留 Authorization
标头。
默认情况下,cmdlet 在重定向前会 Authorization
去除标头。 如果标头需要发送到重定向位置,则指定此参数会禁用此逻辑。
此功能已在 PowerShell 6.0.0 中添加。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
对请求使用代理服务器,而不是直接连接到 Internet 资源。 输入网络代理服务器的统一资源标识符 (URI) 。
此功能已在 PowerShell 6.0.0 中添加。
Type: | Uri |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
指定有权使用由 Proxy 参数指定的代理服务器的用户帐户。 默认为当前用户。
键入用户名,如 User01 或 Domain01\User01, User@Domain.Com或输入 PSCredential
对象,例如 cmdlet Get-Credential
生成的对象。
仅当命令中也使用 Proxy 参数时,此参数才有效。 不能在同一命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 参数。
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
指示 cmdlet 使用当前用户的凭据访问 Proxy 参数指定的代理服务器。
仅当命令中也使用 Proxy 参数时,此参数才有效。 不能在同一命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 参数。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ResponseHeadersVariable
创建一个包含响应标头字典的变量。 输入不带美元符号的变量名称 ($
) 符号。 字典的键包含 Web 服务器返回的响应标头的字段名称和值。
此功能已在 PowerShell 6.0.0 中添加。
Type: | String |
Aliases: | RHV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Resume
尽最大努力尝试继续下载部分文件。 Resume 参数需要 OutFile 参数。
恢复 仅对本地文件和远程文件的大小进行操作,不执行本地文件和远程文件是否相同的其他验证。
如果本地文件大小小于远程文件大小,则 cmdlet 将尝试继续下载文件并将剩余字节追加到文件的末尾。
如果本地文件大小与远程文件大小相同,则不会执行任何操作,并且 cmdlet 假定下载已完成。
如果本地文件大小大于远程文件大小,则将覆盖本地文件,并完全重新下载整个远程文件。 此行为与使用不带 Resume 的 OutFile 相同。
如果远程服务器不支持恢复下载,则将覆盖本地文件,并且将完全重新下载整个远程文件。 此行为与使用不带 Resume 的 OutFile 相同。
如果本地文件不存在,则会创建本地文件,并完全下载整个远程文件。 此行为与使用不带 Resume 的 OutFile 相同。
此功能已在 PowerShell 6.1.0 中添加。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RetryIntervalSec
指定收到失败代码 400 和 599(含 304)时连接重试间隔。 值必须介于 和 [int]::MaxValue
之间1
。
另请参阅用于指定重试次数的 MaximumRetryCount 参数。
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
创建一个包含 Web 请求会话的变量。 输入不带美元符号的变量名称 ($
) 符号。
指定会话变量时, Invoke-RestMethod
会创建一个 Web 请求会话对象,并将其分配给 PowerShell 会话中具有指定名称的变量。 命令完成后可以立即在会话中使用该变量。
在 PowerShell 7.4 之前,Web 请求会话不是永久性连接。 它是一个对象,其中包含有关连接和请求的信息,包括 Cookie、凭据、最大重定向值和用户代理字符串。 可用于共享 Web 请求之间的状态和数据。
从 PowerShell 7.4 开始,只要会话的属性未在后续请求中重写,Web 请求会话就会持久。 如果存在,cmdlet 会使用新值重新创建会话。 持久会话可减少重复请求的开销,使其速度更快。
若要在后续的 Web 请求中使用 Web 请求会话,请在 WebSession 参数的值中指定会话变量。 建立新连接时,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 |
-SkipCertificateCheck
跳过包含所有验证的证书验证检查,例如过期、吊销、受信任的根颁发机构等。
警告
使用此参数不安全,不建议使用。 此开关仅用于对使用自签名证书进行测试的已知主机。 使用风险自担。
此功能已在 PowerShell 6.0.0 中添加。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHeaderValidation
指示 cmdlet 应在不进行验证的情况下向请求添加标头。
此开关应用于需要不符合标准的标头值的网站。 指定此开关将禁用验证,以允许未选中传递值。 指定后,无需验证即可添加所有标头。
这将禁用对传递给 ContentType、 标头和 UserAgent 参数的值的验证。
此功能已在 PowerShell 6.0.0 中添加。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHttpErrorCheck
此参数会导致 cmdlet 忽略 HTTP 错误状态并继续处理响应。 错误响应会像成功一样写入管道。
此参数是在 PowerShell 7 中引入的。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SslProtocol
设置 Web 请求允许的 SSL/TLS 协议。 默认情况下,允许系统支持的 SSL/TLS 协议。 SslProtocol 允许限制为符合性目的的特定协议。
这些值定义为基于标志的枚举。 可以使用此参数将多个值组合在一起以设置多个标志。 这些值可以作为值数组或这些值的逗号分隔字符串传递给 SslProtocol 参数。 cmdlet 将使用二进制 OR 操作合并这些值。 将值作为数组传递是最简单的选项,还允许对值使用 Tab 补全。 你可能无法在所有平台上提供多个值。
注意
在非 Windows 平台上,可能无法提供 Tls
或 Tls12
作为选项。 并非所有操作系统都提供对 Tls13
的支持,需要根据每个操作系统进行验证。
此功能已在 PowerShell 6.0.0 中添加,PowerShell 7.1 中添加了对 Tls13
的支持。
Type: | WebSslProtocol |
Accepted values: | Default, Tls, Tls11, Tls12, Tls13 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StatusCodeVariable
创建一个包含请求的 HTTP 状态代码结果的变量。 输入不带美元符号的变量名称 ($
) 符号。
与 SkipHttpErrorCheck 参数一起使用时,参数可以标识成功消息或失败消息。
以字符串的形式输入参数的变量名称,例如 -StatusCodeVariable "scv"
。
此参数是在 PowerShell 7 中引入的。
Type: | String |
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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Token
要包含在请求中的 OAuth 或持有者令牌。 某些身份验证选项需要令牌。 不能单独使用。
令牌 采用 SecureString
包含令牌的 。 若要提供令牌,请手动使用以下内容:
Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
此参数是在 PowerShell 6.0 中引入的。
Type: | SecureString |
Position: | Named |
Default value: | None |
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
此参数已弃用。 从 PowerShell 6.0.0 开始,所有 Web 请求仅使用基本分析。 包含此参数只是为了向后兼容,对它的任何使用都不会影响 cmdlet 的操作。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseDefaultCredentials
指示 cmdlet 使用当前用户的凭据发送 Web 请求。 这不能与 身份验证 或 凭据 一起使用,并且可能并非在所有平台上都受支持。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WebSession
指定一个 Web 请求会话。 输入变量名称,包括美元符号 ($
) 。
若要在 Web 请求会话中重写某个值,请使用 cmdlet 参数,如 UserAgent 或 Credential。 参数值优先于 Web 请求会话中的值。 为 Body 提供 MultipartFormDataContent 对象时,内容相关的标头(如 Content-Type
)也会被重写。
与远程会话不同,Web 请求会话不是永久性连接。 它是一个对象,其中包含有关连接和请求的信息,包括 Cookie、凭据、最大重定向值和用户代理字符串。 可用于共享 Web 请求之间的状态和数据。
若要创建 Web 请求会话,请在命令的 SessionVariable 参数 Invoke-RestMethod
值中输入变量名称(不带美元符号)。 Invoke-RestMethod
创建会话并将其保存在 变量中。 在后续命令中,将该变量用作 WebSession 参数的值。
不能在同一命令中使用 SessionVariable 和 WebSession 参数。
Type: | WebRequestSession |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
输入
可以通过管道将 Web 请求的正文传递给此 cmdlet。
输出
当请求返回整数时,此 cmdlet 将返回该整数。
当请求返回字符串时,此 cmdlet 将返回该字符串。
当请求返回有效的 XML 时,此 cmdlet 将它作为 XmlDocument 返回。
PSObject
当请求返回 JSON 字符串时,此 cmdlet 将返回表示数据的 PSObject 。
备注
PowerShell 包含以下别名 Invoke-RestMethod
:
- 所有平台:
irm
某些功能可能并非在所有平台上都可用。
由于 .NET Core 3.1 中的更改,PowerShell 7.0 及更高版本使用 HttpClient.DefaultProxy 属性来确定代理配置。
此属性的值是不同的规则,具体取决于你的平台:
- 对于 Windows:从环境变量读取代理配置,如果未定义,则从用户的代理设置读取代理配置。
- 对于 macOS:从环境变量读取代理配置,如果未定义,则从系统的代理设置读取代理配置。
- 对于 Linux:从环境变量读取代理配置,如果未定义这些配置,此属性将初始化绕过所有地址的非配置实例。
基于 Windows 和 Unix 的平台上用于 DefaultProxy
初始化的环境变量是:
HTTP_PROXY
:用于 HTTP 请求的代理服务器的主机名或 IP 地址。HTTPS_PROXY
:用于 HTTPS 请求的代理服务器的主机名或 IP 地址。ALL_PROXY
:在未定义或未定义的情况下HTTP_PROXY
,用于 HTTP 和 HTTPS 请求的代理服务器的主机名或HTTPS_PROXY
IP 地址。NO_PROXY
:应从代理中排除的主机名的逗号分隔列表。