首页
酷软
游戏
媒体
- 电影
- 剧集
- 动画
- 记录
- 综艺
- MV
- 有声世界
云资源
源码
更多
- 文库
- 系统
- web
- 站长帮
- 玩电脑
- 玩游戏
- 玩手机
- 涨姿势
- 玩软件
- 云图志
- 看漫画
- 微读书
- PS玩家
- 网文网语
- 硬件数码
- 编程开发
- 神秘之旅
- 福利线报
- 商业资源
- 网赚相关
- 健康加油站
赞助专区
云盘专区
资源阁
缘聚岛
BT种子库

[玩转系统] 调用 RestMethod (Microsoft.PowerShell.Utility)

作者：精品下载站日期：2024-12-14 02:05:39 浏览：13 分类：玩电脑

调用 RestMethod (Microsoft.PowerShell.Utility)

Invoke-RestMethod

模块：Microsoft.PowerShell.Utility

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

句法

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 向表述性状态传输 (REST) Web 服务发送 HTTP 和 HTTPS 请求，这些服务返回丰富的结构化数据。

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 支持由环境变量定义的代理配置。请参阅本文的注释部分。

从 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 为输出模式，并指定返回数据的时间段（从两天前开始到一天前结束）。 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      = '[email protected]'
    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 > 和爱好。 API 期望在avatar 字段中提供用户个人资料图片的图像。 API 还将接受以同一表单提交的多个爱好条目。

创建 $Form 哈希表时，键名称用作表单字段名称。默认情况下，哈希表的值将转换为字符串。如果存在 System.IO.FileInfo 值，则将提交文件内容。如果存在数组或列表等集合，则表单字段将被多次提交。

通过在 avatar 键上使用 Get-Item，FileInfo 对象将被设置为值。结果是 jdoe.png 的图像数据将被提交。

通过向 hobbies 键提供列表，hobbies 字段将在每个列表项的提交中出现一次。

示例 5：传递多个标头

API 通常需要传递标头来进行身份验证或验证。此示例演示如何将多个标头从哈希表传递到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

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-AllowUnencryptedAuthentication

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

警告

使用此参数不安全，不建议使用。提供它只是为了与无法提供加密连接的旧系统兼容。使用风险自负。

此功能是在 PowerShell 6.0.0 中添加的。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-Authentication

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

可用的身份验证选项：

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

提供身份验证会覆盖提供给标头或包含在WebSession中的任何授权标头。

此功能是在 PowerShell 6.0.0 中添加的。

类型：

Web认证类型

接受的值：

无、基本、不记名、OAuth

位置：

命名

默认值：

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 或 提供的任何与内容相关的标头strong>WebSession 参数将被 MultipartFormDataContent 对象的内容标头覆盖。此功能是在 PowerShell 6.0.0 中添加的。

类型：

目的

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

True

接受通配符：

False

-Certificate

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

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

类型：

X509证书

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-CertificateThumbprint

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

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

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

笔记

目前仅 Windows 操作系统平台支持此功能。

类型：

String

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-ConnectionTimeoutSeconds

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

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

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

类型：

整数32

别名：

TimeoutSec

位置：

命名

默认值：

必需的：

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。否则，调用中不会指定内容类型。

当为 Body 提供 MultipartFormDataContent 对象时，ContentType 将被覆盖。

从 PowerShell 7.4 开始，如果您同时使用此参数和 Headers 参数来定义 Content-Type 标头，则在 ContentType 中指定的值> 使用参数。

类型：

String

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-Credential

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

输入用户名，例如 User01 或 Domain01\User01，或输入由 Get-Credential cmdlet。

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

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

笔记

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

类型：

PS凭证

位置：

命名

默认值：

当前用户

必需的：

False

接受管道输入：

False

接受通配符：

False

-CustomMethod

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

例子：

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

这会向 API 发出 TEST HTTP 请求。

此功能是在 PowerShell 6.0.0 中添加的。

类型：

String

别名：

位置：

命名

默认值：

None

必需的：

True

接受管道输入：

False

接受通配符：

False

-DisableKeepAlive

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

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-FollowRelLink

指示 cmdlet 应遵循关系链接。

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

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

此功能是在 PowerShell 6.0.0 中添加的。

类型：

SwitchParameter

别名：

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-Form

将字典转换为 multipart/form-data 提交。表单不得与正文一起使用。如果 ContentType 将被忽略。

字典的键将用作表单字段名称。默认情况下，表单值将转换为字符串值。

如果该值为 System.IO.FileInfo 对象，则将提交二进制文件内容。文件名将作为文件名提交。 MIME 将设置为 application/octet-stream。 Get-Item 可用于简化提供 System.IO.FileInfo 对象。

