Invoke-WebRequest
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\]
Typ: | Object |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | X509Certificate |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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
.
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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?.
Typ: | PSCredential |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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ń.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | IDictionary |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | Int32 |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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
Typ: | WebRequestMethod |
Dopuszczalne wartości: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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 .
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Uwaga
Gdy używasz parametru PassThru , dane wyjściowe są zapisywane w potoku, ale plik jest pusty. Aby uzyskać więcej informacji, zobacz Problem z programem PowerShell #15409.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Proxy
Określa serwer proxy dla żądania, zamiast łączyć się bezpośrednio z zasobem internetowym. Wprowadź identyfikator URI serwera proxy sieci.
Typ: | Uri |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | PSCredential |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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 .
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.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | String |
Aliasy: | SV |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | Int32 |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-TransferEncoding
Określa wartość nagłówka odpowiedzi HTTP kodowania transferu. Dopuszczalne wartości tego parametru to:
Chunked
Compress
Deflate
GZip
Identity
Typ: | String |
Dopuszczalne wartości: | chunked, compress, deflate, gzip, identity |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | Uri |
Position: | 0 |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-UseDefaultCredentials
Wskazuje, że polecenie cmdlet używa poświadczeń bieżącego użytkownika do wysłania żądania internetowego.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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)
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | 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.
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 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.
Typ: | WebRequestSession |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
Dane wejściowe
Możesz przekazać treść żądania internetowego do tego polecenia cmdlet.
Dane wyjściowe
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