Invoke-WebRequest

Odwołanie

Moduł:: Microsoft.PowerShell.Utility

Pobiera zawartość ze strony internetowej w Internecie.

Składnia

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

Opis

Polecenie Invoke-WebRequest cmdlet wysyła żądania HTTP, HTTPS, FTP i FILE do strony internetowej lub usługi internetowej. Analizuje odpowiedź i zwraca kolekcje formularzy, linków, obrazów i innych znaczących elementów HTML.

To polecenie cmdlet zostało wprowadzone w programie Windows PowerShell 3.0.

Uwaga

Domyślnie kod skryptu na stronie internetowej może być uruchamiany, gdy strona jest analizowana w celu wypełnienia ParsedHtml właściwości. Użyj przełącznika -UseBasicParsing , aby pominąć tę opcję.

Ważne

Przykłady w tym artykule odwołują się do hostów w domenie contoso.com . Jest to fikcyjna domena używana przez firmę Microsoft na potrzeby przykładów. Przykłady zostały zaprojektowane tak, aby pokazać, jak używać poleceń cmdlet. Jednak ponieważ contoso.com witryny nie istnieją, przykłady nie działają. Dostosuj przykłady do hostów w danym środowisku.

Przykłady

Przykład 1. Wysyłanie żądania internetowego

W tym przykładzie użyto Invoke-WebRequest polecenia cmdlet do wysłania żądania internetowego do witryny 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

Dane zwracane przez Invoke-WebRequest program są przechowywane w zmiennej $Response . Właściwość InputFields odpowiedzi zawiera pola formularza. Where-Object Służy do filtrowania pól formularza do tych, w których właściwość name jest podobna do "* Wartość". Przefiltrowane wyniki są przesyłane potokiem, aby Select-Object wybrać właściwości nazwy i wartości .

Przykład 2. Używanie stanowej usługi internetowej

W tym przykładzie pokazano, jak używać Invoke-WebRequest polecenia cmdlet z stanową usługą internetową, taką jak 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

Pierwsze polecenie używa Invoke-WebRequest polecenia cmdlet do wysyłania żądania logowania. Polecenie określa wartość "FB" dla wartości parametru SessionVariable i zapisuje wynik w zmiennej $R . Po zakończeniu polecenia zmienna zawiera obiekt HtmlWebResponseObject, a zmienna $FB zawiera obiekt WebRequestSession.$R

Po zalogowaniu Invoke-WebRequest się polecenia cmdlet do serwisu facebook właściwość StatusDescription obiektu odpowiedzi internetowej w zmiennej $R wskazuje, że użytkownik jest pomyślnie zalogowany.

Przykład 3. Pobieranie linków ze strony internetowej

To polecenie pobiera linki na stronie internetowej.

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

Polecenie Invoke-WebRequest cmdlet pobiera zawartość strony internetowej. Następnie właściwość Links zwróconego obiektu HtmlWebResponseObject jest używana do wyświetlania właściwości Href każdego łącza.

Przykład 4. Przechwytywanie komunikatów o niepowodzeniu powodzenia z polecenia Invoke-WebRequest

W Invoke-WebRequest przypadku napotkania komunikatu HTTP o niepowodowaniu powodzenia (404, 500 itp.), zwraca on brak danych wyjściowych i zgłasza błąd zakończenia. Aby przechwycić błąd i wyświetlić kod StatusCode , możesz ująć wykonywanie w 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

Błąd zakończenia jest przechwycony przez catch blok, który pobiera kod stanu z obiektu Exception .

Przykład 8. Pobieranie wielu plików w tym samym czasie

Polecenie Invoke-WebRequest cmdlet może pobrać tylko jeden plik naraz. W poniższym przykładzie użyto Start-ThreadJob metody do utworzenia wielu zadań wątku w celu pobrania wielu plików w tym samym czasie.

$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
}

Uwaga

Aby użyć Start-ThreadJob polecenia cmdlet, należy zainstalować moduł ThreadJob z Galeria programu PowerShell.

Parametry

-Body

Określa treść żądania. Treść jest zawartością żądania, która jest zgodna z nagłówkami. Możesz również przekazać wartość treści do Invoke-WebRequest.

Parametr Treść może służyć do określenia listy parametrów zapytania lub określenia zawartości odpowiedzi.

Gdy dane wejściowe są żądaniem GET, a treść jest IDictionary (zazwyczaj tabelą skrótów), treść jest dodawana do identyfikatora URI jako parametrów zapytania. W przypadku innych typów żądań (takich jak POST) treść jest ustawiana jako wartość treści żądania w formacie standardowym name=value .

Gdy treść jest formularzem lub jest wynikiem Invoke-WebRequest wywołania, program PowerShell ustawia zawartość żądania na pola formularza. Na przykład:

$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

Lub-

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

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Certificate

Określa certyfikat klienta używany na potrzeby bezpiecznego żądania internetowego. Wprowadź zmienną zawierającą certyfikat lub polecenie lub wyrażenie, które pobiera certyfikat.

Aby znaleźć certyfikat, użyj Get-PfxCertificate polecenia cmdlet lub użyj go Get-ChildItem na dysku Certyfikat (Cert:). Jeśli certyfikat jest nieprawidłowy lub nie ma wystarczającego urzędu, polecenie kończy się niepowodzeniem.

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

-CertificateThumbprint

Określa cyfrowy certyfikat klucza publicznego (X509) konta użytkownika z uprawnieniami do wysyłania żądania. Wprowadź odcisk palca certyfikatu.

Certyfikaty są używane w uwierzytelnianiu opartym na certyfikatach klienta. Certyfikaty można mapować tylko na konta użytkowników lokalnych, a nie na konta domeny.

Aby wyświetlić odcisk palca certyfikatu, użyj Get-Item polecenia lub Get-ChildItem , aby znaleźć certyfikat w pliku Cert:\CurrentUser\My.

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

-ContentType

Określa typ zawartości żądania internetowego.

Jeśli ten parametr zostanie pominięty, a metoda żądania to POST, Invoke-WebRequest ustawia typ zawartości na application/x-www-form-urlencoded. W przeciwnym razie typ zawartości nie jest określony w wywołaniu.

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

-Credential

Określa konto użytkownika, które ma uprawnienia do wysyłania żądania. Wartość domyślna to użytkownik bieżący.

Wpisz nazwę użytkownika, taką jak User01 lub Domain01\User01, lub wprowadź obiekt PSCredential wygenerowany przez Get-Credential polecenie cmdlet.

Poświadczenia są przechowywane w obiekcie PSCredential , a hasło jest przechowywane jako secureString.

Uwaga

Aby uzyskać więcej informacji na temat ochrony danych SecureString , zobacz Jak bezpieczny jest protokół SecureString?.

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

-DisableKeepAlive

Wskazuje, że polecenie cmdlet ustawia wartość KeepAlive w nagłówku HTTP na wartość False. Domyślnie wartość KeepAlive ma wartość True. KeepAlive ustanawia trwałe połączenie z serwerem w celu ułatwienia kolejnych żądań.

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

-Headers

Określa nagłówki żądania internetowego. Wprowadź tabelę skrótu lub słownik.

Aby ustawić nagłówki UserAgent , użyj parametru UserAgent . Nie można użyć tego parametru do określenia nagłówków UserAgent lub cookie.

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

-InFile

Pobiera zawartość żądania internetowego z pliku.

Wprowadź ścieżkę i nazwę pliku. Jeśli pominięto ścieżkę, wartość domyślna to bieżąca lokalizacja.

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

-MaximumRedirection

Określa, ile razy program PowerShell przekierowuje połączenie z alternatywnym identyfikatorem URI (Uniform Resource Identifier) przed niepowodzeniem połączenia. Domyślna wartość wynosi 5. Wartość 0 (zero) uniemożliwia wszystkie przekierowania.

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

-Method

Określa metodę używaną dla żądania internetowego. Dopuszczalne wartości tego parametru to:

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

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

-OutFile

Określa plik wyjściowy, dla którego to polecenie cmdlet zapisuje treść odpowiedzi. Wprowadź ścieżkę i nazwę pliku. Jeśli pominięto ścieżkę, wartość domyślna to bieżąca lokalizacja.

Domyślnie Invoke-WebRequest zwraca wyniki do potoku. Aby wysłać wyniki do pliku i do potoku, użyj parametru Passthru .

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

-PassThru

Wskazuje, że polecenie cmdlet zwraca wyniki oprócz zapisywania ich w pliku. Ten parametr jest prawidłowy tylko wtedy, gdy parametr OutFile jest również używany w poleceniu.

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

-Proxy

Określa serwer proxy dla żądania, zamiast łączyć się bezpośrednio z zasobem internetowym. Wprowadź identyfikator URI serwera proxy sieci.

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

-ProxyCredential

Określa konto użytkownika, które ma uprawnienia do korzystania z serwera proxy określonego przez parametr proxy . Wartość domyślna to użytkownik bieżący.

Wpisz nazwę użytkownika, taką jak User01 lub Domain01\User01, lub wprowadź obiekt PSCredential , taki jak jeden wygenerowany przez Get-Credential polecenie cmdlet.

Ten parametr jest prawidłowy tylko wtedy, gdy parametr serwera proxy jest również używany w poleceniu . Nie można użyć parametrów ProxyCredential i ProxyUseDefaultCredentials w tym samym poleceniu.

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

-ProxyUseDefaultCredentials

Wskazuje, że polecenie cmdlet używa poświadczeń bieżącego użytkownika w celu uzyskania dostępu do serwera proxy określonego przez parametr proxy .

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

-SessionVariable

Określa zmienną, dla której to polecenie cmdlet tworzy sesję żądania internetowego i zapisuje je w wartości. Wprowadź nazwę zmiennej bez symbolu znaku dolara ($).

Po określeniu zmiennej Invoke-WebRequest sesji tworzy obiekt sesji żądania sieci Web i przypisuje go do zmiennej o określonej nazwie w sesji programu PowerShell. Możesz użyć zmiennej w sesji, gdy tylko polecenie zostanie ukończone.

W przeciwieństwie do sesji zdalnej sesja żądania sieci Web nie jest trwałym połączeniem. Jest to obiekt, który zawiera informacje o połączeniu i żądaniu, w tym pliki cookie, poświadczenia, maksymalną wartość przekierowania i parametry agenta użytkownika. Służy do udostępniania stanu i danych między żądaniami internetowymi.

Aby użyć sesji żądania sieci Web w kolejnych żądaniach sieci Web, określ zmienną sesji w wartości parametru WebSession . Program PowerShell używa danych w obiekcie sesji żądania internetowego podczas nawiązywania nowego połączenia. Aby zastąpić wartość w sesji żądania internetowego, użyj parametru polecenia cmdlet, takiego jak UserAgent lub Credential. Wartości parametrów mają pierwszeństwo przed wartościami w sesji żądania internetowego.

Nie można użyć parametrów SessionVariable i WebSession w tym samym poleceniu.

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

-TimeoutSec

Określa, jak długo żądanie może być oczekujące przed upływem limitu czasu. Wprowadź wartość w sekundach. Wartość domyślna 0 określa limit czasu nieokreślony.

Zapytanie systemu nazw domen (DNS) może potrwać do 15 sekund, aby zwrócić lub upłynął limit czasu. Jeśli żądanie zawiera nazwę hosta, która wymaga rozwiązania, i ustawisz wartość TimeoutSec na wartość większą niż zero, ale mniej niż 15 sekund, może upłynąć 15 sekund lub więcej, zanim zostanie zgłoszony wyjątek WebException i przekroczono limit czasu żądania.

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

-TransferEncoding

