Sdílet prostřednictvím

Invoke-WebRequest

Modul:
Microsoft.PowerShell.Utility Module

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

Syntax

Default (Výchozí) 

Invoke-WebRequest
    [-UseBasicParsing]
    [-Uri] <Uri>
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-Method <WebRequestMethod>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [<CommonParameters>]

Description

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

Tato rutina byla zavedena ve Windows PowerShellu 3.0.

Poznámka:

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

Příklady

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

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

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

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

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

Druhý příkaz filtruje objekty v AllElements vlastnost, kde název vlastnost je jako "* Value" a tagName je "INPUT". Filtrované výsledky se předávají do Select-Object a vyberou název a hodnoty vlastnosti.

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

Tento příklad ukazuje, jak používat rutinu Invoke-WebRequest se stavovou webovou službou, jako je Například Facebook.

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the Form.
$Form.fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective Form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method POST -Body $Form.Fields
$R.StatusDescription

První příkaz použije rutinu Invoke-WebRequest k odeslání žádosti o přihlášení. Příkaz určuje hodnotu "FB" pro hodnotu SessionVariable parametru a uloží výsledek do proměnné $R. Po dokončení příkazu obsahuje proměnná $RHtmlWebResponseObject a proměnná $FB obsahuje objekt WebRequestSession.

Po přihlášení rutiny Invoke-WebRequest k facebooku StatusDescription vlastnost objektu webové odpovědi v proměnné $R značí, že se uživatel úspěšně přihlásil.

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

Tento příkaz získá odkazy na webové stránce.

(Invoke-WebRequest -Uri "https://devblogs.microsoft.com/powershell/").Links.Href

Rutina Invoke-WebRequest získá obsah webové stránky. Potom Links vlastnost vrácených HtmlWebResponseObject se používá k zobrazení Href vlastnost každého propojení.

Příklad 4: 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. Následující příklad ukazuje, jak toho dosáhnout.

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

404

První příkaz volá Invoke-WebRequest s ErrorActionStop, který vynutí Invoke-WebRequest vyvolat ukončující chybu u všech neúspěšných požadavků. Ukončovací chyba je zachycena blokem catch, který načte StatusCode z objektu Exception.

Parametry

-Body

Určuje text požadavku. Text je obsah požadavku, který následuje za hlavičkami. Můžete také přesměrovat hodnotu těla do Invoke-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 tělo je IDictionary (obvykle hašovací tabulka), tělo se přidá k URI jako parametry v dotazu. U jiných požadavků GET je tělo nastaveno jako hodnota textu požadavku ve standardním formátu name=value.

Pokud je tělo formulářem nebo výstupem volání Invoke-WebRequest, PowerShell nastaví obsah požadavku na pole formuláře. Například:

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms\[0\].Name = "MyName" $r.Forms\[0\].Password = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $r

  • nebo -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[0\]

Vlastnosti parametru

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

Sady parametrů

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

-Certificate

Určuje klientský certifikát, který se používá pro zabezpečený webový požadavek. Zadejte proměnnou obsahující certifikát nebo příkaz nebo výraz, který certifikát získá.

Pokud chcete najít certifikát, použijte nebo použijte rutinu na jednotce certifikátu (). 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:.

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.

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

Vlastnosti parametru

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

Sady parametrů

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

-DisableKeepAlive

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:KeepAlive
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

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

-Headers

Určuje hlavičky webového požadavku. Zadejte tabulku hash nebo slovník.

Pokud chcete nastavit hlavičky UserAgent, použijte parametr UserAgent. Tento parametr nelze použít k zadání hlavičky userAgent nebo cookie.

Vlastnosti parametru

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

Sady parametrů

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

-InFile

Získá obsah webového požadavku ze souboru.

Zadejte cestu a název souboru. Pokud cestu vynecháte, výchozí je aktuální umístění.

Vlastnosti parametru

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

Sady parametrů

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

-MaximumRedirection

Určuje, kolikrát 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

-Method

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

  • Výchozí
  • Vymazat
  • Získat
  • Hlava
  • Sloučit
  • Možnosti
  • Aktualizace
  • Příspěvek
  • Put
  • Trasování

Vlastnosti parametru

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

Sady parametrů

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

-OutFile

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

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

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

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

-ProxyCredential

Určuje uživatelský účet, který má oprávnění používat proxy server určený parametrem Proxy. Výchozí hodnota je aktuální uživatel.

Zadejte uživatelské jméno, například User01 nebo Domain01\User01, nebo zadejte objekt PSCredential, například objekt vygenerovaný rutinou Get-Credential.

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

Vlastnosti parametru

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

Sady parametrů

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

-ProxyUseDefaultCredentials

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

Vlastnosti parametru

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

Sady parametrů

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

-SessionVariable

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.

Nelze použít parametry SessionVariable a WebSession ve stejném příkazu.

Vlastnosti parametru

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

Sady parametrů

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

-TimeoutSec

Určuje, jak dlouho může požadavek čekat, než vyprší časový limit. Zadejte hodnotu v sekundách. Výchozí hodnota 0 určuje neomezený časový limit.

Vrácení nebo vypršení časového limitu dotazu DNS (Domain Name System) může trvat až 15 sekund. Pokud váš požadavek obsahuje název hostitele, který vyžaduje překlad, a nastavíte TimeoutSec na hodnotu větší než nula, ale méně než 15 sekund, může trvat 15 sekund nebo déle, než se vyvolá WebException a vyprší časový limit požadavku.

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

-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 hodnoty HTTP, HTTPS, FTP a FILE.

Tento parametr je povinný.

Vlastnosti parametru

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

Sady parametrů

(All)
Position:0
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-UseBasicParsing

Označuje, že rutina používá objekt odpovědi pro obsah HTML bez analýzy modelu DOM (Document Object Model). Tento parametr se vyžaduje, pokud není v počítačích nainstalovaný Internet Explorer, například v instalaci jádra serveru operačního systému Windows Server.

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

-UseDefaultCredentials

Označuje, že cmdet používá přihlašovací údaje aktuálního uživatele k odeslání webové žádosti.

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

-UserAgent

Určuje řetězec uživatelského agenta pro webový požadavek. Výchozí uživatelský agent je podobný Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0 s mírnými variacemi pro každý operační systém a platformu.

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 PSUserAgent třídy, jako je Chrome, FireFox, InternetExplorer, Opera a Safari. Následující příkaz například používá řetězec uživatelského agenta pro Internet Explorer.

Vlastnosti parametru

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

Sady parametrů

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

-WebSession

Určuje relaci webového požadavku. Zadejte název proměnné, včetně znaku dolaru ($).

Pokud chcete přepsat hodnotu v relaci webového požadavku, použijte parametr rutiny, například UserAgent nebo Credential. Hodnoty parametrů mají přednost před hodnotami v relaci webového požadavku.

Na rozdíl od vzdálené relace není relace webového požadavku trvalým připojením. Jedná se o objekt, který obsahuje informace o připojení a požadavku, včetně souborů cookie, přihlašovacích údajů, maximální hodnoty přesměrování a řetězce uživatelského agenta. Můžete ho použít ke sdílení stavu a dat mezi webovými požadavky.

Pokud chcete vytvořit relaci webové žádosti, zadejte název proměnné (bez znaku dolaru) do hodnoty parametru SessionVariable příkazu Invoke-WebRequest. Invoke-WebRequest vytvoří relaci a uloží ji do proměnné. V dalších příkazech použijte proměnnou jako hodnotu parametru WebSession.

Nelze použít parametry SessionVariable a WebSession ve stejném příkazu.

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

HtmlWebResponseObject