Invoke-RestMethod

参考

模块:: Microsoft.PowerShell.Utility

将 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、emailavatar、 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 6750 Authorization: Bearer 标头。
OAuth：需要 Token 参数。使用提供的令牌发送 RFC 6750 Authorization: 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各VacationItaly提供一次。该 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。

有效值为：

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

输入

Object

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

输出

Int64

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

String

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

XmlDocument

当请求返回有效的 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：应从代理中排除的主机名的逗号分隔列表。

通过

Invoke-RestMethod

语法

说明

示例

示例 1：获取 PowerShell RSS 源

示例 2：运行 POST 请求

示例 3：关注关系链接

示例 4：简化的多部分/表单数据提交

示例 5：传递多个标头

示例 6：枚举管道上返回的项

示例 7：跳过标头验证

示例 8：使用 HTTP 2.0 发送请求

参数

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-HttpVersion

-InFile

-MaximumFollowRelLink

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-ResponseHeadersVariable

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-StatusCodeVariable

-TimeoutSec

-Token

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

输出

备注

相关链接

其他资源