Invoke-RestMethod

参考

模块:: Microsoft.PowerShell.Utility

将 HTTP 或 HTTPS 请求发送到 RESTful Web 服务。

语法

Invoke-RestMethod
      [-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]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-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]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-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]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-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]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

说明

Invoke-RestMethod cmdlet 将 HTTP 和 HTTPS 请求发送到返回丰富结构化数据的具象状态传输 (REST) Web 服务。

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

注意

当 REST 终结点返回多个对象时，对象将作为数组接收。如果通过管道将输出从 Invoke-RestMethod 传递给另一个命令，则会将其作为单个 [Object[]] 对象发送。该数组的内容不会为管道上的下一个命令枚举。

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

从 PowerShell 7.0 开始，Invoke-RestMethod 支持环境变量定义的代理配置。请参阅本文说明部分。

从 PowerShell 7.4 开始，请求的字符编码默认为 UTF-8 而不是 ASCII。如果需要不同的编码，则必须在 Content-Type 标头中设置 charset 属性。

示例

示例 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 指定为输出模式，并指定两天前开始且一天前结束的返回数据的时间段。正文变量指定应用于 Invoke-RestMethod 通信的特定 REST API 的参数的值。

Invoke-RestMethod 命令将随所有变量一起运行，为生成的 CSV 输出文件指定路径和文件名。

示例 3：跟踪关系链接

根据 RFC5988，一些 REST API 支持通过关系链接进行分页。可以让 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 值，则会提交文件内容。如果存在数组或列表等集合，则表单域将多次提交。

通过在 avatar 键上使用 Get-Item ，将 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。以下示例计算 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

示例 9：向 Unix 套接字应用程序发送请求

某些应用程序（如 Docker）公开用于通信的 Unix 套接字。此示例使用 Docker API 查询 Docker 映像列表。该 cmdlet 使用 Unix 套接字连接到 Docker 守护程序。

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

参数

-AllowInsecureRedirect

允许从 HTTPS 重定向到 HTTP。默认情况下，从 HTTPS 重定向到 HTTP 的任何请求都会导致错误，并且该请求被中止，以防止无意中以纯文本形式通过未加密的连接进行通信。若要自行重写此行为，请使用 AllowInsecureRedirect 参数。

此参数已在 PowerShell 7.4 中添加。

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

-AllowUnencryptedAuthentication

允许通过未加密的连接发送凭据和机密。默认情况下，向 Authentication 或任何 Authentication 选项提供不以 https:// 开头的 Uri 将导致错误，并且请求将中止，以防止无意中通过未加密的连接以纯文本方式传达机密。若要自行重写此行为，请提供 AllowUnencryptedAuthentication 参数。

警告

使用此参数不安全，不建议这样做。它仅用于与无法提供加密连接的旧系统兼容。使用时需要自控风险。

此功能在 PowerShell 6.0.0 中添加。

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

-Authentication

指定要用于请求的显式身份验证类型。默认值为“无”。 Authentication 参数不能与 UseDefaultCredentials 参数一起使用。

可用的身份验证选项：

None：未提供 Authentication 时，这是默认选项。不会使用显式身份验证。
Basic：需要指定 Credential。凭据将用于以 base64(user:password) 格式发送 RFC 7617 基本身份验证 Authorization: Basic 标头。
Bearer：需要指定 Token 参数。使用提供的令牌发送 RFC 6750 Authorization: Bearer 标头。
OAuth：需要指定 Token 参数。使用提供的令牌发送 RFC 6750 Authorization: Bearer 标头。

提供 Authentication 会重写提供给 Headers 或包含在 WebSession 中的任何 Authorization 标头。

此功能在 PowerShell 6.0.0 中添加。

类型:	WebAuthenticationType
接受的值:	None, Basic, Bearer, OAuth
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Body

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

可以将 Body 参数用于指定查询参数的列表，或用于指定响应的内容。对于查询参数，cmdlet 使用 System.Net.WebUtility.UrlEncode 方法对键值对进行编码。有关 URL 编码字符串的详细信息，请参阅 UrlEncode（）方法参考。

当输入是 POST 请求，正文是 String 时，第一个等号 (=) 左侧的值将设置为表单数据中的键，其余文本设置为值。若要指定多个键，请对 Body 使用 IDictionary 对象，例如哈希表。

当输入是一个 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 中添加。

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

