Invoke-RestMethod

模組:: Microsoft.PowerShell.Utility Module

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

語法

StandardMethod (預設值)

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

StandardMethodNoProxy

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

CustomMethod

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

Description

Invoke-RestMethod Cmdlet 會將 HTTP 和 HTTPS 要求傳送至表示式狀態傳輸（REST） Web 服務，以傳回豐富的結構化數據。

PowerShell 會將回應格式化為數據類型。針對 RSS 或 ATOM 摘要，PowerShell 會傳回 Item 或 Entry XML 節點。針對 JavaScript 物件表示法（JSON）或 XML，PowerShell 會將內容轉換或反序列化成 [pscustomobject] 物件。 JSON 數據中允許批注。

備註

當 REST 端點傳回多個物件時，物件會以陣列的形式接收。如果您使用管線將輸出從 Invoke-RestMethod 傳送至另一個命令，則會以單一 [Object[]] 物件的形式傳送。管線上的下一個命令不會列舉該數組的內容。

此 Cmdlet 是在 Windows PowerShell 3.0 中引進的。

從 PowerShell 7.0 開始，Invoke-RestMethod 支援環境變數所定義的 Proxy 組態。請參閱本文 NOTES 一節。

從 PowerShell 7.4 開始，要求的字元編碼預設為 UTF-8，而不是 ASCII。如果您需要不同的編碼方式，您必須在 charset 標頭中設定 Content-Type 屬性。

範例

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

Cmdlet 會提示輸入認證，並將其儲存在 $Cred中。 $Url 包含 REST 端點 URL。

$Body 變數會描述搜尋準則、指定 CSV 做為輸出模式，並指定兩天前開始且一天前結束之傳回數據的時間間隔。主體變數指定了適用於與 Invoke-RestMethod 進行通訊的特定 REST API 參數的值。

Invoke-RestMethod 命令會在所有變數就位的情況下執行，並指定產生的 CSV 輸出檔的路徑和檔名。

範例 3：遵循關聯連結

某些 REST API 透過關聯連結（Relation Links）依據 RFC5988進行分頁支援。與其剖析標頭以取得下一頁的 URL，不如讓 Cmdlet 自動完成這項工作。此範例會從PowerShell GitHub存放庫傳回前兩頁的問題。

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

範例 4：簡化的多部分/Form-Data 提交

某些 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-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，或將命令包裝在括號中。下列範例會計算 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 會傳回錯誤，報告格式化的值無效。請求未被傳送至端點。

使用 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

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-AllowUnencryptedAuthentication

允許透過未加密連線傳送認證和秘密。根據預設，若提供的憑證或任何驗證選項具有的 Uri 並未以 https:// 開頭，則會導致錯誤並中止請求，以防止在未加密連線上無意中以純文本傳輸機密資訊。若要以您自己的風險覆寫此行為，請提供 AllowUnencryptedAuthentication 參數。

警告

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

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Authentication

指定要用於要求的明確驗證類型。預設值為 [無]。驗證參數不能與 UseDefaultCredentials 參數搭配使用。

可用的驗證選項：

None：未提供驗證時，這是預設選項。未使用明確驗證。
Basic：需要認證。這些憑證用於以 Authorization: Basic格式傳送 RFC 7617 基本身份驗證 base64(user:password) 標頭。
Bearer：需要 Token 參數。使用提供的令牌傳送 RFC 6750 Authorization: Bearer 標頭。
OAuth：需要 Token 參數。使用提供的令牌傳送 RFC 6750 Authorization: Bearer 標頭。

提供的驗證將會覆蓋提供給 Authorization 或包含在 WebSession中的任何標頭。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	WebAuthenticationType
預設值:	None
接受的值:	None, Basic, Bearer, OAuth
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Body

指定請求的主體內容。請求的主體是緊接著標頭的內容。您也可以將資料流參數的值傳送至 Invoke-RestMethod。

Body 參數可用來指定查詢參數清單或指定要求的內容。針對查詢參數，Cmdlet 會使用 System.Net.WebUtility.UrlEncode 方法來編碼機碼/值組。如需 URL 編碼字串的詳細資訊，請參閱 UrlEncode（）方法參考。

當輸入是 POST 請求，且其內容為 String時，首次出現的等號（=）左邊的值會被設定為表單資料的鍵，而其餘的文字則被設定為值。若要指定多個索引鍵，請使用 IDictionary 物件，例如哈希表，Body。

