Sdílet prostřednictvím

Invoke-WebRequest

  • Reference
Modul:
Microsoft.PowerShell.Utility

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

Syntaxe

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é roušit 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 hashovací tabulka), tělo se přidá do identifikátoru URI jako parametry 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\]

Typ:Object
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:True
Přijmout zástupné znaky: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.

Typ:X509Certificate
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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:.

Typ:String
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:String
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:PSCredential
Position:Named
Default value:Current user
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:SwitchParameter
Position:Named
Default value:KeepAlive
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:IDictionary
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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í.

Typ:String
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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í.

Typ:Int32
Position:Named
Default value:5
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-Method

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

  • Výchozí
  • Vymazat
  • Dostat
  • Hlava
  • Sloučit
  • Volby
  • Záplata
  • Post
  • Dát
  • Stopa
Typ:WebRequestMethod
Přípustné hodnoty:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:Named
Default value:Default
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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 kanálu. Pokud chcete výsledky odeslat do souboru a do kanálu, použijte parametr Passthru.

Typ:String
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:SwitchParameter
Position:Named
Default value:False
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:Uri
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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. Ve stejném příkazu nelze použít ProxyCredential a ProxyUseDefaultCredentials parametry.

Typ:PSCredential
Position:Named
Default value:Current user
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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 nelze použít ProxyCredential a ProxyUseDefaultCredentials parametry.

Typ:SwitchParameter
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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í ho proměnné se zadaným názvem v relaci PowerShellu. Proměnnou v relaci můžete použít hned po dokončení příkazu.

Na rozdíl od vzdálené relace není relace webového požadavku trvalým připojením. Jedná se o objekt, který obsahuje informace o připojení a požadavku, včetně souborů cookie, přihlašovacích údajů, maximální hodnoty přesměrování a řetězce 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ě WebSession parametru. 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 nelze použít parametry SessionVariable a WebSes sion.

Typ:String
Aliasy:SV
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:Int32
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-TransferEncoding

Určuje hodnotu hlavičky odpovědi HTTP kódování přenosu. Přijatelné hodnoty pro tento parametr jsou:

  • Blokového
  • Komprimovat
  • Vyfouknout
  • GZip
  • Identita
Typ:String
Přípustné hodnoty:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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ý.

Typ:Uri
Position:0
Default value:None
Vyžadováno:True
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:SwitchParameter
Position:Named
Default value:False
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-UseDefaultCredentials

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

Typ:SwitchParameter
Position:Named
Default value:False
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky: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.

Typ:String
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-WebSession

Určuje relaci webové žádosti. 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 SessionVariable parametr 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.

Ve stejném příkazu nelze použít parametry SessionVariable a WebSes sion.

Typ:WebRequestSession
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

Vstupy

Object

Text webového požadavku můžete převést na Invoke-WebRequest.

Výstupy

HtmlWebResponseObject