若要查看证书指纹，请使用Get-Item或Get-ChildItem命令查找证书。Cert:\CurrentUser\My

注意

此功能目前仅在 Windows OS 平台上受支持。

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

-ConnectionTimeoutSeconds

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

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

此参数替换了 PowerShell 7.4 中的 TimeoutSec 参数。可以使用 TimeoutSec 作为 ConnectionTimeoutSeconds 的别名。

类型:	Int32
别名:	TimeoutSec
Position:	Named
默认值:	0
必需:	False
接受管道输入:	False
接受通配符:	False

-ContentType

指定 Web 请求的内容类型。

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

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

当为主体提供 MultipartFormDataContent 对象时，将重写 ContentType。

从 PowerShell 7.4 开始，如果使用此参数和标头参数来定义 Content-Type 标头，将使用 ContentType 参数中指定的值。

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

-Credential

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

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

Credential 可以单独使用，也可以与某些 Authentication 参数选项结合使用。单独使用时，仅当远程服务器发送身份验证质询请求时，它才会向远程服务器提供凭据。与 Authentication 选项一起使用时，将显式发送凭据。

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

注意

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

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

-CustomMethod

指定用于 Web 请求的自定义方法。这可与终结点所需的请求方法一起使用，在 Method 上不可用。 Method 和 CustomMethod 不能一起使用。

示例：

Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

这会向 API 发出 TEST HTTP 请求。

此功能在 PowerShell 6.0.0 中添加。

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

-DisableKeepAlive

指示 cmdlet 将 HTTP 标头中的 KeepAlive 值设置为 False。默认情况下，KeepAlive 为 True。 KeepAlive 可建立到服务器的持续性连接，以便处理后续请求。

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

-FollowRelLink

指示 cmdlet 应跟踪关系链接。

根据 RFC5988，一些 REST API 支持通过关系链接进行分页。可以让 cmdlet 执行此操作，而不是分析标头以获取下一页的 URL。若要设置要跟踪关系链接的次数，请使用 MaximumFollowRelLink 参数。

使用此开关时，cmdlet 将返回结果页的集合。每个结果页可能包含多个结果项。

此功能在 PowerShell 6.0.0 中添加。

类型:	SwitchParameter
别名:	FL
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	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' }

如果值是集合类型（如数组或列表），则表单域将提交多次。默认情况下，列表的值将被视为字符串。如果值为 System.IO.FileInfo 对象，则将提交二进制文件内容。不支持嵌套集合。

$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

在上面的示例中，tags 域将以表单形式提供三次，Vacation、Italy 和 2017 各一次。 pictures 域也将为 2017-Italy 文件夹中的每个文件提交一次。该文件夹中文件的二进制内容将作为值提交。

此功能在 PowerShell 6.1.0 中添加。

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

-Headers

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

为主体提供 MultipartFormDataContent 对象时，将重写与内容相关的标头，例如 Content-Type。

从 PowerShell 7.4 开始，如果使用此参数定义 Content-Type 标头并使用 ContentType 参数，将使用 ContentType 参数中指定的值。

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

-HttpVersion

指定用于请求的 HTTP 版本。默认为 1.1。

有效值为：

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

-InFile

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

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

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

-MaximumFollowRelLink

指定使用 FollowRelLink 时要跟踪关系链接的次数。如果 REST API 由于请求过多而受到限制，可能需要较小的值。默认值是 [Int32]::MaxValue。值为 0 （零）会阻止跟踪关系链接。

类型:	Int32
别名:	ML
Position:	Named
默认值:	Int32.MaxValue
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumRedirection

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

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

-MaximumRetryCount

指定当收到 400 到 599（包括 400 和 599）或 304 之间的故障代码时，PowerShell 重试连接的次数。另请参阅 RetryIntervalSec 参数，以指定重试之间的秒数。

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

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

CustomMethod 参数可用于上面未列出的请求方法。

类型:	WebRequestMethod
接受的值:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-NoProxy

指示 cmdlet 不会使用代理访问目标。

当需要绕过 Internet Explorer 中配置的代理或环境中指定的代理时，请使用此开关。

此参数是在 PowerShell 6.0 中引入的。

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

-OperationTimeoutSeconds

此超时适用于流中读取的数据，不适用于整个流时间。默认值 0 指定无限超时。

