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í může být kód skriptu na webové stránce spuštěn při analýze stránky pro naplnění ParsedHtml vlastnosti. -UseBasicParsing K potlačení použijte přepínač.

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. Vzhledem k tomu, že contoso.com weby 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 -UseBasicParsing -URI https://www.bing.com?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

Data vrácená Invoke-WebRequest pomocí jsou uložena v $Response proměnné. Vlastnost InputFields odpovědi obsahuje pole formuláře. Where-Object slouží k filtrování polí formuláře na pole, ve kterých se vlastnost name podobá hodnotě *. Filtrované výsledky se předávají tak, aby Select-Object vybrali vlastnosti názvu a hodnoty .

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

Tento příklad ukazuje, jak použít 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 Parametr SessionVariable a uloží výsledek do $R proměnné. Po dokončení $R příkazu obsahuje proměnná HtmlWebResponseObject a $FB proměnná obsahuje WebRequestSession objekt.

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

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. Poté Odkazy vlastnost vrácené HtmlWebResponseObject se používá k zobrazení Href vlastnost každého odkazu.

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

Když Invoke-WebRequest se zobrazí zpráva HTTP bez úspěchu (404, 500 atd.), nevrá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 try/catch bloku.

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 .

Příklad 8: Stažení více souborů najednou

Rutina Invoke-WebRequest může stáhnout jenom jeden soubor najednou. Následující příklad používá Start-ThreadJob k vytvoření více úloh vlákna ke stažení více souborů najednou.

$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
        OutFile = 'PowerShell-7.2.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
        OutFile = 'PowerShell-7.2.5-win-x64.zip'
    }
)

$jobs = @()

foreach ($file in $files) {
    $jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
        $params = $using:file
        Invoke-WebRequest @params
    }
}

Write-Host "Downloads started..."
Wait-Job -Job $jobs

foreach ($job in $jobs) {
    Receive-Job -Job $job
}

Poznámka:

Pokud chcete použít rutinu Start-ThreadJob, musíte z Galerie prostředí PowerShell nainstalovat modul ThreadJob.

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 k určení obsahu odpovědi.

Když 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 typů požadavků (například POST) se text nastaví jako hodnota textu požadavku ve standardním name=value formátu.

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

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms\[0\].Name = "MyName" $r.Forms\[0\].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 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.

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ů. Certifikáty lze mapovat pouze na místní uživatelské účty, nikoli účty domény.

Pokud chcete zobrazit kryptografický otisk certifikátu, použijte Get-Item příkaz nebo Get-ChildItem vyhledejte certifikát v Cert:\CurrentUser\Mysouboru .

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

Typ:	PSCredential
Position:	Named
Default value:	None
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 na False. KeepAlive má ve výchozím nastavení hodnotu True. KeepAlive vytvoří trvalé připojení k serveru, aby se usnadnily následné požadavky.

Typ:	SwitchParameter
Position:	Named
Default value:	None
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.

Chcete-li 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:	None
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. Tento parametr přijímá tyto hodnoty:

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Typ:	WebRequestMethod
Přípustné hodnoty:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	None
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 .

Poznámka:

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

Typ:	SwitchParameter
Position:	Named
Default value:	None
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 . Ve výchozím nastavení je to aktuální uživatel.

Zadejte uživatelské jméno, například User01 nebo nebo zadejte Domain01\User01, 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 nemůžete použít parametry ProxyCredential a ProxyUseDefaultCredentials .

Typ:	PSCredential
Position:	Named
Default value:	None
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 .

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 následných webových požadavcích, zadejte 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 .

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 hodnotu TimeoutSec na hodnotu větší než nula, ale méně než 15 sekund, může trvat 15 sekund nebo déle, než se vyvolá výjimka 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. Tento parametr přijímá tyto hodnoty:

Chunked
Compress
Deflate
GZip
Identity

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

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:	None
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-UseDefaultCredentials

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

Typ:	SwitchParameter
Position:	Named
Default value:	None
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 mírným změnám 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. 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)

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.

Pokud chcete vytvořit relaci webového požadavku, zadejte název proměnné bez znaku dolaru do hodnoty Invoke-WebRequest příkazu. 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 .

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

Do této rutiny můžete převést text webového požadavku.

Výstupy

HtmlWebResponseObject

Tato rutina vrátí objekt odpovědi představující výsledek webového požadavku.

Poznámky

Windows PowerShell obsahuje následující aliasy pro Invoke-WebRequest:

iwr

Sdílet prostřednictvím

Invoke-WebRequest

Syntaxe

Description

Příklady

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

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

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

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

Příklad 8: Stažení více souborů najednou

Parametry

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Vstupy

Výstupy

Poznámky

Další materiály

Sdílet prostřednictvím

Invoke-WebRequest

Syntaxe

Description

Příklady

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

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

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

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

Příklad 8: Stažení více souborů najednou

Parametry

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Vstupy

Výstupy

Poznámky

Související odkazy

Další materiály