Sdílet prostřednictvím

Invoke-WebRequest

Modul:
Microsoft.PowerShell.Utility Module

Získá obsah z webové stránky na internetu.

Syntax

StandardMethod (Výchozí) 

Invoke-WebRequest
    [-Uri] <Uri>
    [-UseBasicParsing]
    [-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>]
    [-Method <WebRequestMethod>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

StandardMethodNoProxy 

Invoke-WebRequest
    [-Uri] <Uri>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Method <WebRequestMethod>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

CustomMethod 

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    [-UseBasicParsing]
    [-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>]

CustomMethodNoProxy 

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

Description

Rutina Invoke-WebRequest odesílá požadavky HTTP a HTTPS na webovou stránku nebo webovou službu. Analyzuje odpověď a vrací kolekce odkazů, obrázků a dalších důležitých prvků HTML.

Tento cmdlet byl zaveden v PowerShellu 3.0.

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

Důležité

Příklady v tomto článku odkazují na hostitele v doméně contoso.com . Jedná se o fiktivní doménu používanou Microsoftem pro příklady. Příklady jsou navržené tak, aby ukázaly, jak tyto rutiny používat. Protože contoso.com však tyto stránky neexistují, příklady nefungují. Přizpůsobte příklady hostitelům ve vašem prostředí.

Příklady

Příklad 1: Odeslání webové žádosti

Tento příklad používá rutinu Invoke-WebRequest k odeslání webového požadavku na web Bing.com.

$Response = Invoke-WebRequest -URI https://www.bing.com/search?q=how+many+feet+in+a+mile
$Response.InputFields | Where-Object {
    $_.name -like "* Value*"
} | Select-Object Name, Value

name       value
----       -----
From Value 1
To Value   5280

První příkaz vydá požadavek a uloží odpověď do proměnné $Response.

Druhý příkaz získá jakýkoli InputField , kde name vlastnost je like "* Value". Filtrované výsledky se předají tak, aby Select-Object vybrali vlastnosti Název a Hodnota .

Příklad 2: Použití stavové webové služby

Tento příklad ukazuje, jak použít rutinu Invoke-WebRequest se stavovou webovou službou.

$Body = @{
    User = 'jdoe'
    password = 'P@S$w0rd!'
}
$LoginResponse = Invoke-WebRequest 'https://www.contoso.com/login/' -SessionVariable 'Session' -Body $Body -Method 'POST'

$Session

$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

$ProfileResponse

První volání, které Invoke-WebRequest odešle žádost o přihlášení. Příkaz určuje hodnotu "Session" pro hodnotu parametru -SessionVariable a uloží výsledek do proměnné $LoginResponse . Po dokončení příkazu proměnná $LoginResponse obsahuje an BasicHtmlWebResponseObject a proměnná $Session obsahuje WebRequestSession objekt. Tím se uživatel přihlásí na web.

Volání to $Session samo o sobě zobrazí WebRequestSession objekt v proměnné.

Druhé volání pro Invoke-WebRequest načtení profilu uživatele, které vyžaduje, aby byl uživatel přihlášen k webu. Údaje o relaci uložené v proměnné $Session se používají k poskytování souborů cookie relace webu vytvořených během přihlášení. Výsledek se uloží do proměnné $ProfileResponse .

Volání to $ProfileResponse samo o sobě zobrazí v BasicHtmlWebResponseObject proměnné.

Příklad 3: Získání odkazů z webové stránky

Tento příklad získá odkazy na webovou stránku. Používá rutinu Invoke-WebRequest k získání obsahu webové stránky. Poté použije vlastnost Links vráceného objektu a BasicHtmlWebResponseObjectInvoke-WebRequest vlastnost Href každého odkazu.

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

Příklad 4: Zapíše obsah odpovědi do souboru pomocí kódování definovaného na požadované stránce.

Tento příklad používá rutinu Invoke-WebRequest k načtení obsahu webové stránky stránky dokumentace PowerShellu.

$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
    $Stream.Write($Response.Content)
}
finally {
    $Stream.Dispose()
}

První příkaz načte stránku a uloží objekt odpovědi do $Response proměnné.

Druhý příkaz vytvoří příkaz a, který StreamWriter se použije k zápisu obsahu odpovědi do souboru. Vlastnost Kódování objektu odpovědi slouží k nastavení kódování souboru.

Posledních několik příkazů zapíše vlastnost Content do souboru a poté StreamWriterodstraní vlastnost .

Všimněte si, že vlastnost Kódování má hodnotu null, pokud webový požadavek nevrací textový obsah.

Příklad 5: Odeslání vícedílového/form-datového souboru

Tento příklad používá rutinu Invoke-WebRequest k nahrání souboru jako multipart/form-data odeslání. Soubor c:\document.txt je odeslán jako pole document formuláře s Content-Typetext/plain

$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'

$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)

$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)

$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'

Příklad 6: Zjednodušené odeslání více částí/dat formuláře

Některá rozhraní API vyžadují multipart/form-data podání pro nahrávání souborů a smíšeného obsahu. Tento příklad ukazuje aktualizaci profilu 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-WebRequest -Uri $Uri -Method Post -Form $Form

Formulář profilu vyžaduje tato pole: firstName, lastName, email, avatar, birthdaya hobbies. Rozhraní API očekává, že obrázek profilové fotky uživatele bude poskytnut v poli avatar. Rozhraní API také přijímá více položek hobbies k odeslání 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. Pokud je k dispozici hodnota System.IO.FileInfo, obsah souboru se odešle. Pokud existuje kolekce, jako jsou pole nebo seznamy, je pole formuláře odesláno několikrát.

Pomocí Get-Item na klíč avatar je objekt FileInfo nastaven jako hodnota. Výsledkem je, že data obrázku pro jdoe.png jsou odeslána.

Když do hobbies klíče zadáte seznam, zobrazí se pole hobbies v odesláních jednou pro každou položku seznamu.

Příklad 7: Zachycení zpráv, které nejsou úspěšné z invoke-WebRequest

Když Invoke-WebRequest narazí na zprávu HTTP bez úspěchu (404, 500 atd.), vrátí žádný výstup a vyvolá ukončující chybu. Chcete-li zachytit chybu a zobrazit StatusCode můžete uzavřít spuštění do bloku try/catch.

try
{
    $Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
}
catch
{
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

Ukončovací chyba je zachycena catch blokem, který načte StatusCode z objektu Exception .

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í má zadání přihlašovacích údajů nebo jakékoli možnosti ověřování s identifikátorem URI , který nezačíná na https:// , za následek chybu a požadavek se přeruší, aby se zabránilo neúmyslnému sdělování tajných kódů ve formátu prostého textu prostřednictvím nešifrovaných připojení. Pokud chcete toto chování přepsat na vlastní riziko, zadejte parametr AllowUnencryptedAuthentication.

Výstraha

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

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

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

-Authentication

Určuje explicitní typ ověřování, který se má použít pro požadavek. Výchozí hodnota je Žádná. Parametr Authentication 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ích údajů . Přihlašovací údaje se použijí k odeslání hlavičky základního Authorization: Basicověřování base64(user:password) RFC 7617 ve formátu .
  • 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ání Ověřování přepíše jakékoliv hlavičky Authorization zadané do Hlavičky nebo zahrnuté v rámci WebSession.

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

Vlastnosti parametru

Typ:WebAuthenticationType
Default value:None
Přípustné hodnoty:None, Basic, Bearer, OAuth
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

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

Parametr Body lze použít k zadání seznamu parametrů dotazu nebo zadání obsahu odpovědi.

Pokud je vstupem požadavek GET a jeho tělo je IDictionary (obvykle zatřiďovací 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 name=value formátu.

Parametr Body může také přijmout System.Net.Http.MultipartFormDataContent objekt. To usnadňuje multipart/form-data žádosti. Při MultipartFormDataContent objektu je zadána text, všechny content související hlavičky zadané ContentType, Headers nebo WebSession parametry je přepsána hlavičkami Content MultipartFormDataContent objektu. Tato funkce byla přidána v PowerShellu 6.0.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 PowerShellu Cert:.

Poznámka:

Tato funkce se v současné době podporuje jenom na platformách operačního systému Windows.

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-WebRequest nastaví typ obsahu na application/x-www-form-urlencoded. V opačném případě není ve volání zadán typ obsahu.

ContentType se přepíše, pokud je objekt MultipartFormDataContent zadán pro Body.

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 objekt PSCredential vygenerovaný rutinou Get-Credential.

Přihlašovací údaje lze použít samostatně nebo ve spojení s určitými možnostmi parametru ověřování . Pokud se používá samostatně, poskytuje přihlašovací údaje jenom vzdálenému serveru, pokud vzdálený server odešle požadavek na výzvu ověření. Při použití s možnostmi ověřování se přihlašovací údaje explicitně odesílají.

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 najdete v tématu Jak zabezpečený je SecureString?.

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

-CustomMethod

Určuje vlastní metodu použitou pro webový požadavek. To se dá použít, pokud metoda požadavku vyžadovaná koncovým bodem není k dispozici v metodě. metoda a CustomMethod nelze použít společně.

Tento příklad vytvoří TEST požadavek HTTP na rozhraní API:

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

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

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False
Aliasy:CM

Sady parametrů

CustomMethod
Position:Named
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False
CustomMethodNoProxy
Position:Named
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-DisableKeepAlive

Označuje, že rutina nastaví hodnotu KeepAlive v hlavičce HTTP tak, aby False. Ve výchozím nastavení je KeepAliveTrue. KeepAlive vytvoří trvalé připojení k serveru, aby se usnadnily následné požadavky.

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

-Form

Převede datový slovník na předání dat multipart/form-data. Formulář nelze použít s tělem . Pokud se použije ContentType , bude ignorován.

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

Pokud je hodnota System.IO.FileInfo objekt, pak se odešle obsah binárního souboru. Název souboru se odešle jako vlastnost názvu souboru . Typ MIME je nastaven jako application/octet-stream. Get-Item lze použít ke zjednodušení poskytová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 Seznamy, pole pro pole se odešle několikrát. Hodnoty seznamu jsou ve výchozím nastavení považovány za řetězce. Pokud je hodnota System.IO.FileInfo objekt, pak se odešle obsah binárního souboru. Vnořené kolekce nejsou podporované.

$Form = @{
    tags     = 'Vacation', 'Italy', '2017'
    pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy\'
}

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

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

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

-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 určení User-Agent nebo záhlaví souborů cookie.

Záhlaví související s obsahem, například Content-Type se přepíší, když je pro Body zadán objekt MultipartFormDataContent.

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

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

-MaximumRetryCount

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

Vlastnosti parametru

Typ:Int32
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

-Method

Určuje metodu použitou pro webový požadavek. Přijatelné hodnoty pro tento parametr jsou:

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace

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

Vlastnosti parametru

Typ:WebRequestMethod
Default value:None
Přípustné hodnoty:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

StandardMethod
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
StandardMethodNoProxy
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

-NoProxy

Označuje, že rutina by neměla k dosažení cíle používat proxy server. Pokud potřebujete obejít proxy server nakonfigurovaný v prostředí, použijte tento přepínač. Tato funkce byla přidána v PowerShellu 6.0.0.

Vlastnosti parametru

Typ:SwitchParameter
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

StandardMethodNoProxy
Position:Named
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False
CustomMethodNoProxy
Position:Named
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-OutFile

Určuje výstupní soubor, pro který tato rutina uloží tělo odpovědi. Zadejte cestu a název souboru. Pokud cestu vynecháte, výchozí je aktuální umístění. Název se považuje za doslovnou cestu. Názvy obsahující hranaté závorky ([]) musí být uzavřeny v jednoduchých uvozovkách (').

Ve výchozím nastavení Invoke-WebRequest 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

Označuje, že rutina kromě zápisu do souboru vrací výsledky. Tento parametr je platný pouze v případě, že se v příkazu používá také parametr OutFile.

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

-PreserveAuthorizationOnRedirect

Označuje, že cmdlet by měl zachovat hlavičku Authorization (pokud je k dispozici) při přesměrováních.

Ve výchozím nastavení cmdlet před přesměrováním odstraní hlavičku Authorization. Zadání tohoto parametru zakáže tuto logiku pro případy, kdy se hlavička musí odeslat na cílové místo přesměrování.

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

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

-Proxy

Určuje 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.

Vlastnosti parametru

Typ:Uri
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

StandardMethod
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
CustomMethod
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.

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

Vlastnosti parametru

Typ:PSCredential
Default value:Current user
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

StandardMethod
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
CustomMethod
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

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. Ve stejném příkazu nemůžete použít proxyCredential a ProxyUseDefaultCredentials parametry.

Vlastnosti parametru

Typ:SwitchParameter
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

StandardMethod
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
CustomMethod
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

-Resume

Provede pokus o obnovení stahování částečného souboru. Resume vyžaduje 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í pokračovat ve stahování souboru a připojí zbývající bajty na konec souboru.

Pokud je velikost místního souboru stejná jako velikost vzdáleného souboru, pak se neprovedou žádné akce a rutina předpokládá, že stahování je už hotové.

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 znovu stáhne. Toto chování je stejné jako použití OutFile bez Resume.

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

Pokud lokální soubor neexistuje, vytvoří se lokální soubor a stáhne se celý vzdálený soubor. Toto chování je stejné jako použití OutFile bez Resume.

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

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

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

Vlastnosti parametru

Typ:Int32
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

Určuje proměnnou, pro kterou tato rutina vytvoří relaci webového požadavku a uloží ji do hodnoty. Zadejte název proměnné bez symbolu dolaru ($).

Když zadáte proměnnou relace, Invoke-WebRequest vytvoří objekt relace webového požadavku a přiřadí jej proměnné s určeným názvem ve vaší relaci 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 webovou relaci v dalších webových požadavcích, zadejte použitou 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.

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

-SkipCertificateCheck

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

Výstraha

Použití tohoto parametru není bezpečné a nedoporučuje se. Tento přepínač je určený pouze pro známé hostitele, 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.

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

-SkipHeaderValidation

Označuje, že cmdlet přidá hlavičky do požadavku 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ěřování, aby byla hodnota předána bez kontroly. Po zadání se všechny hlavičky přidají bez ověření.

Tento přepínač zakáže ověřování hodnot předaných parametrům ContentType, Headers a UserAgent .

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

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

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

Vlastnosti parametru

Typ:SwitchParameter
Default value:False
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

-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ýčtové hodnoty na bázi příznaků. Pomocí tohoto parametru můžete zkombinovat více hodnot a nastavit více příznaků. Hodnoty lze předat SslProtocol parametr 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 využít automatické doplňování pomocí klávesy Tab pro hodnoty. Možná nebudete moct definovat více možností na všech platformách.

Poznámka:

Na jiných platformách než Windows nemusí být možné poskytovat 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 byla přidána podpora pro Tls13 PowerShell 7.1.

Vlastnosti parametru

Typ:WebSslProtocol
Default value:None
Přípustné hodnoty:Default, Tls, Tls11, Tls12
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

-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í dotazu DNS (Domain Name System) může trvat až 15 sekund. Pokud váš požadavek obsahuje název hostitele, který vyžaduje rozlišení, a nastavíte TimeoutSec na hodnotu větší než nula, ale méně než 15 sekund, může trvat 15 sekund nebo déle, než je vyvolána výjimka WebException a vyprší časový limit vašeho 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

-Token

Token OAuth nebo Bearer, který má být zahrnut do požadavku. Token je vyžadován určitými možnostmi ověřování . Nelze jej používat samostatně.

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

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

Tento parametr byl představen v PowerShellu 6.0.

Vlastnosti parametru

Typ:SecureString
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

-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. Zadejte identifikátor URI. Tento parametr podporuje pouze PROTOKOL HTTP nebo HTTPS.

Tento parametr je povinný. Identifikátor URI názvu parametru 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

Tento parametr je zastaralý. Počínaje PowerShellem 6.0.0 používají všechny webové požadavky pouze základní analýzu. Tento parametr je součástí pouze zpětné kompatibility a jakékoli jeho použití nemá žádný vliv na provoz rutiny.

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

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ěřením nebo pověřeními a nemusí být podporována na všech platformách.

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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 s mírnými variacemi 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.

Například následující příkaz používá řetězec uživatelského agenta pro Aplikaci Internet Explorer: 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. Hlavičky související s obsahem, například Content-Type, jsou také přepsány při MultipartFormDataContent objektu body.

Na rozdíl od relace vzdáleného připojení není relace webového požadavku trvalá. 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é žádosti, do hodnoty parametru SessionVariable příkazu Invoke-WebRequest zadejte název proměnné bez znaku dolaru. Invoke-WebRequest 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 nemůžete 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-WebRequest.

Výstupy

BasicHtmlWebResponseObject

Poznámky

Počínaje PowerShellem 6.0.0 Invoke-WebRequest podporuje pouze základní analýzu.

Další informace naleznete v tématu BasicHtmlWebResponseObject.

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

Hodnota této vlastnosti je určena vaší platformou:

  • Pro Windows: Načte konfiguraci proxy serveru z proměnných prostředí. Pokud tyto proměnné nejsou definovány, je vlastnost odvozena z nastavení proxy serveru.
  • Pro macOS: Čte konfiguraci proxy serveru z proměnných prostředí. Pokud tyto proměnné nejsou definovány, je vlastnost odvozena z nastavení proxy serveru.
  • Pro Linux: Načte konfiguraci proxy serveru z proměnných prostředí. Pokud tyto proměnné nejsou definovány, vlastnost inicializuje nenakonfigurovanou instanci, která obchází všechny adresy.

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

  • HTTP_PROXY: název hostitele nebo IP adresa proxy serveru používaného u požadavků HTTP.
  • HTTPS_PROXY: název hostitele nebo IP adresa proxy serveru používaného v požadavcích 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.