Invoke-RestMethod
傳送 HTTP 或 HTTPS 要求至 RESTful Web 服務。
Syntax
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
Cmdlet 會將 Invoke-RestMethod
HTTP 和 HTTPS 要求傳送至表示狀態傳輸 (REST) Web 服務,以傳回豐富的結構化數據。
Windows PowerShell 會根據資料類型設定回應格式。 對於 RSS 或 ATOM 摘要,Windows PowerShell 會傳回項目 XML 節點。 對於 JavaScript Object Notation (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),會以標準「名稱=值」格式將主體設定為要求主體的值。
警告: POST 主體的詳細信息輸出會以 with -1-byte payload
結尾,即使本文的大小都是已知,並在 HTTP 標頭中 Content-Length
傳送。
當本文是表單,或它是另一個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]
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Certificate
指定用於安全 Web 要求的用戶端憑證。 輸入包含憑證的變數,或可取得憑證的命令或運算式。
若要尋找憑證,請使用 Get-PfxCertificate
或使用 Get-ChildItem
憑證 (Cert:
) 磁碟驅動器中的 Cmdlet。
若憑證無效或權限不足,則命令會失敗。
Type: | X509Certificate |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
指定具有傳送要求權限之使用者帳戶的數位公開金鑰憑證 (X509)。 請輸入憑證的憑證指紋。
憑證將用於用戶端憑證式驗證。 這些憑證只能對應至本機使用者帳戶,無法用於網域帳戶。
若要取得憑證指紋,請使用 Get-Item
Windows PowerShell () Cert:
磁碟驅動器中的或 Get-ChildItem
命令。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ContentType
指定 Web 要求的內容類型。
如果省略此參數,且要求方法是 POST, Invoke-RestMethod
請將內容類型設定為 “application/x-www-form-urlencoded”。
否則,呼叫中不會指定內容類型。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Credential
指定具有傳送要求權限的使用者帳戶。 預設為目前使用者。
輸入使用者名稱,例如 「User01」 或 「Domain01\User01」,或輸入 PSCredential 物件,例如 Cmdlet 所產生的 Get-Credential
用戶名稱。
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-DisableKeepAlive
將 HTTP 標頭中的 KeepAlive 值設為 False。 KeepAlive 預設為 True。 KeepAlive 會建立伺服器持續連線,有助於後續要求。
Type: | SwitchParameter |
Position: | Named |
Default value: | KeepAlive |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Headers
指定 Web 要求的標頭。 輸入雜湊表或字典。
若要設定 UserAgent 標頭,請使用 -UserAgent
參數。
您無法使用此參數指定 UserAgent 或 Cookie 標頭。
Type: | IDictionary |
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 |
-MaximumRedirection
決定連線失敗之前,Windows PowerShell 可將連線重新導向至替代「統一資源識別項 (URI)」的次數。 預設值為 5。 值為 0 (零) 將禁止所有重新導向。
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Method
指定用於 Web 要求的方法。 此參數可接受的值為:
- Default
- 刪除
- Get
- 前端
- 合併
- 選項
- 修補程式
- 郵寄
- Put
- 追蹤
Type: | WebRequestMethod |
Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Default value: | Default |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutFile
將回應主體儲存在指定的輸出檔中。 輸入路徑和檔案名稱。 若省略路徑,則預設為目前位置。
根據預設, Invoke-RestMethod
會將結果傳回至管線。
若要將結果傳送至檔案和管線,請使用 -Passthru
參數。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
除了將結果寫入檔案,也會傳回結果。
只有當命令中也使用 -OutFile
參數時,此參數才會有效。
Type: | SwitchParameter |
Position: | Named |
Default value: | No output |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
對於要求使用 Proxy 伺服器,而不是直接連線網際網路資源。 輸入網路 Proxy 伺服器的 URI。
Type: | Uri |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
指定有權使用 參數所 -Proxy
指定 Proxy 伺服器的用戶帳戶。
預設為目前使用者。
輸入使用者名稱,例如 「User01」 或 「Domain01\User01」,或輸入 PSCredential 物件,例如 Cmdlet 所產生的 Get-Credential
用戶名稱。
只有當命令中也使用 -Proxy
參數時,此參數才會有效。
您無法在相同的命令中使用 -ProxyCredential
和 -ProxyUseDefaultCredentials
參數。
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
使用目前使用者的認證來存取 參數所 -Proxy
指定的 Proxy 伺服器。
只有當命令中也使用 -Proxy
參數時,此參數才會有效。
您無法在相同的命令中使用 -ProxyCredential
和 -ProxyUseDefaultCredentials
參數。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
建立 Web 要求工作階段,並將它儲存在指定變數的值。
輸入不含貨幣符號的變數名稱, ($
) 符號。
當您指定會話變數時,Invoke-RestMethod
會建立 Web 要求工作階段物件,並將它指派給 Windows PowerShell 工作階段中具有指定名稱的變數。
一旦命令完成,便可在工作階段中使用變數。
Web 要求工作階段不同於遠端工作階段,並非持續連線。 它是包含連線與要求相關資訊的物件,這些資訊包括 Cookie、認證、重新導向上限值,以及使用者代理字串。 您可以使用它在 Web 要求之間共用狀態與資料。
若要在後續 Web 要求中使用 Web 要求工作階段,請在 參數的值 -WebSession
中指定會話變數。
建立新連線時,Windows 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 |
-TimeoutSec
指定要求逾時之前可以擱置的時間長度。以秒為單位輸入值。 預設值為 0,會指定無限逾時。
功能變數名稱系統 (DNS) 查詢最多可能需要 15 秒的時間才能傳回或逾時。如果您的要求包含需要解析的主機名,而且您已將 TimeoutSec 設定為大於零的值,但小於 15 秒,則擲回 WebException 之前可能需要 15 秒以上的時間,而且您的要求逾時。
Type: | Int32 |
Position: | Named |
Default value: | 0 |
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 |
-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
表示 Cmdlet 使用基本剖析。 Cmdlet 會傳回 String 物件中的原始 HTML。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseDefaultCredentials
使用目前使用者的認證來傳送 Web 要求。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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)
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WebSession
指定 Web 要求工作階段。
輸入變數名稱,包括貨幣符號 ($
) 。
若要覆寫 Web 要求工作階段中的值,請使用 Cmdlet 參數,例如 -UserAgent
或 -Credential
。
參數值的優先順序高於 Web 要求工作階段中的值。
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 |
輸入
您可以使用管線將 Web 要求的主體傳送至 Invoke-RestMethod
。
輸出
System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String
Cmdlet 的輸出取決於抓取內容的格式。
PSObject
如果要求傳回 JSON 字串, Invoke-RestMethod
則會傳回代表字串的 PSObject。