當輸入是 GET 要求，主體是 IDictionary（通常是哈希表），主體會新增至 URI 作為查詢參數。對於其他請求類型（例如 PATCH），請求主體會設成包含標準 name=value 格式中的值，並將值進行 URL 編碼。

當輸入是 System.Xml.XmlNode 物件，且 XML 宣告會指定編碼方式時，除非由 ContentType 參數覆寫，否則該編碼會用於要求中的數據。

當主體是表單，或它是另一個 Invoke-WebRequest 呼叫的輸出時，PowerShell 會將要求的內容設定為表單欄位。

Body 參數也可以接受 System.Net.Http.MultipartFormDataContent 物件，以利 multipart/form-data 要求。當將 MultipartFormDataContent 物件提供給 Body時，任何提供給 ContentType、Headers或 WebSession 參數的內容相關標頭都會被此 MultipartFormDataContent 物件的內容標頭覆蓋。此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	Object
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Certificate

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

若要尋找憑證，請使用 Get-PfxCertificate 或使用憑證（Get-ChildItem）磁碟驅動器中的 Cert: Cmdlet。如果憑證無效或沒有足夠的授權單位，則命令會失敗。

參數屬性

類型:	X509Certificate
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CertificateThumbprint

指定有權傳送要求之用戶帳戶的數位公鑰憑證（X509）。輸入憑證的指紋。

憑證用於客戶端憑證型驗證。憑證只能對應至本機用戶帳戶，而不是網域帳戶。

若要查看憑證指紋，請使用 Get-Item 或 Get-ChildItem 命令，在 Cert:\CurrentUser\My中尋找憑證。

備註

此功能目前僅支援 Windows OS 平臺。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ConnectionTimeoutSeconds

指定請求逾時前可擱置的時間長度。輸入以秒為單位的數值。預設值 0 表示無限期等待。

網域名稱系統（DNS）查詢最多可能需要 15 秒才能返回或超時。如果您的請求包含需要解析的主機名稱，並且您將 ConnectionTimeoutSeconds 設定為大於零但小於 15 秒的值，則可能需要 15 秒或更長時間才會出現 WebException，導致您的請求超時。

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

參數屬性

類型:	Int32
預設值:	0
支援萬用字元:	False
不要顯示:	False
別名:	TimeoutSec

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ContentType

指定 Web 要求的內容類型。

如果 ContentType 的值 包含編碼格式（如 charset），Cmdlet 會使用該格式來編碼 Web 要求的本文。如果 ContentType 未指定編碼格式，則會改用預設編碼格式。具有編碼格式的 ContentType 範例為 text/plain; charset=iso-8859-5，其會指定拉丁文/斯拉夫文字母。

如果您省略參數，內容類型可能會根據您使用的 HTTP 方法而有所不同：

針對 POST 方法，內容類型為 application/x-www-form-urlencoded
針對PUT方法，內容類型為 application/json
對於其他方法，在要求中未指定內容類型

如果您使用 InFile 參數來上傳檔案，您應該設定內容類型。通常，類型應該 application/octet-stream。不過，您必須根據端點的需求來設定內容類型。

當 Body 是 multipartFormDataContent 物件時，ContentType 會覆寫。

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Credential

指定有權傳送要求的用戶帳戶。預設值為目前的使用者。

輸入使用者名稱，例如 User01 或 Domain01\User01，或輸入 Cmdlet 所產生的 Get-Credential 物件。

您可以單獨使用 Credential，或搭配特定驗證參數選項。單獨使用時，只有在遠端伺服器傳送驗證挑戰要求時，才會將認證提供給遠端伺服器。搭配驗證選項使用時，會明確傳送認證。

認證會儲存在 PSCredential 物件中，密碼會儲存為 secureString 。

備註

如需 SecureString 數據保護的詳細資訊，請參閱 SecureString 有多安全？。

參數屬性

類型:	PSCredential
預設值:	Current user
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CustomMethod

指定用於 Web 要求的自訂方法。這可以與端點要求的方法一起使用，而該方法在方法上不是可用的選項。方法和 CustomMethod 無法一起使用。

範例：

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

這會對 API 提出 TEST HTTP 要求。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	公分

參數集

CustomMethod

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethodNoProxy

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-DisableKeepAlive

將 HTTP 標頭中的 KeepAlive 值設定為 False。根據預設，KeepAlive 為True。 KeepAlive 會建立與伺服器的持續性連線，以利後續的要求。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-FollowRelLink

指出 Cmdlet 應遵循關聯連結。

