Invoke-RestMethod
將 HTTP 或 HTTPS 要求傳送至 RESTful Web 服務。
語法
Default (預設值)
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[<CommonParameters>]
Description
Invoke-RestMethod Cmdlet 會將 HTTP 和 HTTPS 要求傳送至表示式狀態傳輸 （REST） Web 服務，以傳回豐富的結構化數據。
Windows PowerShell 會將回應格式化為數據類型。 針對 RSS 或 ATOM 摘要，Windows PowerShell 會傳回 Item 或 Entry XML 節點。 針對 JavaScript 物件表示法 （JSON） 或 XML，Windows PowerShell 會將內容轉換成物件（或還原串行化）。
此 Cmdlet 是在 Windows PowerShell 3.0 中引進的。
備註
根據預設，網頁中的腳本代碼可能會在剖析頁面以填入 ParsedHtml 屬性時執行。
使用 -UseBasicParsing 參數來隱藏此專案。
參數
-Body
指定請求的主體內容。
請求的主體是緊接著標頭的內容。
您也可以將資料流參數的值傳送至 Invoke-RestMethod。
-Body 參數可用來指定查詢參數的清單，或指定響應的內容。
當輸入是 GET 要求，主體是 IDictionary （通常是哈希表），主體會新增至 URI 作為查詢參數。 對於其他請求類型（例如 POST），內容會設定為標準 name=value 格式的請求主體的值。
警告：POST 主體的詳細信息輸出會以 with -1-byte payload結尾，即使主體的大小都是已知，而且傳送於 Content-Length HTTP 標頭中。
當本文是窗體，或它是另一個 Invoke-WebRequest 呼叫的輸出時，Windows PowerShell 會將要求內容設定為表單域。
例如：
$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[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）。 輸入憑證的指紋。
憑證用於客戶端憑證型驗證。 它們只能對應至本機用戶帳戶;它們不適用於網域帳戶。
若要取得憑證指紋，請使用 Windows PowerShell （Get-Item） 磁碟驅動器中的 Get-ChildItem 或 Cert: 命令。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-ContentType
指定 Web 要求的內容類型。
如果省略此參數且要求方法是POST，Invoke-RestMethod 將內容類型設定為 「application/x-www-form-urlencoded」。。
否則，不會在呼叫中指定內容類型。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Credential
指定有權傳送要求的用戶帳戶。 預設值為目前的使用者。
輸入使用者名稱，例如 「User01」 或 「Domain01\User01」，或輸入 PSCredential 物件，例如 Get-Credential Cmdlet 所產生的用戶名稱。
參數屬性
| 類型: | PSCredential |
| 預設值: | Current user |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-DisableKeepAlive
將 HTTP 標頭中的 KeepAlive 值設定為 False。 根據預設，KeepAlive 為True。 KeepAlive 會建立與伺服器的持續性連線，以利後續的要求。
參數屬性
| 類型: | SwitchParameter |
| 預設值: | KeepAlive |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Headers
指定 Web 要求的標頭。 輸入哈希表或字典。
若要設定 UserAgent 標頭，請使用 -UserAgent 參數。
您無法使用此參數來指定 UserAgent 或 Cookie 標頭。
參數屬性
| 類型: | IDictionary |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-InFile
從檔案取得 Web 要求的內容。
輸入路徑和檔名。 如果您省略路徑，則預設值為目前的位置。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-MaximumRedirection
判斷 Windows PowerShell 在連線失敗之前，將連線重新導向至替代統一資源標識碼 （URI） 的次數。 預設值為 5。 值為 0 （零） 會防止所有重新導向。
參數屬性
| 類型: | Int32 |
| 預設值: | 5 |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Method
指定用於 Web 要求的方法。 此參數可接受的值為：
- 預設
- 刪除
- 獲取
- 頭
- 合併
- 選項
- 補丁
- 貼文
- 放
- 痕跡
參數屬性
| 類型: | WebRequestMethod |
| 預設值: | Default |
| 接受的值: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-OutFile
將回應本文儲存在指定的輸出檔中。 輸入路徑和檔名。 如果您省略路徑，則預設值為目前的位置。
根據預設，Invoke-RestMethod 會將結果傳回至管線。
若要將結果傳送至檔案和管線，請使用 -Passthru 參數。
參數屬性
| 類型: | 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 |
-Proxy
使用 Proxy 伺服器進行要求，而不是直接連線到因特網資源。 輸入網路 Proxy 伺服器的 URI。
參數屬性
| 類型: | Uri |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-ProxyCredential
指定有權使用 -Proxy 參數所指定 Proxy 伺服器的用戶帳戶。
預設值為目前的使用者。
輸入使用者名稱，例如 「User01」 或 「Domain01\User01」，或輸入 PSCredential 物件，例如 Get-Credential Cmdlet 所產生的用戶名稱。
只有在命令中也使用 -Proxy 參數時，此參數才有效。
您無法在相同的命令中使用 -ProxyCredential 和 -ProxyUseDefaultCredentials 參數。
參數屬性
| 類型: | PSCredential |
| 預設值: | Current user |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-ProxyUseDefaultCredentials
使用目前使用者的認證來存取由 -Proxy 參數指定的 Proxy 伺服器。
只有在命令中也使用 -Proxy 參數時，此參數才有效。
您無法在相同的命令中使用 -ProxyCredential 和 -ProxyUseDefaultCredentials 參數。
參數屬性
| 類型: | SwitchParameter |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-SessionVariable
建立 Web 要求工作階段，並將它儲存在指定變數的值中。
輸入不含 "$" 符號（$）的變數名稱。
當您指定會話變數時，Invoke-RestMethod 會建立 Web 要求工作階段物件，並將它指派給 Windows PowerShell 工作階段中具有指定名稱的變數。
只要命令完成，您就可以在會話中使用 變數。
不同於遠端會話，Web 要求會話不是持續性連線。 它是物件，其中包含連線和要求的相關信息，包括 Cookie、認證、最大重新導向值，以及使用者代理程式字串。 您可以使用它，在 Web 要求之間共享狀態和數據。
若要在後續的 Web 要求中使用 Web 要求工作階段，請在 -WebSession 參數的值中指定工作階段變數。
Windows PowerShell 會在建立新連線時，使用 Web 要求會話對象中的數據。
若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 -UserAgent 或 -Credential。
參數值優先於網路要求會話中的值。
您無法在相同的命令中使用 -SessionVariable 和 -WebSession 參數。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
| 別名: | SV |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-TimeoutSec
指定請求逾時前可擱置的時間長度。輸入以秒為單位的數值。 預設值 0 表示無限期等待。
網域名稱系統（DNS）查詢可能需要最多15秒才能返回或超時。如果您的請求包含需要解析的主機名稱，並且您將 TimeoutSec 設置為大於零但小於15秒，則可能需要 15 秒或更長時間才會引發 WebException，並且您的請求會超時。
參數屬性
| 類型: | Int32 |
| 預設值: | 0 |
| 支援萬用字元: | 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 |
-Uri
指定傳送 Web 要求之因特網資源的統一資源識別碼 （URI）。 此參數支援 HTTP、HTTPS、FTP 和 FILE 值。
這是必要參數。
參數名稱 （-Uri） 是選擇性的。
參數屬性
| 類型: | Uri |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | 0 |
| 必要: | True |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-UseBasicParsing
表示 cmdlet 使用基本剖析。 Cmdlet 會傳回 String 物件中的原始 HTML。
參數屬性
| 類型: | SwitchParameter |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-UseDefaultCredentials
使用目前用戶的認證來傳送 Web 要求。
參數屬性
| 類型: | SwitchParameter |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-UserAgent
指定 Web 要求的使用者代理字串。
默認使用者代理程序類似於 「Mozilla/5.0 （Windows NT;Windows NT 6.1;en-US） WindowsPowerShell/3.0“，每個作業系統和平臺都有輕微的變化。
若要使用大部分因特網瀏覽器所使用的標準使用者代理程式字串來測試網站，請使用 PSUserAgent 類別的屬性，例如 Chrome、FireFox、Internet Explorer、Opera 和 Safari。
例如，下列命令使用因特網的使用者代理程式字串
Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-WebSession
指定網頁要求會話。
輸入變數名稱，包括貨幣符號 （$）。
若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 -UserAgent 或 -Credential。
參數值優先於網路要求會話中的值。
不同於遠端會話，Web 要求會話不是持續性連線。 它是物件，其中包含連線和要求的相關信息，包括 Cookie、認證、最大重新導向值，以及使用者代理程式字串。 您可以使用它，在 Web 要求之間共享狀態和數據。
若要建立 Web 要求工作階段，請在 -SessionVariable 命令的 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 要求的本文傳送至 Invoke-RestMethod。
輸出
System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String
Cmdlet 的輸出取決於所擷取的內容格式。
PSObject
如果要求傳回 JSON 字串，Invoke-RestMethod 會傳回代表字串的 PSObject。