将值设置为 30 秒意味着流中的数据之间的任何延迟超过 30 秒会终止请求。除非流停止超过 30 秒，否则下载需要几分钟才能终止的大型文件。

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

-OutFile

默认情况下，Invoke-RestMethod 将结果返回到管道。使用 OutFile 参数时，结果将保存到指定的文件中，而不返回到管道。输入路径和文件名。若要将结果发送到文件和管道，请添加 PassThru 参数。

如果省略路径，则默认路径为当前位置。该名称被视为文本路径。包含方括号 ([]) 的名称必须用单引号 (') 括起来。

从 PowerShell 7.4 开始，可以指定不包含文件名的文件夹路径。执行此操作时，该命令会在任何重定向后使用解析 URI 的最后一段的文件名。如果为 OutFile 指定了文件夹路径，则不能使用 Resume 参数。

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

-PassThru

仅当命令中还使用了 OutFile 参数时，此参数才有效。目的是将结果写入文件并写入管道。

注意

使用 PassThru 参数时，输出将写入管道，但未创建该文件。 PowerShell 7.5-preview.4 中已修复此问题。有关详细信息，请参阅 PowerShell 问题 #15409。

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

-PreserveAuthorizationOnRedirect

指示 cmdlet 应在重定向之间保留 Authorization 标头（如果存在）。

默认情况下，cmdlet 在重定向之前会去除 Authorization 标头。如果需要将标头发送到重定向位置，则指定此参数将禁用此逻辑。

此功能在 PowerShell 6.0.0 中添加。

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

-PreserveHttpMethodOnRedirect

指示 cmdlet 应保留跨重定向的请求的方法。

默认情况下，cmdlet 在重定向时将方法更改为 GET。指定此参数会禁用此逻辑，以确保预期方法可用于重定向。

此功能在 PowerShell 7.4 中添加。

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

-Proxy

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

此功能在 PowerShell 6.0.0 中添加。

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

-ProxyCredential

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

键入用户名（如 User01 或 Domain01\User01、User@Domain.Com）或输入 PSCredential 对象，例如由 Get-Credential cmdlet 生成的对象。

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

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

-ProxyUseDefaultCredentials

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

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

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

-ResponseHeadersVariable

创建包含响应标头字典的变量。输入一个不带美元符号 ($) 的变量名称。字典的键包含 Web 服务器返回的响应标头的域名称和值。

此功能在 PowerShell 6.0.0 中添加。

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

-Resume

尽最大努力继续下载部分文件。 Resume 参数需要 OutFile 参数。

Resume 仅对本地文件和远程文件的大小进行操作，而不执行本地文件与远程文件相同的其他验证。

如果本地文件大小小于远程文件大小，则 cmdlet 将尝试恢复下载文件并将剩余的字节追加到文件末尾。

如果本地文件大小与远程文件大小相同，则不执行任何操作，并且 cmdlet 假定下载已完成。

如果本地文件大小大于远程文件大小，则将覆盖本地文件，并且将完全重新下载整个远程文件。此行为与在没有 Resume 的情况下使用 OutFile 相同。

如果远程服务器不支持下载恢复，则将覆盖本地文件，并且将完全重新下载整个远程文件。此行为与在没有 Resume 的情况下使用 OutFile 相同。

如果本地文件不存在，则将创建本地文件，并且将完全下载整个远程文件。此行为与在没有 Resume 的情况下使用 OutFile 相同。

此功能在 PowerShell 6.1.0 中添加。

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

-RetryIntervalSec

指定当收到 400 到 599（包括 400 和 599）或 304 之间的故障代码时连接重试之间的间隔。该值必须在 1 和 [int]::MaxValue 之间。当失败代码为 429 并且响应在其标头中包含 Retry-After 属性时，即使指定了此参数，该 cmdlet 也会将该值用于重试间隔。

另请参阅 MaximumRetryCount 参数，以指定重试次数。

类型:	Int32
Position:	Named
默认值:	5
必需:	False
接受管道输入:	False
接受通配符:	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 参数。

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

-SkipCertificateCheck

跳过证书验证检查，包括所有验证，例如过期、吊销、受信任的根机构等。

警告

使用此参数不安全，不建议这样做。此开关仅用于使用自签名证书对已知主机进行测试。使用时需要自控风险。

此功能在 PowerShell 6.0.0 中添加。

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

-SkipHeaderValidation

指示 cmdlet 应在未验证的情况下向请求添加标头。

此开关应用于需要不符合标准的标头值的网站。指定此开关将禁用验证，以允许未经检查地传递值。指定后，将添加所有标头而不进行验证。

这将禁用传递给 ContentType、Headers 和 UserAgent 参数的值的验证。

此功能在 PowerShell 6.0.0 中添加。

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

-SkipHttpErrorCheck

此参数会导致 cmdlet 忽略 HTTP 错误状态并继续处理响应。错误响应被写入管道，就好像它们成功了一样。

在 PowerShell 7 中引入了此参数。

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

-SslProtocol

设置 Web 请求允许的 SSL/TLS 协议。默认情况下，允许系统支持的所有 SSL/TLS 协议。 SslProtocol 允许出于合规目的限制为特定协议。

这些值定义为基于标志的枚举。可以使用此参数将多个值组合在一起以设置多个标志。可以将值以值数组或这些值的逗号分隔字符串形式传递给 SslProtocol 参数。该 cmdlet 将使用二进制或运算合并这些值。将值作为数组传递是最简单的选项，此选项还支持对值使用 Tab 自动补全。可能无法在所有平台上提供多个值。

注意

在非 Windows 平台上，可能无法提供 Tls 或 Tls12 作为选项。对 Tls13 的支持并非在所有操作系统上都可用，需要根据每个操作系统进行验证。

此功能已添加到 PowerShell 6.0.0 中，并在 PowerShell 7.1 中添加了对 Tls13 的支持。

类型:	WebSslProtocol
接受的值:	Default, Tls, Tls11, Tls12, Tls13
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-StatusCodeVariable

创建包含请求的 HTTP 状态代码结果的变量。输入一个不带美元符号 ($) 的变量名称。

当与 SkipHttpErrorCheck 参数一起使用时，该参数可以标识成功消息或失败消息。

以字符串形式输入参数的变量名称，如 -StatusCodeVariable "scv"。

在 PowerShell 7 中引入了此参数。

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

-Token

要包含在请求中的 OAuth 或持有者令牌。某些 Authentication 选项需要 Token。它不能单独使用。

Token 采用包含令牌的 SecureString。若要提供令牌，请手动使用以下项：

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

此参数是在 PowerShell 6.0 中引入的。

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

-TransferEncoding

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

Chunked
压缩
Deflate
GZip
标识

类型:	String
接受的值:	chunked, compress, deflate, gzip, identity
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-UnixSocket

指定要连接到的 Unix 套接字的名称。基于 Unix 的系统和 Windows 版本 1803 及更高版本支持此参数。有关 Windows 对 Unix 套接字的支持的详细信息，请参阅 Windows/WSL 互操作与AF_UNIX 博客文章。

此参数已在 PowerShell 7.4 中添加。

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

-Uri

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

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

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

-UseBasicParsing

此参数已弃用。从 PowerShell 6.0.0 开始，所有 Web 请求仅使用基本分析。此参数仅用于后向兼容性，任何对它的使用都不会影响 cmdlet 的操作。

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

-UseDefaultCredentials

指示此 cmdlet 使用当前用户的凭据来发送 Web 请求。这不能与 Authentication 或 Credential 一起使用，并且可能不是所有平台都支持。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	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 请求会话中的值。为 Body 提供 MultipartFormDataContent 对象时，也会重写与内容相关的标头（如 Content-Type）。

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

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

备注

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 或 HTTPS_PROXY，则为用于 HTTP 和 HTTPS 请求的代理服务器的主机名或 IP 地址。
NO_PROXY：应从代理中排除的主机名的逗号分隔列表。

PowerShell 7.4 添加了对 Brotli 压缩算法的支持。

通过

Invoke-RestMethod

语法

说明

示例

示例 1：获取 PowerShell RSS 源

示例 2：运行 POST 请求

示例 3：跟踪关系链接

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

示例 5：传递多个标头

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

示例 7：跳过标头验证

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

示例 9：向 Unix 套接字应用程序发送请求

参数

-AllowInsecureRedirect

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ConnectionTimeoutSeconds

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-HttpVersion

-InFile

-MaximumFollowRelLink

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OperationTimeoutSeconds

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-PreserveHttpMethodOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-ResponseHeadersVariable

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-StatusCodeVariable

-Token

-TransferEncoding

-UnixSocket

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

输入

输出

备注

相关链接

其他资源