某些 REST API 透過關聯連結（Relation Links）依據 RFC5988進行分頁支援。與其剖析標頭以取得下一頁的 URL，不如讓 Cmdlet 自動完成這項工作。若要設定要追蹤關聯連結的次數，請使用 MaximumFollowRelLink 參數。

使用此參數時，Cmdlet 會傳回結果頁面的集合。每個結果頁面可能包含多個結果項目。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	佛羅里達州

參數集

(All)

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
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Headers

指定 Web 要求的標頭。輸入哈希表或字典。

當提供 Content-Type的 MultipartFormDataContent 物件時，內容相關的標頭，如，會被覆寫。

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

參數屬性

類型:	IDictionary
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-HttpVersion

指定用於要求的 HTTP 版本。預設值為 1.1。

有效值為：

參數屬性

類型:	Version
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InFile

從檔案取得 Web 要求本文的內容。輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。

您也需要設定要求的內容類型。例如，若要上傳檔案，您應該設定內容類型。通常，類型應該 application/octet-stream。不過，您必須根據端點的需求來設定內容類型。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumFollowRelLink

如果使用 FollowRelLink ，指定要追蹤關聯連結的次數。如果 REST API 因要求太多而節流，可能需要較小的值。預設值是 [int32]::MaxValue。值為 0 （零）會防止下列關聯連結。

參數屬性

類型:	Int32
預設值:	Int32.MaxValue
支援萬用字元:	False
不要顯示:	False
別名:	ML

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumRedirection

指定 PowerShell 在連線失敗之前，將連線重新導向至替代統一資源識別碼（URI）的次數。預設值為 5。值為 0 （零）會防止所有重新導向。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumRetryCount

指定收到 400 到 599 之間的失敗碼或 304 時，PowerShell 重試連線的次數。另請參閱 RetryIntervalSec 參數，以指定重試之間的間隔。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Method

指定用於 Web 要求的方法。此參數可接受的值為：

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

CustomMethod 參數可用於上述未列出的要求方法。

參數屬性

類型:	WebRequestMethod
預設值:	None
接受的值:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

StandardMethodNoProxy

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-NoProxy

表示 Cmdlet 不會使用 Proxy 到達目的地。使用此工具來略過你在網際網路設定或環境中指定的代理伺服器。

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

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethodNoProxy

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethodNoProxy

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-OperationTimeoutSeconds

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

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

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-OutFile

根據預設，Invoke-RestMethod 會將結果傳回至管線。當您使用 OutFile 參數時，結果會儲存至指定的檔案，而不會傳回至管線。輸入路徑和檔名。若要將結果傳送至檔案和管線，請新增 PassThru 參數。

如果您省略路徑，則預設值為目前的位置。名稱會被視為字面上的路徑。包含方括弧（[]）的名稱必須以單引弧括住（'）。

從 PowerShell 7.4 開始，您可以指定沒有檔名的資料夾路徑。當您這樣做時，命令會在經過任何重新導向後，使用已解析 URI 最後一個區段的文件名。當您指定 OutFile的資料夾路徑時，無法使用 Resume 參數。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PassThru

只有當命令中也會使用 OutFile 參數時，此參數才有效。意圖是將結果寫入檔案和管線。

參數屬性

類型:	SwitchParameter
預設值:	No output
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PreserveAuthorizationOnRedirect

指出當存在時，Cmdlet 應該在重定向過程中保留 Authorization 標頭。

根據預設，Cmdlet 會先移除 Authorization 標頭，再重新導向。針對需要將標頭傳送至重新導向位置的情況，指定此參數會停用此邏輯。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PreserveHttpMethodOnRedirect

指出 Cmdlet 在重新導向中應保留請求的方法。

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

此功能已在PowerShell 7.4中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Proxy

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

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	Uri
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ProxyCredential

指定具有許可權的用戶帳戶，其有權使用 Proxy 參數所指定的 Proxy 伺服器。預設值為目前的使用者。

輸入使用者名稱，例如「User01」或「Domain01\User01」，或輸入 PSCredential 物件，例如 Get-Credential Cmdlet 所產生的用戶名稱。

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

參數屬性

類型:	PSCredential
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ProxyUseDefaultCredentials

使用目前使用者的認證來存取 Proxy 參數所指定的 Proxy 伺服器。

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

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

StandardMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CustomMethod

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ResponseHeadersVariable

建立包含響應標頭字典的變數。輸入不含 "$" 符號（$）的變數名稱。字典的鍵包含由網頁伺服器返回的響應標頭中的欄位名稱和值。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	RHV

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Resume

