Invoke-RestMethod
Odešle požadavek HTTP nebo HTTPS do webové služby RESTful.
Syntax
Default (Výchozí)
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 REST (Representational State Transfer), které vrací bohatě strukturovaná data.
Windows PowerShell formátuje odpověď na základě datového typu. V případě informačního kanálu RSS nebo ATOM vrátí Windows PowerShell uzly XML položky nebo položky. V případě javascriptového zápisu objektu (JSON) nebo XML převede Windows PowerShell (nebo deserializuje) obsah na objekty.
Tento cmdlet je zaveden ve Windows PowerShell 3.0.
Poznámka:
Ve výchozím nastavení se kód skriptu na webové stránce může spustit, když je stránka analyzována, aby se naplnila vlastnost ParsedHtml.
K potlačení použijte přepínač -UseBasicParsing.
Parametry
-Body
Určuje text požadavku.
Text je obsah požadavku, který následuje za hlavičkami.
Můžete také přesměrovat hodnotu těla do Invoke-RestMethod.
Parametr -Body lze použít k zadání seznamu parametrů dotazu nebo zadání obsahu odpovědi.
Když je vstupem požadavek GET a tělo je IDictionary (obvykle hashovací tabulka), tělo se přidá do URI jako parametry v 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.
upozornění: Podrobný výstup těla POST skončí with -1-byte payload, i když je velikost těla známá a odeslána v hlavičce Content-Length HTTP.
Pokud je tělo formuláře nebo výstupem jiného volání Invoke-WebRequest, Windows PowerShell nastaví obsah požadavku na pole formuláře.
Napří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]
Vlastnosti parametru
| Typ: | Object |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | True |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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.
Vlastnosti parametru
| Typ: | X509Certificate |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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ů. Mohou být mapovány pouze na místní uživatelské účty; nefungují s doménovými účty.
Pokud chcete získat kryptografický otisk certifikátu, použijte příkaz Get-Item nebo Get-ChildItem na jednotce Windows PowerShellu (Cert:).
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Credential
Určuje uživatelský účet, který má oprávnění k odeslání požadavku. Výchozí hodnota je aktuální uživatel.
Zadejte uživatelské jméno, například "User01" nebo "Domain01\User01", nebo zadejte PSCredential objekt, například objekt vygenerovaný rutinou Get-Credential.
Vlastnosti parametru
| Typ: | PSCredential |
| Default value: | Current user |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-DisableKeepAlive
Nastaví hodnotu KeepAlive v hlavičce HTTP na False. Ve výchozím nastavení je KeepAlive True. KeepAlive vytvoří trvalé připojení k serveru, aby se usnadnily následné požadavky.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | KeepAlive |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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.
Vlastnosti parametru
| Typ: | IDictionary |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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í.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-MaximumRedirection
Určuje, kolikrát Windows PowerShell přesměruje připojení na alternativní identifikátor URI (Uniform Resource Identifier), než připojení selže. Výchozí hodnota je 5. Hodnota 0 (nula) zabraňuje veškerému přesměrování.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 5 |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Method
Určuje metodu použitou pro webový požadavek. Přijatelné hodnoty pro tento parametr jsou:
- Výchozí
- Vymazat
- Získat
- Hlava
- Sloučit
- Možnosti
- Aktualizace
- Příspěvek
- Put
- Trasování
Vlastnosti parametru
| Typ: | WebRequestMethod |
| Default value: | Default |
| Přípustné hodnoty: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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 potrubí.
Pokud chcete výsledky odeslat do souboru a do kanálu, použijte parametr -Passthru.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-PassThru
Vrátí výsledky kromě jejich zápisu do souboru.
Tento parametr je platný pouze v případě, že se v příkazu použije také parametr -OutFile.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | No output |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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.
Vlastnosti parametru
| Typ: | Uri |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-ProxyCredential
Určuje uživatelský účet, který má oprávnění používat proxy server určený parametrem -Proxy.
Výchozí hodnota je aktuální uživatel.
Zadejte uživatelské jméno, například "User01" nebo "Domain01\User01", nebo zadejte PSCredential objekt, například objekt vygenerovaný rutinou Get-Credential.
Tento parametr je platný pouze v případě, že se v příkazu použije také parametr -Proxy.
Ve stejném příkazu nelze použít parametry -ProxyCredential a -ProxyUseDefaultCredentials.
Vlastnosti parametru
| Typ: | PSCredential |
| Default value: | Current user |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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žije také parametr -Proxy.
Ve stejném příkazu nelze použít parametry -ProxyCredential a -ProxyUseDefaultCredentials.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-SessionVariable
Vytvoří relaci webového požadavku a uloží ji do hodnoty zadané proměnné.
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 Windows PowerShellu.
Proměnnou můžete v relaci 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.
Windows PowerShell používá data v objektu relace webového požadavku při navazování nového připojení.
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 nelze použít parametry -SessionVariable a -WebSession.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
| Aliasy: | SV |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 0 |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-TransferEncoding
Určuje hodnotu hlavičky odpovědi HTTP pro kódování přenosu. Přijatelné hodnoty pro tento parametr jsou:
- Rozdělený
- Komprimovat
- Vyfouknout
- GZip
- Identita
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Přípustné hodnoty: | chunked, compress, deflate, gzip, identity |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | 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ý.
Vlastnosti parametru
| Typ: | Uri |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | 0 |
| Povinné: | True |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-UseBasicParsing
Označuje, že cmdlet používá základní analýzu. Cmdlet vrátí nezpracovaný kód HTML v objektu String.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-UseDefaultCredentials
Použije přihlašovací údaje aktuálního uživatele k odeslání webové žádosti.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-UserAgent
Určuje řetězec uživatelského agenta pro webový požadavek.
Výchozí uživatelský agent je podobný "Mozilla/5.0 (Windows NT; 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 PSUserAgent třídy, jako je Chrome, FireFox, Internet Explorer, Opera a Safari.
Například následující příkaz používá řetězec uživatelského agenta pro internet.
Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-WebSession
Určuje relaci webového požadavku.
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 Invoke-RestMethod název proměnné (bez znaku dolaru).
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.
Vlastnosti parametru
| Typ: | WebRequestSession |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
CommonParameters
Tato rutina podporuje běžné parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction a -WarningVariable. Další informace najdete v about_CommonParameters.
Vstupy
Object
Text webového požadavku můžete převést na Invoke-RestMethod.
Výstupy
System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String
Výstup rutiny závisí na formátu načteného obsahu.
PSObject
Pokud požadavek vrátí řetězce JSON, Invoke-RestMethod vrátí objekt PSObject, který představuje řetězce.