Invoke-RestMethod

參考

模組:: Microsoft.PowerShell.Utility

將 HTTP 或 HTTPS 要求傳送至 RESTful Web 服務。

Syntax

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>]

Description

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 支援環境變數所定義的 Proxy 組態。請參閱本文的附註一節。

從 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 ，在用戶組織中的內部網路網站上執行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 指定為輸出模式，並指定兩天前開始且一天前結束之傳回數據的時間間隔。本文變數會指定套用至通訊之特定 REST API Invoke-RestMethod 的參數值。

命令 Invoke-RestMethod 會使用所有變數就地執行，並指定所產生 CSV 輸出檔的路徑和檔名。

範例 3：遵循關聯連結

某些 REST API 支援透過每個RFC5988的關聯連結進行分頁。您可以讓 Cmdlet 為您執行此動作，而不是剖析標頭以取得下一頁的 URL。此範例會從PowerShell GitHub存放庫傳回前兩頁的問題。

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

範例 4：簡化的多部分/表單數據提交

某些 API 需要 multipart/form-data 提交才能上傳檔案和混合內容。此範例示範如何更新使用者的配置檔。

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form

設定檔案表單需要下列欄位： firstName、 lastName、 email、 avatar、、 birthday和 hobbies。 API 預期會在欄位中提供 avatar 使用者配置檔圖片的影像。 API 也會接受要以相同形式提交的多個 hobbies 專案。

建立 $Form HashTable時，索引鍵名稱會當做表單域名稱使用。根據預設，HashTable 的值會轉換成字串。 System.IO.FileInfo如果值存在，則會提交檔案內容。如果陣列或清單等集合存在，則會多次提交表單域。

藉由在Get-Itemavatar索引鍵上使用，物件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 會驗證具有標準ards 定義值格式之已知標頭的值。下列範例示範此驗證如何引發錯誤，以及如何使用 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中新增。

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

-AllowUnencryptedAuthentication

允許透過未加密連線傳送認證和秘密。根據預設，以未開頭https://的 URI 提供 Credential 或任何驗證選項會導致錯誤，而且要求會中止，以防止非預期地透過未加密連線在純文字中通訊秘密。若要以您自己的風險覆寫此行為，請提供 AllowUnencryptedAuthentication 參數。

警告

使用此參數並不安全，不建議使用。它僅適用於無法提供加密連線的舊版系統相容性。以您自己的風險使用。

此功能已在PowerShell 6.0.0中新增。

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

-Authentication

指定要用於要求的明確驗證類型。預設值為 None。 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 時，第一個等號= （）左邊的值會設定為窗體數據的索引鍵，而其餘的文字會設定為值。若要指定多個索引鍵，請使用 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中新增。

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

-Certificate

指定用於安全 Web 要求的客戶端憑證。輸入包含憑證的變數，或取得憑證的命令或表達式。

若要尋找憑證，請使用 Get-PfxCertificate 或使用 Get-ChildItem Certificate （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

-ConnectionTimeoutSeconds

指定要求逾時之前可以擱置的時間長度。以秒為單位輸入值。預設值 0 會指定無限期逾時。

功能變數名稱系統（DNS）查詢最多可能需要 15 秒才能傳回或逾時。如果您的要求包含需要解析的主機名，而且您將連線 ionTimeoutSeconds 設定為大於零的值，但小於 15 秒，則擲回 WebException 之前可能需要 15 秒以上的時間，而且您的要求逾時。

此參數取代 了 PowerShell 7.4 中的 TimeoutSec 參數。您可以使用 TimeoutSec 作為連線 ionTimeoutSeconds 的別名。

Type:	Int32
Aliases:	TimeoutSec
Position:	Named
Default value:	0
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContentType

指定 Web 要求的內容類型。

如果 ContentType 的值包含編碼格式（as 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 參數中指定的值。

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'

這會對 TEST API 提出 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 提交。表單不得與 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字段會在窗體中提供三次，每個、 Italy和 2017各Vacation提供一次。欄位 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 。

從 PowerShell 7.4 開始，如果您使用此參數來定義Content-Type標頭並使用 ContentType 參數，則會使用 ContentType 參數中指定的值。

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 不會使用 Proxy 來連線到目的地。

當您需要略過 Internet Explorer 中所設定的 Proxy，或環境中指定的 Proxy 時，請使用此參數。

此參數是在 PowerShell 6.0 中引進的。

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-OperationTimeoutSeconds

