Invoke-RestMethod
Odešle požadavek HTTP nebo HTTPS do webové služby RESTful.
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
Rutina Invoke-RestMethod
odesílá požadavky HTTP a HTTPS do webových služeb REPRESENTATIONAL State Transfer (REST), které vracejí bohatě strukturovaná data.
PowerShell formátuje odpověď na základě datového typu. V případě informačního kanálu RSS nebo ATOM vrátí PowerShell uzly XML položky nebo položky. V případě zápisu javascriptového objektu (JSON) nebo XML převede PowerShell nebo deserializuje obsah na [PSCustomObject]
objekty.
Poznámka:
Když koncový bod REST vrátí více objektů, objekty se přijímají jako pole. Pokud předáte výstup z Invoke-RestMethod
jiného příkazu, odešle se jako jeden [Object[]]
objekt. Obsah tohoto pole se nevypíše pro další příkaz v kanálu.
Tato rutina je zavedena ve Windows PowerShellu 3.0.
Poznámka:
Ve výchozím nastavení může být kód skriptu na webové stránce spuštěn při analýze stránky pro naplnění ParsedHtml
vlastnosti. K potlačení použijte přepínač UseBasicParsing.
Příklady
Příklad 1: Získání informačního kanálu RSS PowerShellu
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
Tento příkaz používá rutinu Invoke-RestMethod
k získání informací z informačního kanálu RSS blogu PowerShellu. Příkaz používá rutinu Format-Table
k zobrazení hodnot vlastností Title a pubDate každého blogu v tabulce.
Příklad 2
V následujícím příkladu uživatel spustí Invoke-RestMethod
požadavek POST na intranetovém webu v organizaci uživatele.
$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"}}
Příklad 3: Předání více hlaviček
Tento příklad ukazuje, jak předat více hlaviček z hash-table
rozhraní REST API.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
Rozhraní API často vyžadují předané hlavičky pro ověřování, ověřování atd.
Příklad 3: Odeslání dat formuláře
Pokud je tělo formulářem nebo výstupem jiného Invoke-WebRequest
volání, PowerShell nastaví obsah požadavku na pole formuláře.
Příklad:
$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]
Příklad 4: Vytvoření výčtu vrácených položek v kanálu
GitHub vrátí více objektů pole. Pokud výstup předáte do jiného příkazu, odešle se jako jeden [Object[]]
objekt.
Pokud chcete vytvořit výčet objektů do kanálu, předáte výsledky do Write-Output
závorek nebo rutinu zabalíte do závorek. Následující příklad spočítá počet objektů vrácených GitHubem. Potom spočítá počet objektů výčtu kanálu.
$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
Parametry
-Body
Určuje text požadavku. Text je obsah požadavku, který následuje za hlavičkami.
Můžete také roušit hodnotu těla do Invoke-RestMethod
.
Parametr Body lze použít k zadání seznamu parametrů dotazu nebo k určení obsahu odpovědi.
Když je vstupem požadavek GET a tělo je IDictionary (obvykle hashovací tabulka), tělo se přidá do identifikátoru URI jako parametry dotazu. U jiných typů požadavků (například POST) se text nastaví jako hodnota textu požadavku ve standardním formátu name=value.
Upozorňující
Podrobný výstup textu POST bude končit with -1-byte payload
, i když je velikost těla známá i odeslaná v Content-Length
hlavičce HTTP.
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Certificate
Určuje klientský certifikát, který se používá pro zabezpečený webový požadavek. Zadejte proměnnou obsahující certifikát nebo příkaz nebo výraz, který certifikát získá.
Pokud chcete najít certifikát, použijte Get-PfxCertificate
nebo použijte rutinu Get-ChildItem
na jednotce Certificate (Cert:
). Pokud certifikát není platný nebo nemá dostatečnou autoritu, příkaz selže.
Type: | X509Certificate |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
Určuje certifikát digitálního veřejného klíče (X509) uživatelského účtu, který má oprávnění k odeslání žádosti. Zadejte kryptografický otisk certifikátu.
Certifikáty se používají při ověřování na základě klientských certifikátů. Certifikáty lze mapovat pouze na místní uživatelské účty, nikoli účty domény.
Pokud chcete zobrazit kryptografický otisk certifikátu, použijte Get-Item
příkaz nebo Get-ChildItem
vyhledejte certifikát v Cert:\CurrentUser\My
souboru .
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ContentType
Určuje typ obsahu webového požadavku.
Pokud tento parametr vynecháte a metoda požadavku je POST, Invoke-RestMethod
nastaví typ obsahu na "application/x-www-form-urlencoded". V opačném případě není ve volání zadán typ obsahu.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Credential
Určuje uživatelský účet, který má oprávnění k odeslání požadavku. Ve výchozím nastavení je to aktuální uživatel.
Zadejte uživatelské jméno, například User01 nebo Domain01\User01, nebo zadejte objekt PSCredential vygenerovaný rutinouGet-Credential
.
Přihlašovací údaje jsou uloženy v objektu PSCredential a heslo je uloženo jako SecureString.
Poznámka:
Další informace o ochraně dat SecureString naleznete v tématu Jak zabezpečený je SecureString?.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-DisableKeepAlive
Nastaví hodnotu KeepAlive v hlavičce HTTP na False. KeepAlive má ve výchozím nastavení hodnotu True. KeepAlive vytvoří trvalé připojení k serveru, aby se usnadnily následné požadavky.
Type: | SwitchParameter |
Position: | Named |
Default value: | KeepAlive |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Headers
Určuje hlavičky webového požadavku. Zadejte tabulku hash nebo slovník.
Chcete-li nastavit hlavičky UserAgent, použijte parametr UserAgent . Tento parametr nelze použít k zadání hlavičky UserAgent nebo cookie.
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InFile
Získá obsah webového požadavku ze souboru.
Zadejte cestu a název souboru. Pokud cestu vynecháte, výchozí je aktuální umístění.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
Určuje, kolikrát Windows PowerShell přesměruje připojení na alternativní identifikátor URI (Uniform Resource Identifier), než se připojení nezdaří. Výchozí hodnota je 5. Hodnota 0 (nula) zabraňuje veškerému přesměrování.
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Method
Určuje metodu použitou pro webový požadavek. Tento parametr přijímá tyto hodnoty:
Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace
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
Uloží tělo odpovědi do zadaného výstupního souboru. Zadejte cestu a název souboru. Pokud cestu vynecháte, výchozí je aktuální umístění.
Ve výchozím nastavení Invoke-RestMethod
vrátí výsledky do kanálu.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Tento parametr je platný pouze v případě, že se v příkazu používá také parametr OutFile . Záměrem je zapsat výsledky do souboru a do kanálu.
Poznámka:
Když použijete parametr PassThru , výstup se zapíše do kanálu, ale soubor je prázdný. Další informace najdete v tématu Problém PowerShellu č. 15409.
Type: | SwitchParameter |
Position: | Named |
Default value: | No output |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
Místo přímého připojení k internetovému prostředku používá proxy server pro požadavek. Zadejte identifikátor URI síťového proxy serveru.
Type: | Uri |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
Určuje uživatelský účet, který má oprávnění používat proxy server určený parametrem Proxy . Ve výchozím nastavení je to aktuální uživatel.
Zadejte uživatelské jméno, například User01 nebo Domain01\User01, nebo zadejte objekt PSCredential , například objekt vygenerovaný rutinou Get-Credential
.
Tento parametr je platný pouze v případě, že se v příkazu používá také parametr Proxy . Ve stejném příkazu nelze použít parametry ProxyCredential a ProxyUseDefaultCredentials .
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
Používá přihlašovací údaje aktuálního uživatele pro přístup k proxy serveru určenému parametrem proxy .
Tento parametr je platný pouze v případě, že se v příkazu používá také parametr Proxy . Ve stejném příkazu nelze použít parametry ProxyCredential a ProxyUseDefaultCredentials .
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
Vytvoří proměnnou obsahující relaci webového požadavku. Zadejte název proměnné bez symbolu dolaru ($
).
Když zadáte proměnnou relace, Invoke-RestMethod
vytvoří objekt relace webového požadavku a přiřadí ho proměnné se zadaným názvem v relaci PowerShellu. Proměnnou v relaci můžete použít hned po dokončení příkazu.
Na rozdíl od vzdálené relace není relace webového požadavku trvalým připojením. Jedná se o objekt, který obsahuje informace o připojení a požadavku, včetně souborů cookie, přihlašovacích údajů, maximální hodnoty přesměrování a řetězce uživatelského agenta. Můžete ho použít ke sdílení stavu a dat mezi webovými požadavky.
Pokud chcete použít relaci webového požadavku v následných webových požadavcích, zadejte proměnnou relace v hodnotě parametru WebSession . PowerShell při navazování nového připojení používá data v objektu relace webového požadavku. Pokud chcete přepsat hodnotu v relaci webového požadavku, použijte parametr rutiny, například UserAgent nebo Credential. Hodnoty parametrů mají přednost před hodnotami v relaci webového požadavku.
Ve stejném příkazu nemůžete použít parametry SessionVariable a WebSession .
Type: | String |
Aliases: | SV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TimeoutSec
Určuje, jak dlouho může požadavek čekat, než vyprší časový limit. Zadejte hodnotu v sekundách. Výchozí hodnota 0 určuje neomezený časový limit.
Vrácení nebo vypršení časového limitu dotazu DNS (Domain Name System) může trvat až 15 sekund. Pokud váš požadavek obsahuje název hostitele, který vyžaduje překlad, a nastavíte hodnotu TimeoutSec na hodnotu větší než nula, ale méně než 15 sekund, může trvat 15 sekund nebo déle, než se vyvolá výjimka WebException a vyprší časový limit požadavku.
Type: | Int32 |
Position: | Named |
Default value: | 0 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TransferEncoding
Určuje hodnotu hlavičky odpovědi HTTP kódování přenosu. Tento parametr přijímá tyto hodnoty:
Chunked
Compress
Deflate
GZip
Identity
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
Určuje identifikátor URI (Uniform Resource Identifier) internetového prostředku, do kterého se odešle webový požadavek. Tento parametr podporuje hodnoty HTTP, HTTPS, FTP a FILE.
Tento parametr je povinný. Název parametru (Uri) je volitelný.
Type: | Uri |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseBasicParsing
Označuje, že rutina používá základní analýzu. Rutina vrátí nezpracovaný kód HTML v objektu String .
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseDefaultCredentials
Použije přihlašovací údaje aktuálního uživatele k odeslání webové žádosti.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UserAgent
Určuje řetězec uživatelského agenta pro webový požadavek.
Výchozí uživatelský agent je podobný "Mozilla/5.0 (systém Windows NT; systém Windows NT 6.1; en-US) WindowsPowerShell/3.0" s mírnými variacemi pro každý operační systém a platformu.
K otestování webu se standardním řetězcem uživatelského agenta, který používá většina internetových prohlížečů, použijte vlastnosti třídy PSUserAgent , jako je Chrome, FireFox, Internet Explorer, Opera a Safari.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WebSession
Určuje relaci webové žádosti. Zadejte název proměnné včetně znaku dolaru ($
).
Pokud chcete přepsat hodnotu v relaci webového požadavku, použijte parametr rutiny, například UserAgent nebo Credential. Hodnoty parametrů mají přednost před hodnotami v relaci webového požadavku.
Na rozdíl od vzdálené relace není relace webového požadavku trvalým připojením. Jedná se o objekt, který obsahuje informace o připojení a požadavku, včetně souborů cookie, přihlašovacích údajů, maximální hodnoty přesměrování a řetězce uživatelského agenta. Můžete ho použít ke sdílení stavu a dat mezi webovými požadavky.
Pokud chcete vytvořit relaci webového požadavku, zadejte do hodnoty parametru SessionVariable příkazu název proměnné (bez znaku dolaru Invoke-RestMethod
). Invoke-RestMethod
vytvoří relaci a uloží ji do proměnné. V dalších příkazech použijte proměnnou jako hodnotu parametru WebSession .
Ve stejném příkazu nelze použít parametry SessionVariable a WebSession .
Type: | WebRequestSession |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Vstupy
Do této rutiny můžete převést text webového požadavku.
Výstupy
Když požadavek vrátí celé číslo, vrátí tato rutina toto celé číslo.
Když požadavek vrátí řetězec, vrátí tato rutina tento řetězec.
Když požadavek vrátí platný kód XML, tato rutina ji vrátí jako XmlDocument.
PSObject
Když požadavek vrátí řetězce JSON, vrátí tato rutina objekt PSObject představující data.
Poznámky
Windows PowerShell obsahuje následující aliasy pro Invoke-RestMethod
:
irm
Související odkazy
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro