Invoke-RestMethod

Odešle požadavek HTTP nebo HTTPS webové službě RESTful.

Syntax

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]
Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]
Invoke-RestMethod
      -CustomMethod <String>
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]
Invoke-RestMethod
      -CustomMethod <String>
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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.

PowerShell naformátuje odpověď na základě datového typu. Pro informační kanál RSS nebo ATOM vrátí PowerShell uzly Item nebo Entry XML. Pro JavaScript Object Notation (JSON) nebo XML, PowerShell převede 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 výstup předáte z Invoke-RestMethod jiného příkazu, odešle se jako jeden [Object[]] objekt. Obsah tohoto pole není výčtem dalšího příkazu v kanálu.

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

Počínaje PowerShellem 7.0 Invoke-RestMethod podporuje konfiguraci proxy serveru definovanou proměnnými prostředí. Viz část Poznámky tohoto článku.

Příklady

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

Tento příklad 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.

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

Příklad 2: Spuštění požadavku POST

V tomto příkladu uživatel spustí Invoke-RestMethod požadavek POST na intranetovém webu v organizaci uživatele.

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

Přihlašovací údaje se zobrazí výzva k zadání a následnému uložení a $Cred adrese URL, která bude mít přístup, je definována v $Url.

Proměnná $Body popisuje kritéria hledání, určuje csv jako výstupní režim a určuje časové období pro vrácená data, která začínají před dvěma dny a končí před dvěma dny. Proměnná těla určuje hodnoty parametrů, které se vztahují na konkrétní rozhraní REST API, se kterým Invoke-RestMethod komunikuje.

Příkaz Invoke-RestMethod se spustí se všemi proměnnými, které určují cestu a název souboru pro výsledný výstupní soubor CSV.

Příklad 3: Sledování odkazů na relace

Některá rozhraní REST API podporují stránkování prostřednictvím relačních odkazů na RFC5988. Místo analýzy záhlaví získáte adresu URL pro další stránku, můžete tuto rutinu provést za vás. Tento příklad vrátí první dvě stránky problémů z úložiště GitHub PowerShellu.

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Příklad 4: Zjednodušené odeslání více částí nebo formulářových dat

Některá rozhraní API vyžadují multipart/form-data odeslání k nahrání souborů a smíšeného obsahu. Tento příklad ukazuje, jak aktualizovat profil uživatele.

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form

Formulář profilu vyžaduje tato pole: firstName, lastName, emailavatar, , birthdaya hobbies. Rozhraní API očekává, že obrázek obrázku profilu uživatele bude zadán v avatar poli. Rozhraní API také přijme více hobbies položek, které se mají odeslat ve stejném formuláři.

Při vytváření $Form hashtable se názvy klíčů používají jako názvy polí formuláře. Ve výchozím nastavení se hodnoty hashtable převedou na řetězce. System.IO.FileInfo Pokud je hodnota k dispozici, obsah souboru se odešle. Pokud existuje kolekce, jako jsou pole nebo seznamy, bude pole formuláře odesláno několikrát.

Get-ItemavatarFileInfo Pomocí klíče se objekt nastaví jako hodnota. Výsledkem je odeslání dat obrázku.jdoe.png

Zadáním seznamu hobbies klíči hobbies se pole zobrazí v odesláních jednou pro každou položku seznamu.

Příklad 5: Předání více hlaviček

Rozhraní API často vyžadují předané hlavičky pro ověřování nebo ověření. 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

Příklad 6: Výčet 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 ji 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ů, které jsou v kanálu výčtu.

$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

Příklad 7: Přeskočení ověření hlavičky

Ve výchozím nastavení Invoke-RestMethod rutina ověří hodnoty dobře známých hlaviček, které mají formát standardních hodnot definovaných standardem. Následující příklad ukazuje, jak toto ověření může vyvolat chybu a jak můžete použít parametr SkipHeaderValidation , abyste se vyhnuli ověřování hodnot pro koncové body, které tolerují neplatné formátované hodnoty.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org je služba, která vrací informace o webových požadavcích a odpovědích pro řešení potíží. Proměnná $Uri se přiřadí ke koncovému /headers bodu služby, který vrátí hlavičky požadavku jako obsah v odpovědi.

Hlavička If-Match požadavku je definována v dokumentu RFC-7232 oddíl 3.1 a vyžaduje, aby byla hodnota pro danou hlavičku definována s okolními uvozovkami. Proměnná $InvalidHeaders má přiřazenou tabulku hash, ve které je hodnota If-Match neplatná, protože je definována jako 12345 místo "12345".

Volání Invoke-RestMethod s neplatnými záhlavími vrátí chybovou zprávu, že formátovaná hodnota je neplatná. Požadavek se do koncového bodu neodesílají.

Volání Invoke-RestMethod pomocí parametru SkipHeaderValidation ignoruje chybu ověření a odešle požadavek do koncového bodu. Vzhledem k tomu, že koncový bod toleruje nekompatibilní hodnoty hlaviček, vrátí rutina objekt odpovědi bez chyby.

Parametry

-AllowUnencryptedAuthentication

Umožňuje odesílání přihlašovacích údajů a tajných kódů přes nešifrovaná připojení. Ve výchozím nastavení zadání přihlašovacích údajů nebo jakékoli možnosti ověřování pomocí identifikátoru URI , který nezačíná https:// , způsobí chybu a požadavek přeruší, aby se zabránilo neúmyslné komunikaci tajných kódů v prostém textu přes nešifrovaná připojení. Pokud chcete toto chování přepsat na vlastní riziko, zadejte parametr AllowUnencryptedAuthentication .

Upozornění

Použití tohoto parametru není zabezpečené a nedoporučuje se. Poskytuje se pouze kvůli kompatibilitě se staršími systémy, které nemohou poskytovat šifrovaná připojení. Používejte vlastní riziko.

Tato funkce byla přidána v PowerShellu 6.0.0.

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

-Authentication

Určuje explicitní typ ověřování, který se má použít pro požadavek. Výchozí hodnota je Žádná. Parametr ověřování nelze použít s parametrem UseDefaultCredentials .

Dostupné možnosti ověřování:

  • None: Toto je výchozí možnost, pokud není zadáno ověřování . Nebude použito žádné explicitní ověřování.
  • Basic: Vyžaduje přihlašovací údaje. Přihlašovací údaje se použijí k odeslání hlavičky základního ověřování Authorization: Basic RFC 7617 ve formátu base64(user:password).
  • Bearer: Vyžaduje parametr tokenu . Odešle hlavičku RFC 6750 Authorization: Bearer se zadaným tokenem.
  • OAuth: Vyžaduje parametr tokenu . Odešle hlavičku RFC 6750 Authorization: Bearer se zadaným tokenem.

Zadávání ověřování přepíše všechny Authorization hlavičky zadané do hlaviček nebo zahrnutých ve službě WebSession.

Tato funkce byla přidána v PowerShellu 6.0.0.

Type:WebAuthenticationType
Accepted values:None, Basic, Bearer, OAuth
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-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), text se přidá do identifikátoru URI (Uniform Resource Identifier) 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.

Pokud je text formulářem nebo výstupem jiného Invoke-WebRequest volání, PowerShell nastaví obsah požadavku na pole formuláře.

Parametr Body může také přijmout System.Net.Http.MultipartFormDataContent objekt. To usnadní multipart/form-data žádosti. Pokud je objekt MultipartFormDataContent zadán pro body, všechny hlavičky související s obsahem zadané contentType, Headers nebo WebSession parametry budou přepsány hlavičkami obsahu objektu MultipartFormDataContent . Tato funkce byla přidána v PowerShellu 6.0.0.

Type:Object
Position:Named
Default value:None
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
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 příkaz Get-ItemGet-ChildItem nebo příkaz na jednotce PowerShellu Cert: .

Poznámka

Tato funkce je aktuálně podporována pouze na platformách operačního systému Windows.

Type:String
Position:Named
Default value:None
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 zadaný ve volání.

ContentType se přepíše při zadání objektu MultipartFormDataContent pro body.