此逾時適用於數據流內的數據讀取，而不是整個數據流時間。預設值 0 會指定無限期逾時。

將值設定為 30 秒，表示數據流中的數據之間任何超過 30 秒的延遲都會終止要求。除非串流停止超過 30 秒，否則下載需要幾分鐘才能終止的大型檔案。

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

-OutFile

將回應本文儲存在指定的輸出檔中。輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。名稱會被視為常值路徑。包含方括弧（[]）的名稱必須以單引號（'）括住。

根據預設， Invoke-RestMethod 會將結果傳回至管線。

從 PowerShell 7.4 開始，您可以指定沒有檔名的資料夾路徑。當您這麼做時，檔案的名稱是從解析 URI 的最後一個區段擷取到任何重新導向之後。當您指定 OutFile 的資料夾路徑時，無法使用 Resume 參數。

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

-PreserveHttpMethodOnRedirect

指出 Cmdlet 應該跨重新導向保留要求的方法。

根據預設，Cmdlet 會在重新導向時將方法變更為 GET 。指定此參數會停用此邏輯，以確保預定的方法可以與重新導向搭配使用。

此功能已在PowerShell 7.4中新增。

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

-Proxy

使用 Proxy 伺服器進行要求，而不是直接連線到因特網資源。輸入網路 Proxy 伺服器的統一資源識別碼（URI）。

此功能已在PowerShell 6.0.0中新增。

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

-ProxyCredential

指定有權使用 Proxy 參數所指定 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 伺服器。

只有在命令中也使用 Proxy 參數時，這個參數才有效。您無法在 相同的命令中使用 ProxyCredential 和 ProxyUseDefaultCredentials 參數。

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

-ResponseHeadersVariable

建立包含響應標頭字典的變數。輸入不含貨幣符號（$）符號的變數名稱。字典的索引鍵包含網頁伺服器所傳回之響應標頭的功能變數名稱和值。

此功能已在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。當失敗碼為 429 且回應在其 標頭中包含 Retry-After 屬性時，Cmdlet 會針對重試間隔使用該值，即使已指定此參數也一樣。

此外，請參閱 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、 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中新增，且已在 Tls13 PowerShell 7.1中新增支援。

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

-Token

要包含在要求中的 OAuth 或 Bearer 令牌。 某些驗證選項需要令牌。它無法獨立使用。

權杖接受 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 回應標頭的值。此參數可接受的值為：

區塊化
壓縮
緊縮
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

-UnixSocket

指定要連線的 Unix 套接字名稱。 Unix 型系統和 Windows 1803 版和更新版本支援此參數。如需 Unix 套接字之 Windows 支援的詳細資訊，請參閱 Windows/WSL Interop 搭配AF_UNIX 部落格文章。

此參數已在PowerShell 7.4中新增。

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

-Uri

指定傳送 Web 要求之因特網資源的統一資源識別碼（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 每個作業系統和平臺的輕微變化。

若要使用大部分因特網瀏覽器所使用的標準使用者代理程式字串測試網站，請使用 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 屬性來判斷 Proxy 組態。

此屬性的值會根據您的平臺而有所不同：

若為 Windows：從環境變數讀取 Proxy 組態，或者，如果未定義，則從使用者的 Proxy 設定讀取 Proxy 組態。
針對macOS：從環境變數讀取 Proxy 組態，或從系統的 Proxy 設定中讀取這些設定。
針對 Linux：從環境變數讀取 Proxy 組態，或如果未定義 Proxy 組態，這個屬性會初始化未設定的實例，以略過所有位址。

Windows 和 Unix 平台上用於 DefaultProxy 初始化的環境變數如下：

HTTP_PROXY：HTTP 要求上使用之 Proxy 伺服器的主機名或IP位址。
HTTPS_PROXY：HTTPS 要求上使用之 Proxy 伺服器的主機名或IP位址。
ALL_PROXY：在 HTTP 和 HTTPS 要求上使用之 Proxy 伺服器的主機名或 IP 位址，以防HTTP_PROXYHTTPS_PROXY或未定義。
NO_PROXY：應從 Proxy 處理中排除的主機名稱清單 (以逗號分隔)。

PowerShell 7.4 已新增對 Brotli 壓縮演演算法的支援。

Invoke-RestMethod

Syntax

Description

範例

範例 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

輸入

輸出

備註

相關連結

意見反應

其他資源