Invoke-RestMethod

  • Reference
Modul:
Microsoft.PowerShell.Utility

Odešle požadavek HTTP nebo HTTPS webové službě 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 REST (Representational State Transfer), které vrací bohatě strukturovaná data.

Windows PowerShell formátuje odpověď na základě datového typu. U informačního kanálu RSS nebo ATOM Windows PowerShell vrátí uzly Item nebo Entry XML. Pro JavaScript Object Notation (JSON) nebo XML Windows PowerShell převede (nebo deserializuje) obsah na objekty.

Tato rutina se zavádí v Windows PowerShell 3.0.

Poznámka

Ve výchozím nastavení může být kód skriptu na webové stránce spuštěn, když je stránka analyzována, aby ParsedHtml se naplní vlastnost. K potlačení tohoto -UseBasicParsing přepínače použijte přepínač.

Příklady

Příklad 1: Získání informačního kanálu RSS PowerShellu

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

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

$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.

Tento příklad ukazuje, jak předat více hlaviček z hash-table rozhraní REST API.

Parametry

-Body

Určuje text požadavku. Tělo je obsah požadavku, který se řídí hlavičkami. Můžete také roušit hodnotu těla na Invoke-RestMethod.

Parametr -Body lze použít k určení seznamu parametrů dotazu nebo určení obsahu odpovědi.

Když je vstup požadavek GET a text je IDictionary (obvykle tabulka hash), 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 formátu standard name=value.

Upozornění: Podrobný výstup textu POST skončí with -1-byte payload, i když je velikost těla známá i odeslaná v Content-Length hlavičce HTTP.

Pokud je text formuláře nebo je výstupem jiného Invoke-WebRequest volání, Windows 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]. Heslo = "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

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í v ověřování založeném na klientských certifikátech. Je možné je namapovat pouze na místní uživatelské účty; nefungují s doménovými účty.

Pokud chcete získat kryptografický otisk certifikátu, použijte na Get-ItemGet-ChildItem jednotce Windows PowerShell (Cert:) příkaz nebo příkaz.

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í typ obsahu zadán ve volání.

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 , například jeden vygenerovaný rutinou Get-Credential .

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 Hodnotu False. Funkce KeepAlive je ve výchozím nastavení true. KeepAlive vytvoří trvalé připojení k serveru, aby bylo možné usnadnit 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.

Pokud chcete nastavit hlavičky UserAgent, použijte parametr -UserAgent . Tento parametr nelze použít k zadání hlaviček 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é žádosti 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) před selháním připojení. Výchozí hodnota je 5. Hodnota 0 (nula) brání 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:

  • Výchozí
  • Odstranit
  • Získat
  • Head
  • Sloučit
  • Možnosti
  • Patch
  • Příspěvek
  • Put
  • Trasování
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ží text 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. Pokud chcete výsledky odeslat do souboru a do kanálu, použijte -Passthru parametr.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Vrátí výsledky kromě jejich zápisu do souboru. Tento parametr je platný pouze v případě, že -OutFile se parametr používá také v příkazu.

Type:SwitchParameter
Position:Named
Default value:No output
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Proxy

Používá proxy server pro požadavek místo přímého připojení k internetovému prostředku. 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 jeden vygenerovaný rutinou Get-Credential .

Tento parametr je platný pouze v případě, že -Proxy se parametr používá také v příkazu. Ve stejném příkazu nelze použít -ProxyCredential parametry a -ProxyUseDefaultCredentials parametry.

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ého parametrem -Proxy .

Tento parametr je platný pouze v případě, že -Proxy se parametr používá také v příkazu. Ve stejném příkazu nelze použít -ProxyCredential parametry a -ProxyUseDefaultCredentials parametry.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SessionVariable

Vytvoří relaci webové žádosti 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 PowerShell. 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 agenta uživatele. 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 při vytváření nového připojení používá data v objektu relace webové žádosti. Pokud chcete přepsat hodnotu v relaci webové žádosti, 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 -SessionVariable parametry a -WebSession parametry.

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 neomezenou dobu vypršení časového limitu.

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 vy nastavíte timeoutSec na hodnotu větší než nula, ale méně než 15 sekund, může trvat 15 sekund nebo více, než se vyvolá webException a váš požadavek vyprší.

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 pro kódování přenosu. Tento parametr přijímá tyto hodnoty:

  • Blokového
  • Komprimovat
  • Deflaci
  • Gzip
  • Identita
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í parsování. 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žívá 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 agenta uživatele 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.

Pokud chcete otestovat web 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.

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)

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é žádosti, 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 agenta uživatele. Můžete ho použít ke sdílení stavu a dat mezi webovými požadavky.

Pokud chcete vytvořit relaci webové žádosti, zadejte název proměnné (bez znaku dolaru) hodnotu -SessionVariable parametru Invoke-RestMethod příkazu. 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 -SessionVariable parametry a -WebSession parametry.

Type:WebRequestSession
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Vstupy

Object

Text webové žádosti 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.