Type:String
Position:Named
Default value:None
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ý rutinou Get-Credential .

Přihlašovací údaje lze použít samostatně nebo ve spojení s některými možnostmi parametrů ověřování . Pokud vzdálený server odešle žádost o výzvu k ověření, bude při použití samostatně zadávat přihlašovací údaje pouze vzdálenému serveru. Při použití s možnostmi ověřování se přihlašovací údaje explicitně odešlou.

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
Accept pipeline input:False
Accept wildcard characters:False

-CustomMethod

Určuje vlastní metodu použitou pro webový požadavek. Tuto možnost lze použít s metodou požadavku požadovanou koncovým bodem není k dispozici v metodě. Metodu a CustomMethod nelze použít společně.

Příklad:

Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Tím se vytvoří TEST požadavek HTTP na rozhraní API.

Tato funkce byla přidána v PowerShellu 6.0.0.

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

-DisableKeepAlive

Označuje, že rutina nastaví hodnotu KeepAlive v hlavičce HTTP na 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:False
Accept pipeline input:False
Accept wildcard characters:False

-FollowRelLink

Označuje, že rutina by měla sledovat odkazy na relace.

Některá rozhraní REST API podporují stránkování prostřednictvím relačních odkazů na RFC5988. Místo analýzy záhlaví získáte adresu URL pro další stránku, můžete tuto rutinu provést za vás. Chcete-li nastavit, kolikrát chcete sledovat relační odkazy, použijte parametr MaximumFollowRelLink .

Při použití tohoto přepínače vrátí rutina kolekci stránek výsledků. Každá stránka výsledků může obsahovat více položek výsledků.

Tato funkce byla přidána v PowerShellu 6.0.0.

Type:SwitchParameter
Aliases:FL
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Form

Převede slovník na multipart/form-data odeslání. Formulář nelze použít s textem. Pokud bude ContentType ignorováno.

Klíče slovníku se použijí jako názvy polí formuláře. Ve výchozím nastavení se hodnoty formuláře převedou na řetězcové hodnoty.

Pokud je hodnota Objekt System.IO.FileInfo , odešle se obsah binárního souboru. Název souboru bude odeslán jako filename. MIME se nastaví jako application/octet-stream. Get-Item lze použít ke zjednodušení zadávání objektu System.IO.FileInfo .

$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

Pokud je hodnota typu kolekce, například Pole nebo Seznam, bude pole pro pole odesláno několikrát. Hodnoty seznamu budou ve výchozím nastavení považovány za řetězce. Pokud je hodnota Objekt System.IO.FileInfo , odešle se obsah binárního souboru. Vnořené kolekce se nepodporují.

