Invoke-RestMethod

参考

模块:: Microsoft.PowerShell.Utility

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

语法

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-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>
      [-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>
      [-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>
      [-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>]

说明

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 或在括号中包装。以下示例对 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

参数

-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

指定要用于请求的显式身份验证类型。默认值为“无”。 身份验证参数不能与 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 参数用于指定查询参数的列表，或用于指定响应的内容。

如果输入是 GET 请求，并且正文 IDictionary 通常是 (哈希表) ，则正文将作为查询参数添加到统一资源标识符 (URI) 。对于其他请求类型（如 POST），将正文按标准的“名称=值”格式设置为请求正文的值。

当正文是窗体，或者它是另一个 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)。输入证书的证书指纹。

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

若要获取证书指纹，请在 PowerShell Cert: 驱动器中使用 Get-Item 或 Get-ChildItem 命令。

注意

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContentType

指定 Web 请求的内容类型。

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

为 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 请求的标头。输入哈希表或字典。

若要设置 UserAgent 标头，请使用 UserAgent 参数。不能使用此参数指定 User-Agent 或 Cookie 标头。

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

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InFile

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

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

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

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

如果本地文件大小小于远程文件大小，则 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（含 400 到 599）或 304 时连接重试的间隔。另请参阅用于指定重试次数的 MaximumRetryCount 参数。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionVariable

创建一个包含 Web 请求会话的变量。输入不带美元符号的变量名称 ($) 符号。

指定会话变量时， Invoke-RestMethod 会创建一个 Web 请求会话对象，并将其分配给 PowerShell 会话中具有指定名称的变量。命令完成后可以立即在会话中使用该变量。

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

若要在后续的 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、 Headers 和 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 请求会话，请在命令的 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 请求的正文传递给 Invoke-RestMethod。

输出

System.Int64, System.String, System.Xml.XmlDocument

此 cmdlet 的输出取决于检索内容的格式。

PSObject

如果请求返回 JSON 字符串， Invoke-RestMethod 则返回表示字符串的 PSObject 。

备注

某些功能可能并非在所有平台上都可用。

由于 .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 和 HTTPS 请求的代理服务器的主机名或 IP 地址，以防 HTTP_PROXY 或 HTTPS_PROXY 未定义。
NO_PROXY：应从代理中排除的主机名的逗号分隔列表。

Share via

Invoke-RestMethod

语法

说明

示例

示例 1：获取 PowerShell RSS 源

示例 2：运行 POST 请求

示例 3：关注关系链接

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

示例 5：传递多个标头

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

参数

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-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

输入

输出

备注

相关链接

其他资源