Invoke-RestMethod

參考

模組:: Microsoft.PowerShell.Utility

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

語法

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 服務，以傳回豐富的結構化數據。

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

注意

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

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

注意

根據預設，網頁中的腳本代碼可能會在剖析頁面以填入 ParsedHtml 屬性時執行。使用 UseBasicParsing 開關來取消此操作。

範例

範例 1：取得 PowerShell RSS 訂閱源

Invoke-RestMethod -Uri https://devblogs.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

此命令會使用 Invoke-RestMethod Cmdlet 從 PowerShell 部落格 RSS 摘要取得資訊。命令會使用 Format-Table Cmdlet 來顯示資料表中每個部落格的 Title 和 pubDate 属性的值。

範例 2

在下列範例中，用戶會執行 Invoke-RestMethod，在用戶組織中的內部網路網站上執行 POST 要求。

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as
# the output mode, and specifies a time period for returned data that starts two days ago and ends
# one day ago. The body variable specifies values for parameters that apply to the particular REST
# API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file
# name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

範例 3：傳遞多個標頭

此範例示範如何將多個標頭從 hash-table 傳遞至 REST API。

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

API 通常需要傳遞標頭以進行身份驗證、確認等作業。

範例 3：提交表單數據

當本文是表單，或它是另一個 Invoke-WebRequest 呼叫的輸出時，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]

範例 4：列舉管線上返回的項目

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

參數

-Body

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

Body 參數可用來指定查詢參數清單或指定回應的內容。

當輸入是 GET 要求，主體是 IDictionary （通常是哈希表），主體會新增至 URI 作為查詢參數。對於其他請求類型（例如 POST），內容會設定為標準 name=value 格式的請求主體的值。

警告

POST 主體的詳細輸出會在 with -1-byte payload終止，即使主體的大小是已知的，且會在 Content-Length HTTP 標頭中傳送。

類型:	Object
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	True
接受萬用字元:	False

-Certificate

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

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

類型:	X509Certificate
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-CertificateThumbprint

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

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

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

類型:	String
Position:	Named
預設值:	None
必要:	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。不過，您必須根據端點的需求來設定內容類型。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Credential

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

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

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

注意

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

類型:	PSCredential
Position:	Named
預設值:	Current user
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DisableKeepAlive

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

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Headers

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

若要設定 UserAgent 標頭，請使用 UserAgent 參數。您無法使用此參數來指定 UserAgent 或 Cookie 標頭。

類型:	IDictionary
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-InFile

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

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaximumRedirection

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

類型:	Int32
Position:	Named
預設值:	5
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

類型:	WebRequestMethod
接受的值:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
預設值:	Default
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-OutFile

將回應本文儲存在指定的輸出檔中。輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-PassThru

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

注意

當您使用 PassThru 參數時，輸出會寫入管線，但檔案是空的。如需詳細資訊，請參閱 PowerShell 問題 #15409。

類型:	SwitchParameter
Position:	Named
預設值:	No output
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Proxy

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

類型:	Uri
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ProxyCredential

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

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

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

類型:	PSCredential
Position:	Named
預設值:	Current user
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ProxyUseDefaultCredentials

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

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SessionVariable

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

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

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

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

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

類型:	String
別名:	SV
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TimeoutSec

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

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

類型:	Int32
Position:	Named
預設值:	0
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

類型:	String
接受的值:	chunked, compress, deflate, gzip, identity
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Uri

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

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

類型:	Uri
Position:	0
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-UseBasicParsing

表示 cmdlet 使用基本剖析。 Cmdlet 會傳回 String 物件中的原始 HTML。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-UseDefaultCredentials

使用目前用戶的認證來傳送 Web 要求。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	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
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-WebSession

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

若要覆寫 Web 要求工作階段中的值，請使用 Cmdlet 參數，例如 UserAgent 或 Credential。參數值優先於網路要求會話中的值。

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