$Form = @{ tags = 'Vacation', 'Itálie', '2017' obrázky = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

V předchozím příkladu tags bude pole zadáno třikrát ve formuláři, jednou pro každý z Vacation, Italya 2017. Pole pictures se odešle také jednou pro každý soubor ve 2017-Italy složce. Binární obsah souborů v této složce se odešle jako hodnoty.

Tato funkce byla přidána v PowerShellu 6.1.0.

Type:IDictionary
Position:Named
Default value:None
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 určení User-Agent hlaviček souborů cookie nebo jejich použití.

Hlavičky související s obsahem, například Content-Type budou přepsány při zadání objektu MultipartFormDataContent pro body.

Type:IDictionary
Position:Named
Default value:None
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
Accept pipeline input:False
Accept wildcard characters:False

-MaximumFollowRelLink

Určuje, kolikrát se mají sledovat relační odkazy, pokud se používá FollowRelLink . Pokud rozhraní REST API omezuje příliš mnoho požadavků, může být potřeba menší hodnota. Výchozí hodnota je [Int32]::MaxValue. Hodnota 0 (nula) brání následujícím odkazům na relace.

Type:Int32
Aliases:ML
Position:Named
Default value:Int32.MaxValue
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

Určuje, kolikrát 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:None
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRetryCount

Určuje, kolikrát PowerShell opakuje připojení, když se zobrazí kód selhání mezi 400 a 599 včetně nebo 304. Viz také parametr RetryIntervalSec pro určení počtu opakování.

Type:Int32
Position:Named
Default value:None
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

Parametr CustomMethod lze použít pro metody požadavku, které nejsou uvedené výše.

Type:WebRequestMethod
Accepted values:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NoProxy

Označuje, že rutina nebude k dosažení cíle používat proxy server.

Pokud potřebujete obejít proxy server nakonfigurovaný v Aplikaci Internet Explorer nebo proxy server zadaný v prostředí, použijte tento přepínač.

Tento parametr byl zaveden v PowerShellu 6.0.

Type:SwitchParameter
Position:Named
Default value: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í. Název se považuje za literálovou cestu. Názvy obsahující závorky ([]) musí být uzavřeny v jednoduchých uvozovkách (').

Ve výchozím nastavení Invoke-RestMethod vrátí výsledky do kanálu.

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

-PassThru

Tento parametr je platný pouze v případě, že se parametr OutFile používá také v příkazu. Záměrem je, aby se výsledky zapisovaly do souboru a do kanálu.

Poznámka

Když použijete parametr PassThru , výstup se zapíše do kanálu, ale soubor se nevytvořil. Další informace najdete v tématu Problém PowerShellu č. 15409.

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

-PreserveAuthorizationOnRedirect

Označuje, že rutina by měla zachovat hlavičku Authorization , pokud je k dispozici, napříč přesměrováními.

Ve výchozím nastavení rutina před přesměrováním Authorization odstraní záhlaví. Zadáním tohoto parametru tuto logiku zakážete v případech, kdy se hlavička musí odeslat do umístění přesměrování.

Tato funkce byla přidána v PowerShellu 6.0.0.

Type:SwitchParameter
Position:Named
Default value: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 (Uniform Resource Identifier) síťového proxy serveru.

Tato funkce byla přidána v PowerShellu 6.0.0.

Type:Uri
Position:Named
Default value:None
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, User@Domain.Comnebo zadejte PSCredential objekt, 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 . Parametry ProxyCredential a ProxyUseDefaultCredentials nemůžete použít ve stejném příkazu.

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

-ProxyUseDefaultCredentials

Označuje, že rutina 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 . Parametry ProxyCredential a ProxyUseDefaultCredentials nemůžete použít ve stejném příkazu.

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

-ResponseHeadersVariable

Vytvoří proměnnou obsahující slovník Hlavičky odpovědi. Zadejte název proměnné bez symbolu dolaru ($). Klíče slovníku obsahují názvy polí a hodnoty hlavičky odpovědi vrácené webovým serverem.

Tato funkce byla přidána v PowerShellu 6.0.0.

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

-Resume

Snaží se obnovit stahování částečného souboru. Parametr Resume vyžaduje parametr OutFile .

Resume funguje jenom s velikostí místního souboru a vzdáleného souboru a neprovádí žádné jiné ověření, že místní soubor a vzdálený soubor jsou stejné.

Pokud je velikost místního souboru menší než velikost vzdáleného souboru, rutina se pokusí obnovit stahování souboru a připojit zbývající bajty na konec souboru.

Pokud je velikost místního souboru stejná jako velikost vzdáleného souboru, není provedena žádná akce a rutina předpokládá, že stahování už bylo dokončeno.

Pokud je velikost místního souboru větší než velikost vzdáleného souboru, místní soubor se přepíše a celý vzdálený soubor se úplně znovu stáhne. Toto chování je stejné jako použití souboru OutFile bez funkce Resume.

Pokud vzdálený server nepodporuje obnovení stahování, místní soubor se přepíše a celý vzdálený soubor se úplně znovu stáhne. Toto chování je stejné jako použití souboru OutFile bez funkce Resume.

Pokud místní soubor neexistuje, vytvoří se místní soubor a celý vzdálený soubor se úplně stáhne. Toto chování je stejné jako použití souboru OutFile bez funkce Resume.

Tato funkce byla přidána v PowerShellu 6.1.0.

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

-RetryIntervalSec

Určuje interval mezi opakovanými pokusy o připojení, když se obdrží kód chyby mezi 400 a 599 včetně nebo 304. Viz také parametr MaximumRetryCount pro určení počtu opakování. Hodnota musí být mezi 1 a [int]::MaxValue.

Type:Int32
Position:Named
Default value:5
Accept pipeline input:False
Accept wildcard characters:False

-SessionVariable

Vytvoří proměnnou obsahující relaci webové žádosti. Zadejte název proměnné bez symbolu dolaru ($).

Když zadáte proměnnou relace, Invoke-RestMethod vytvoří objekt relace webové žádosti a přiřadí ho proměnné se zadaným názvem v relaci PowerShellu. Proměnnou můžete ve své relaci použít hned po dokončení příkazu.

Na rozdíl od vzdálené relace není relace webové žádosti 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 dalších webových požadavcích, zadejte proměnnou relace v hodnotě parametru WebSession . PowerShell používá data v objektu relace webové žádosti při navazování nového připojení. 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.

Parametry SessionVariable a WebSession nemůžete použít ve stejném příkazu.

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

-SkipCertificateCheck

Přeskočí kontroly ověření certifikátu, které zahrnují všechna ověření, jako je vypršení platnosti, odvolání, důvěryhodná kořenová autorita atd.

Upozornění

Použití tohoto parametru není zabezpečené a nedoporučuje se. Účelem tohoto přepínače je použít pouze u známých hostitelů, kteří používají certifikát podepsaný svým držitelem pro účely testování. Používejte na vlastní nebezpečí.

Tato funkce byla přidána v PowerShellu 6.0.0.

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

-SkipHeaderValidation

Označuje, že rutina by měla do požadavku přidat hlavičky bez ověření.

Tento přepínač by se měl používat pro weby, které vyžadují hodnoty hlaviček, které nevyhovují standardům. Zadáním tohoto přepínače zakážete ověření, aby byla hodnota předána nezaškrtnutá. Při zadání se všechny hlavičky přidají bez ověření.

Tím se zakáže ověření hodnot předaných parametrům ContentType, Headers a UserAgent .

Tato funkce byla přidána v PowerShellu 6.0.0.

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

-SkipHttpErrorCheck

Tento parametr způsobí, že rutina ignoruje stavy chyb HTTP a bude dál zpracovávat odpovědi. Odpovědi na chyby se zapíšou do kanálu stejně, jako kdyby byly úspěšné.

Tento parametr byl představen v PowerShellu 7.

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

-SslProtocol

Nastaví protokoly SSL/TLS, které jsou pro webový požadavek přípustné. Ve výchozím nastavení jsou povolené protokoly SSL/TLS podporované systémem. SslProtocol umožňuje omezit na konkrétní protokoly pro účely dodržování předpisů.

Tyto hodnoty jsou definovány jako výčet založený na příznaku. Pomocí tohoto parametru můžete zkombinovat více hodnot a nastavit více příznaků. Hodnoty lze předat parametru SslProtocol jako pole hodnot nebo jako řetězec oddělený čárkami těchto hodnot. Rutina zkombinuje hodnoty pomocí binární operace OR. Předání hodnot jako pole je nejjednodušší možností a také umožňuje použít pro hodnoty dokončování tabulátoru. Na všech platformách možná nebudete moct zadat více hodnot.

Poznámka

Na jiných platformách než Windows nemusí být možné zadat Tls ani Tls12 jako možnost. Tls13 Podpora není k dispozici ve všech operačních systémech a bude nutné ji ověřit na základě jednotlivých operačních systémů.

Tato funkce byla přidána v PowerShellu 6.0.0 a podpora byla Tls13 přidána v PowerShellu 7.1.

Type:WebSslProtocol
Accepted values:Default, Tls, Tls11, Tls12, Tls13
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-StatusCodeVariable

Vytvoří proměnnou obsahující výsledek stavového kódu HTTP požadavku. Zadejte název proměnné bez symbolu dolaru ($).

Parametr může identifikovat zprávy o úspěchu nebo chybové zprávy při použití s parametrem SkipHttpErrorCheck .

Zadejte název proměnné parametru jako řetězec, například -StatusCodeVariable "scv".

Tento parametr byl představen v PowerShellu 7.

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

-TimeoutSec

Určuje, jak dlouho může být požadavek čekající, než vyprší časový limit. Zadejte hodnotu v sekundách. Výchozí hodnota 0 určuje neurčitý č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 časový limitSec na hodnotu větší než nula, ale méně než 15 sekund, může trvat 15 sekund nebo více, než se vyvolá výjimka WebException a vyprší časový limit požadavku.

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

-Token

Token OAuth nebo Bearer, který se má zahrnout do požadavku. Token je vyžadován určitými možnostmi ověřování . Nedá se použít nezávisle.

Token přebírá SecureString token obsahující token. Pokud chcete token zadat, použijte ručně následující:

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Tento parametr byl zaveden v PowerShellu 6.0.

Type:SecureString
Position:Named
Default value:None
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:

  • Blokového
  • Komprimovat
  • Deflaci
  • Gzip
  • Identita
Type:String
Accepted values:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
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
Accept pipeline input:False
Accept wildcard characters:False

-UseBasicParsing

Tento parametr je zastaralý. Počínaje PowerShellem 6.0.0 používají všechny webové požadavky pouze základní parsování. Tento parametr je zahrnut pouze pro zpětnou kompatibilitu a jakékoli jeho použití nebude mít žádný vliv na operaci rutiny.

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

-UseDefaultCredentials

Označuje, že rutina používá přihlašovací údaje aktuálního uživatele k odeslání webové žádosti. Tuto možnost nelze použít s ověřováním nebo přihlašovacími údaji a nemusí být podporována na všech platformách.

Type:SwitchParameter
Position:Named
Default value: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 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 mírné variantě pro každý operační systém a platformu.

Chcete-li 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, InternetExplorer, Opera a Safari.

Type:String
Position:Named
Default value:None
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. Při zadání objektu MultipartFormDataContent pro body se přepíše také hlavičky související s obsahem, například Content-Type.

Na rozdíl od vzdálené relace není relace webové žádosti 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 název proměnné bez znaku dolaru do hodnoty parametru Invoke-RestMethodSessionVariable 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 .

Parametry SessionVariable a WebSession nemůžete použít ve stejném příkazu.

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

Vstupy

Object

Text webové žádosti můžete převést na Invoke-RestMethod.

Výstupy

System.Int64, System.String, System.Xml.XmlDocument

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.

Poznámky

Některé funkce nemusí být dostupné na všech platformách.

Kvůli změnám v .NET Core 3.1 použijte PowerShell 7.0 a vyšší vlastnost HttpClient.DefaultProxy k určení konfigurace proxy serveru.

Hodnota této vlastnosti je různá pravidla v závislosti na vaší platformě:

  • Pro Windows: Načte konfiguraci proxy serveru z proměnných prostředí nebo pokud nejsou definované, z nastavení proxy serveru uživatele.
  • Pro macOS: Čte konfiguraci proxy serveru z proměnných prostředí nebo pokud nejsou definované, z nastavení proxy serveru systému.
  • Pro Linux: Načte konfiguraci proxy serveru z proměnných prostředí nebo v případě, že nejsou definovány, tato vlastnost inicializuje nekonfigurovanou instanci, která obchází všechny adresy.

Proměnné prostředí používané k DefaultProxy inicializaci na platformách se systémem Windows a Unix jsou:

  • HTTP_PROXY: název hostitele nebo IP adresa proxy serveru používaného v požadavcích HTTP.
  • HTTPS_PROXY: název hostitele nebo IP adresa proxy serveru používaného pro požadavky HTTPS.
  • ALL_PROXY: název hostitele nebo IP adresa proxy serveru používaného v požadavcích HTTP a HTTPS v případě HTTP_PROXY , že HTTPS_PROXY nejsou definovány.
  • NO_PROXY: Seznam názvů hostitelů oddělených čárkami, které by měly být vyloučeny z proxy serveru.