盡最大努力繼續下載部分檔案。 Resume 參數需要 OutFile 參數。

繼續只會在本機檔案和遠端檔案的大小上運作，而且不會執行本機檔案和遠端檔案相同的其他驗證。

如果本機檔案大小小於遠端檔案大小，則 Cmdlet 會嘗試繼續下載檔案，並將剩餘的位元組附加至檔尾。

如果本機檔案大小與遠端檔案大小相同，則不會採取任何動作，而且 Cmdlet 會假設下載已完成。

如果本機檔案大小大於遠端檔案大小，則會覆寫本機檔案，並重新下載整個遠端檔案。此行為等同於使用 OutFile 而不使用 Resume。

如果遠端伺服器不支援繼續下載，則會覆寫本機檔案，並重新下載整個遠端檔案。此行為等同於使用 OutFile 而不使用 Resume。

如果本機檔案不存在，則會建立本機檔案，並下載整個遠端檔案。此行為等同於使用 OutFile 而不使用 Resume。

此功能已在PowerShell 6.1.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-RetryIntervalSec

指定當收到 400 到 599（包含）或 304 的失敗碼時，連線重試的間隔。值必須介於 1 與 [int]::MaxValue之間。當失敗碼為 429 且回應在其標頭中包含 Retry-After 屬性時，即使指定此參數，Cmdlet 仍會針對重試間隔使用該值。

此外，請參閱指定重試次數的 MaximumRetryCount 參數。

參數屬性

類型:	Int32
預設值:	5
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SessionVariable

建立包含 Web 要求會話的變數。輸入不含 "$" 符號（$）的變數名稱。

當您指定會話變數時，Invoke-RestMethod 會建立 Web 要求工作階段物件，並將它指派給 PowerShell 工作階段中具有指定名稱的變數。只要命令完成，您就可以在會話中使用變數。

在 PowerShell 7.4 之前，Web 要求會話不是持續性連線。它是物件，其中包含連線和要求的相關信息，包括 Cookie、認證、最大重新導向值，以及使用者代理程式字串。您可以使用它，在 Web 要求之間共享狀態和數據。

從 PowerShell 7.4 開始，只要後續要求中不會覆寫工作階段的屬性，Web 要求工作階段就會持續。當它們符合條件時，cmdlet 會以新的值重新建立會話。持續性會話可減少重複要求的額外負荷，使其更快。

若要在後續的網頁請求中使用網頁請求會話，請在 WebSession 參數的值中指定會話變數。 PowerShell 會在建立新的連線時，使用 Web 要求工作階段物件中的數據。若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 UserAgent 或 Credential。參數值優先於網路要求會話中的值。

您無法在相同的命令中使用 SessionVariable 和 WebSession 參數。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	SV

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SkipCertificateCheck

略過包含所有驗證的憑證驗證檢查，例如到期、撤銷、受信任的根授權單位等。

警告

使用此參數並不安全，不建議使用。此開關僅限用於在使用自我簽署憑證進行測試的已知主機上。以您自己的風險使用。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SkipHeaderValidation

指出 Cmdlet 應該將標頭新增至要求，而不需驗證。

此開關應該用於需要使用不符合標準的標頭值的網站。指定此參數會停用驗證，以允許未核取傳遞值。指定時，會新增所有標頭而不進行驗證。

此開關會停用對傳遞至 ContentType、Headers和 UserAgent 參數的值的驗證。

此功能已在PowerShell 6.0.0中新增。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SkipHttpErrorCheck

此參數會使 Cmdlet 忽略 HTTP 錯誤狀態，並繼續處理回應。錯誤回應會被寫入管線，呈現方式就像是成功回應一樣。

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

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SslProtocol

設定 Web 要求允許的 SSL/TLS 通訊協定。根據預設，系統支援 SSL/TLS 通訊協定。 SslProtocol 允許針對特定通訊協議進行合規性限制。

這些值會定義為旗標型列舉。您可以將多個值結合在一起，以使用此參數來設定多個旗標。這些值可以傳遞至 SslProtocol 參數做為值的陣列，或做為這些值的逗號分隔字串。 Cmdlet 會使用二進位 OR 作業來結合值。將值以陣列的形式傳遞是最簡單的選擇，還可以讓您在使用 Tab 鍵時自動完成值。您可能無法在所有平臺上提供多個值。

此功能已在PowerShell 6.0.0中新增。 PowerShell 7.1 已新增 Tls13 支援。