Określa wartość nagłówka odpowiedzi HTTP kodowania transferu. Dopuszczalne wartości tego parametru to:

Chunked
Compress
Deflate
GZip
Identity

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

Określa identyfikator URI (Uniform Resource Identifier) zasobu internetowego, do którego jest wysyłane żądanie internetowe. Wprowadź identyfikator URI. Ten parametr obsługuje wartości HTTP, HTTPS, FTP i FILE.

Ten parametr jest wymagany. Identyfikator URI nazwy parametru jest opcjonalny.

Type:	Uri
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UseBasicParsing

Wskazuje, że polecenie cmdlet używa obiektu odpowiedzi dla zawartości HTML bez analizowania modelu obiektów dokumentów (DOM). Ten parametr jest wymagany, gdy program Internet Explorer nie jest zainstalowany na komputerach, na przykład w instalacji Server Core systemu operacyjnego Windows Server.

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

-UseDefaultCredentials

Wskazuje, że polecenie cmdlet używa poświadczeń bieżącego użytkownika do wysłania żądania internetowego.

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

-UserAgent

Określa ciąg agenta użytkownika dla żądania internetowego. Domyślny agent użytkownika jest podobny do Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0 niewielkich zmian dla każdego systemu operacyjnego i platformy.

Aby przetestować witrynę internetową przy użyciu standardowego ciągu agenta użytkownika używanego przez większość przeglądarek internetowych, użyj właściwości klasy PSUserAgent , takich jak Chrome, FireFox, InternetExplorer, Opera i Safari. Na przykład następujące polecenie używa ciągu agenta użytkownika dla programu Internet Explorer: Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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

-WebSession

Określa sesję żądania internetowego. Wprowadź nazwę zmiennej, w tym znak dolara ($).

Aby zastąpić wartość w sesji żądania internetowego, użyj parametru polecenia cmdlet, takiego jak UserAgent lub Credential. Wartości parametrów mają pierwszeństwo przed wartościami w sesji żądania internetowego.

Aby utworzyć sesję żądania internetowego, wprowadź nazwę zmiennej bez znaku dolara w wartości parametru Invoke-WebRequest SessionVariable polecenia. Invoke-WebRequest tworzy sesję i zapisuje ją w zmiennej. W kolejnych poleceniach użyj zmiennej jako wartości parametru WebSession .

Nie można użyć parametrów SessionVariable i WebSession w tym samym poleceniu.

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

Dane wejściowe

Object

Możesz przekazać treść żądania internetowego do tego polecenia cmdlet.

Dane wyjściowe

HtmlWebResponseObject

To polecenie cmdlet zwraca obiekt odpowiedzi reprezentujący wynik żądania internetowego.

Uwagi

Program Windows PowerShell zawiera następujące aliasy dla programu Invoke-WebRequest:

iwr

Udostępnij przez

Invoke-WebRequest

Składnia

Opis

Przykłady

Przykład 1. Wysyłanie żądania internetowego

Przykład 2. Używanie stanowej usługi internetowej

Przykład 3. Pobieranie linków ze strony internetowej

Przykład 4. Przechwytywanie komunikatów o niepowodzeniu powodzenia z polecenia Invoke-WebRequest

Przykład 8. Pobieranie wielu plików w tym samym czasie

Parametry

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Dane wejściowe

Dane wyjściowe

Uwagi

Opinia

Dodatkowe zasoby

Udostępnij przez

Invoke-WebRequest

Składnia

Opis

Przykłady

Przykład 1. Wysyłanie żądania internetowego

Przykład 2. Używanie stanowej usługi internetowej

Przykład 3. Pobieranie linków ze strony internetowej

Przykład 4. Przechwytywanie komunikatów o niepowodzeniu powodzenia z polecenia Invoke-WebRequest

Przykład 8. Pobieranie wielu plików w tym samym czasie

Parametry

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Dane wejściowe

Dane wyjściowe

Uwagi

Linki powiązane

Opinia

Dodatkowe zasoby