$Form=@{ 简历=Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

如果value是集合类型，比如Array或者List，for字段会被提交多次。默认情况下，列表的值将被视为字符串。如果该值为 System.IO.FileInfo 对象，则将提交二进制文件内容。不支持嵌套集合。

$Form=@{ 标签='假期', '意大利', '2017' 图片=Get-ChildItem 'c:\Users\jdoe\Pictures\2017-意大利' }

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

此功能是在 PowerShell 6.1.0 中添加的。

类型：

词典

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-Headers

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

当为 Body 提供 MultipartFormDataContent 对象时，与内容相关的标头（例如 Content-Type）将被覆盖。

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

类型：

词典

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-HttpVersion

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

有效值为：

类型：

版本

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-InFile

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

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

类型：

String

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-MaximumFollowRelLink

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

类型：

整数32

别名：

位置：

命名

默认值：

Int32.MaxValue

必需的：

False

接受管道输入：

False

接受通配符：

False

-MaximumRedirection

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

类型：

整数32

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-MaximumRetryCount

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

类型：

整数32

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-Method

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

Default

Delete

Get

Head

Merge

Options

Patch

Post

Put

Trace

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

类型：

Web请求方法

接受的值：

默认、获取、标题、发布、放置、删除、跟踪、选项、合并、修补

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-NoProxy

指示 cmdlet 将不使用代理来到达目标。

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

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

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

True

接受管道输入：

False

接受通配符：

False

-OperationTimeoutSeconds

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

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

类型：

整数32

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-OutFile

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

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

从 PowerShell 7.4 开始，您可以指定不带文件名的文件夹路径。执行此操作后，该命令将在任何重定向后使用已解析 URI 最后一段的文件名。当您为 OutFile 指定文件夹路径时，无法使用 Resume 参数。

类型：

String

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-PassThru

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

笔记

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

类型：

SwitchParameter

位置：

命名

默认值：

无输出

必需的：

False

接受管道输入：

False

接受通配符：

False

-PreserveAuthorizationOnRedirect

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

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

此功能是在 PowerShell 6.0.0 中添加的。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-PreserveHttpMethodOnRedirect

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

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

此功能是在 PowerShell 7.4 中添加的。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-Proxy

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

此功能是在 PowerShell 6.0.0 中添加的。

类型：

乌里

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-ProxyCredential

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

输入用户名，例如 User01 或 Domain01\User01、[email protected]，或输入 PSCredential 对象，例如由 Get-Credential cmdlet 生成的对象。

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

类型：

PS凭证

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-ProxyUseDefaultCredentials

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

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

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-ResponseHeadersVariable

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

此功能是在 PowerShell 6.0.0 中添加的。

类型：

String

别名：

RHV

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-Resume

尽最大努力尝试恢复下载部分文件。 Resume 参数需要 OutFile 参数。

恢复仅对本地文件和远程文件的大小进行操作，并且不执行其他验证本地文件和远程文件是否相同的操作。

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

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

如果本地文件大小大于远程文件大小，则本地文件将被覆盖，整个远程文件将被完全重新下载。此行为与使用不带 Resume 的 OutFile 相同。

如果远程服务器不支持断点续传，则本地文件将被覆盖，整个远程文件将被完全重新下载。此行为与使用不带 Resume 的 OutFile 相同。

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

此功能是在 PowerShell 6.1.0 中添加的。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-RetryIntervalSec

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

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

类型：

整数32

位置：

命名

默认值：

必需的：

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

别名：

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-SkipCertificateCheck

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

警告

使用此参数不安全，不建议使用。此开关仅适用于使用自签名证书进行测试的已知主机。使用风险自负。

此功能是在 PowerShell 6.0.0 中添加的。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-SkipHeaderValidation

指示 cmdlet 应向请求添加标头而不进行验证。

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

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

此功能是在 PowerShell 6.0.0 中添加的。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-SkipHttpErrorCheck

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

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

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-SslProtocol

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

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

笔记

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

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

类型：

WebSSL协议

接受的值：

默认、Tls、Tls11、Tls12、Tls13

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-StatusCodeVariable

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

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

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

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

类型：

String

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-Token

要包含在请求中的 OAuth 或承载令牌。某些身份验证选项需要令牌。它不能独立使用。

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

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

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

类型：

SecureString

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-TransferEncoding

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

分块
压缩
放气
压缩包
身份

类型：

String

接受的值：

分块、压缩、放气、gzip、身份

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-UnixSocket

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

此参数是在 PowerShell 7.4 中添加的。

类型：

UnixDomainSocketEndPoint

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

-Uri

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

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

类型：

乌里

位置：

默认值：

None

必需的：

True

接受管道输入：

False

接受通配符：

False

-UseBasicParsing

该参数已被弃用。从 PowerShell 6.0.0 开始，所有 Web 请求仅使用基本解析。包含此参数只是为了向后兼容，对其的任何使用都不会影响 cmdlet 的操作。

类型：

SwitchParameter

位置：

命名

默认值：

False

必需的：

False

接受管道输入：

False

接受通配符：

False

-UseDefaultCredentials

指示 cmdlet 使用当前用户的凭据发送 Web 请求。这不能与身份验证或凭据一起使用，并且可能并非所有平台都支持。

类型：

SwitchParameter

位置：

命名

默认值：

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

位置：

命名

默认值：

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 参数。

类型：

网络请求会话

位置：

命名

默认值：

None

必需的：

False

接受管道输入：

False

接受通配符：

False

输入

对象

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

输出

Int64

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

字符串

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

Xml文档

当请求返回有效的 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 压缩算法的支持。