參數屬性

類型:	WebSslProtocol
預設值:	None
接受的值:	Default, Tls, Tls11, Tls12, Tls13
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-StatusCodeVariable

建立變數，其中包含要求的 HTTP 狀態代碼結果。輸入不含 "$" 符號（$）的變數名稱。

參數可以識別與 SkipHttpErrorCheck 參數搭配使用時的成功訊息或失敗訊息。

輸入參數的變數名稱做為字串，例如 -StatusCodeVariable "scv"。

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Token

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

令牌會採用包含令牌的 SecureString。若要提供令牌，請手動使用如下指示：

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

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

參數屬性

類型:	SecureString
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TransferEncoding

指定傳輸編碼 HTTP 回應標頭的值。此參數可接受的值為：

分塊
壓縮
洩氣
GZip
身份

參數屬性

類型:	String
預設值:	None
接受的值:	chunked, compress, deflate, gzip, identity
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UnixSocket

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

此參數已在PowerShell 7.4中新增。

參數屬性

類型:	UnixDomainSocketEndPoint
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Uri

指定傳送 Web 要求之因特網資源的統一資源識別碼（URI）。此參數支援 HTTP、HTTPS、FTP 和 FILE 值。

這是必要參數。參數名稱（Uri）是選擇性的。

參數屬性

類型:	Uri
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UseBasicParsing

此參數已被取代。從 PowerShell 6.0.0 開始，所有網頁請求只會使用基本解析。此參數僅供回溯相容性使用。使用時，它不會影響 Cmdlet 的作業。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UseDefaultCredentials

指出 Cmdlet 會使用目前使用者的認證來傳送 Web 要求。這無法與驗證或認證搭配使用，而且在所有平臺上都不支援。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

(All)

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，每個作業系統和平臺都有輕微的變化。

若要使用大部分因特網瀏覽器所使用的標準使用者代理程式字串測試網站，請使用 PSUserAgent 類別的屬性，例如 Chrome、Firefox、InternetExplorer、Opera 和 Safari。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-WebSession

指定網頁要求會話。輸入變數名稱，包括貨幣符號（$）。

若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 UserAgent 或 Credential。參數值優先於網路要求會話中的值。當 Content-Type 物件用於 Body時，內容相關的標頭（例如）會被覆寫。

不同於遠端會話，Web 要求會話不是持續性連線。它是物件，其中包含連線和要求的相關信息，包括 Cookie、認證、最大重新導向值，以及使用者代理程式字串。您可以使用它，在 Web 要求之間共享狀態和數據。

若要建立 Web 要求會話，請在命令的 Invoke-RestMethod 參數的值中輸入變數名稱，但不包含美元符號。 Invoke-RestMethod 建立會話，並將它儲存在變數中。在後續命令中，使用變數作為 WebSession 參數的值。

您無法在相同的命令中使用 SessionVariable 和 WebSession 參數。

參數屬性

類型:	WebRequestSession
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。如需詳細資訊，請參閱 about_CommonParameters。

輸入

Object

您可以透過管道將 Web 要求的主體傳遞給此 Cmdlet。

PSObject

當要求傳回 JSON 字串時，此 Cmdlet 會傳回代表數據的 PSObject。

備註

PowerShell 包含下列 Invoke-RestMethod的別名：

所有平臺：
- irm

某些功能可能無法在所有平臺上使用。

由於 .NET Core 3.1 中的變更，PowerShell 7.0 和更新版本會使用 HttpClient.DefaultProxy 屬性來判斷 Proxy 組態。

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

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

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

HTTP_PROXY：HTTP 要求上使用之 Proxy 伺服器的主機名或IP位址。
HTTPS_PROXY：HTTPS 要求上使用之 Proxy 伺服器的主機名或IP位址。
ALL_PROXY：未定義 HTTP_PROXY 或 HTTPS_PROXY 時，用於 HTTP 和 HTTPS 要求的 Proxy 伺服器的主機名或 IP 位址。
NO_PROXY：應該從 Proxy 中排除的主機名逗號分隔清單。

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

意見反應

此頁面對您有幫助嗎？

共用方式為

Invoke-RestMethod

語法

StandardMethod (預設值)

StandardMethodNoProxy

CustomMethod

CustomMethodNoProxy

Description

範例

範例 1：取得 PowerShell RSS 訂閱源

範例 2：執行 POST 要求

範例 3：遵循關聯連結

範例 4：簡化的多部分/Form-Data 提交

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