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

Windows PowerShell 會將回應格式化為數據類型。針對 RSS 或 ATOM 摘要，Windows PowerShell 會傳回 Item 或 Entry XML 節點。針對 JavaScript 物件表示法（JSON）或 XML，Windows PowerShell 會將內容轉換成物件（或還原串行化）。

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

注意

根據預設，網頁中的腳本程式代碼可能會在剖析頁面以填入 ParsedHtml 屬性時執行。使用 -UseBasicParsing 參數來隱藏此專案。

範例

範例 1：取得 PowerShell RSS 摘要

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

此命令會使用 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：傳遞多個標頭

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

API 通常需要傳遞的標頭來進行驗證、驗證等。

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

參數

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

-Certificate

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

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

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

-CertificateThumbprint

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

憑證用於客戶端憑證型驗證。它們只能對應至本機用戶帳戶;它們不適用於網域帳戶。

若要取得憑證指紋，請使用 Windows PowerShell （Cert:）磁碟驅動器中的 Get-Item 或 Get-ChildItem 命令。

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

-ContentType

指定 Web 要求的內容類型。

如果省略此參數且要求方法是POST，Invoke-RestMethod 將內容類型設定為「application/x-www-form-urlencoded」。。否則，不會在呼叫中指定內容類型。

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

-Credential

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

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

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

-DisableKeepAlive

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

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

-Headers

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

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

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

-InFile

從檔案取得 Web 要求的內容。

輸入路徑和檔名。如果您省略路徑，則預設值為目前的位置。

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

-MaximumRedirection

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

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

-Method

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

違約
刪除
獲取
頭
合併
選項
補丁
發佈
放
跟蹤

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

-OutFile

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

根據預設，Invoke-RestMethod 會將結果傳回至管線。若要將結果傳送至檔案和管線，請使用 -Passthru 參數。

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

-PassThru

除了將結果寫入檔案之外，還傳回結果。只有在命令中也使用 -OutFile 參數時，此參數才有效。

類型:	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 要求工作階段物件，並將它指派給 Windows PowerShell 工作階段中具有指定名稱的變數。只要命令完成，您就可以在會話中使用變數。

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

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

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

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

-TimeoutSec

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

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

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

-TransferEncoding

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

區塊化
壓縮
緊縮
GZip
身份

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

-WebSession

指定 Web 要求工作階段。輸入變數名稱，包括貨幣符號（$）。

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

若要建立 Web 要求工作階段，請在 Invoke-RestMethod 命令的 -SessionVariable 參數值中輸入變數名稱（不含貨幣符號）。 Invoke-RestMethod 建立會話，並將它儲存在變數中。在後續的命令中，使用變數作為 -WebSession 參數的值。

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

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

輸入

Object

您可以使用管線將 Web 要求的本文傳送至 Invoke-RestMethod。

輸出

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

Cmdlet 的輸出取決於所擷取的內容格式。

PSObject

如果要求傳回 JSON 字串，Invoke-RestMethod 會傳回代表字串的 PSObject。

共用方式為

Invoke-RestMethod

語法

Description

範例

範例 1：取得 PowerShell RSS 摘要

範例 2

範例 3：傳遞多個標頭

參數

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

輸入

輸出

其他資源

共用方式為

Invoke-RestMethod

語法

Description

範例

範例 1：取得 PowerShell RSS 摘要

範例 2

範例 3：傳遞多個標頭

參數

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

輸入

輸出

相關連結

其他資源