Udostępnij za pośrednictwem

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>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]
Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]
Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]
Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

Opis

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

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

Począwszy od programu PowerShell 7.0, Invoke-WebRequest obsługuje konfigurację serwera proxy zdefiniowaną przez zmienne środowiskowe. Zobacz sekcję Uwagi w tym artykule.

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 przykład. 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 środowisku.

Przykłady

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

W tym przykładzie Invoke-WebRequest użyto polecenia cmdlet do wysłania żądania internetowego do witryny Bing.com.

$Response = Invoke-WebRequest -URI https://www.bing.com/search?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

Pierwsze polecenie wystawia żądanie i zapisuje odpowiedź w zmiennej $Response .

Drugie polecenie pobiera dowolne pole wejściowe , w którym właściwość Name jest podobna do "* Value". Przefiltrowane wyniki są przesyłane potokiem, aby wybrać Select-Object właściwości Nazwa i Wartość .

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

$Body = @{
    User = 'jdoe'
    password = 'P@S$w0rd!'
}
$LoginResponse = Invoke-WebRequest 'https://www.contoso.com/login/' -SessionVariable 'Session' -Body $Body -Method 'POST'

$Session

$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

$ProfileResponse

Pierwsze wywołanie do Invoke-WebRequest wysyłania żądania logowania. Polecenie określa wartość "Session" dla wartości parametru -SessionVariable i zapisuje wynik w zmiennej $LoginResponse . Po zakończeniu $LoginResponse polecenia zmienna zawiera zmienną BasicHtmlWebResponseObject , a zmienna $Session zawiera WebRequestSession obiekt . Spowoduje to zalogowanie użytkownika do witryny.

Wywołanie do $Session samego siebie pokazuje WebRequestSession obiekt w zmiennej.

Drugie wywołanie pobierania Invoke-WebRequest profilu użytkownika, które wymaga zalogowania użytkownika do witryny. Dane sesji przechowywane w zmiennej $Session służą do udostępniania plików cookie sesji do witryny utworzonej podczas logowania. Wynik jest zapisywany w zmiennej $ProfileResponse .

Wywołanie do $ProfileResponse samego siebie pokazuje BasicHtmlWebResponseObject wartość w zmiennej .

Ten przykład pobiera linki na stronie internetowej. Invoke-WebRequest Używa polecenia cmdlet do pobierania zawartości strony internetowej. Następnie używa właściwości Links zwracanej BasicHtmlWebResponseObjectInvoke-WebRequest wartości i właściwości Href każdego łącza.

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

Przykład 4. Zapisuje zawartość odpowiedzi do pliku przy użyciu kodowania zdefiniowanego na żądanej stronie.

W tym przykładzie Invoke-WebRequest użyto polecenia cmdlet do pobrania zawartości strony internetowej strony dokumentacji programu PowerShell.

$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
    $Stream.Write($Response.Content)
}
finally {
    $Stream.Dispose()
}

Pierwsze polecenie pobiera stronę i zapisuje obiekt odpowiedzi w zmiennej $Response .

Drugie polecenie tworzy element , StreamWriter który służy do zapisywania zawartości odpowiedzi w pliku. Właściwość Kodowanie obiektu odpowiedzi służy do ustawiania kodowania dla pliku.

Ostatnie kilka poleceń zapisuje właściwość Content w pliku, a następnie usuwa StreamWriterelement .

Należy pamiętać, że właściwość Kodowanie ma wartość null, jeśli żądanie internetowe nie zwraca zawartości tekstowej.

Przykład 5. Przesyłanie pliku wieloczęściowego/formularza-danych

W tym przykładzie użyto Invoke-WebRequest polecenia cmdlet przekazywania pliku jako multipart/form-data przesłania. Plik c:\document.txt jest przesyłany jako pole document formularza z wartością Content-Typetext/plain.

$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'

$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)

$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)

$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'

Przykład 6. Uproszczone przesyłanie danych wieloczęściowych/formularzy

Niektóre interfejsy API wymagają multipart/form-data przesyłania plików i mieszanej zawartości. W tym przykładzie pokazano aktualizowanie profilu użytkownika.

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-WebRequest -Uri $Uri -Method Post -Form $Form

Formularz profilu wymaga następujących pól: firstName, , lastNameemail, avatar, birthdayi hobbies. Interfejs API oczekuje, że obraz zdjęcia profilu użytkownika zostanie dostarczony w avatar polu. Interfejs API akceptuje również wiele hobbies wpisów do przesłania w tym samym formularzu.

Podczas tworzenia tabeli $Form HashTable nazwy kluczy są używane jako nazwy pól formularza. Domyślnie wartości tabeli HashTable są konwertowane na ciągi. Jeśli wartość System.IO.FileInfo jest obecna, zawartość pliku zostanie przesłana. Jeśli kolekcja, taka jak tablice lub listy, jest wyświetlana, pole formularza jest przesyłane wiele razy.

Za pomocą Get-Itemavatar klucza FileInfo obiekt jest ustawiany jako wartość. Wynik polega na przesłaniu danych obrazu.jdoe.png

Po podaniu listy do hobbies klucza hobbies pole jest obecne w przesłanych raz dla każdego elementu listy.

Przykład 7. Przechwytywanie komunikatów o niepowodzeń powodzenia z Invoke-WebRequest

W Invoke-WebRequest przypadku napotkania komunikatu HTTP o niepowodzeniu 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 stanu , 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 przechwytywane przez catch blok, który pobiera Kod stanu z obiektu Exception .

Parametry

-AllowUnencryptedAuthentication

Umożliwia wysyłanie poświadczeń i wpisów tajnych za pośrednictwem nieszyfrowanych połączeń. Domyślnie podanie opcji Poświadczenie lub uwierzytelnianie z identyfikatorem URI , które nie zaczyna się https:// od wyniku błędu, a żądanie zostało przerwane, aby zapobiec niezamierzonej komunikacji wpisów tajnych w postaci zwykłego tekstu za pośrednictwem niezaszyfrowanych połączeń. Aby zastąpić to zachowanie na własnym ryzyku, podaj parametr AllowUnencryptedAuthentication .

Ostrzeżenie

Użycie tego parametru nie jest bezpieczne i nie jest zalecane. Jest on udostępniany tylko w celu zapewnienia zgodności ze starszymi systemami, które nie mogą zapewnić zaszyfrowanych połączeń. Użyj na własne ryzyko.

Ta funkcja została dodana w programie PowerShell 6.0.0.

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

-Authentication

Określa jawny typ uwierzytelniania do użycia dla żądania. Wartość domyślna to Brak. Parametr uwierzytelniania nie może być używany z parametrem UseDefaultCredentials .

Dostępne opcje uwierzytelniania:

  • None: Jest to opcja domyślna, gdy nie podano uwierzytelniania . Nie zostanie użyte żadne jawne uwierzytelnianie.
  • Basic: wymaga poświadczeń. Poświadczenia będą używane do wysyłania nagłówka uwierzytelniania Authorization: Basic podstawowego RFC 7617 w formacie base64(user:password).
  • Bearer: wymaga parametru Token . Wysyła nagłówek RFC 6750 Authorization: Bearer z podanym tokenem.
  • OAuth: wymaga parametru Token . Wysyła nagłówek RFC 6750 Authorization: Bearer z podanym tokenem.

Podanie uwierzytelniania zastępuje wszystkie Authorizationnagłówki dostarczone do nagłówków lub zawarte w usłudze WebSession.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Type:WebAuthenticationType
Accepted values:None, Basic, Bearer, OAuth
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Body

Określa treść żądania. Treść to zawartość żą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 to żądanie GET, a treść to IDictionary (zazwyczaj tabela 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 .

Parametr Body może również akceptować System.Net.Http.MultipartFormDataContent obiekt. multipart/form-data Ułatwia to żądania. Gdy obiekt MultipartFormDataContent jest dostarczany dla treści, wszystkie nagłówki powiązane z zawartością dostarczane do parametrów ContentType, Headers lub WebSession są zastępowane przez nagłówki Zawartości obiektu MultipartFormDataContent . Ta funkcja została dodana w programie PowerShell 6.0.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 do bezpiecznego żądania internetowego. Wprowadź zmienną zawierającą certyfikat lub polecenie lub wyrażenie, które pobiera certyfikat.

Aby znaleźć certyfikat, użyj Get-PfxCertificate lub użyj Get-ChildItem polecenia cmdlet 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 certyfikatu.

Certyfikaty są używane w uwierzytelnianiu opartym na certyfikatach klienta. Mogą być mapowane tylko na konta użytkowników lokalnych; nie działają z kontami domeny.

Aby uzyskać odcisk palca certyfikatu, użyj Get-Item polecenia lub Get-ChildItem na dysku programu PowerShell Cert: .

Uwaga

Ta funkcja jest obecnie obsługiwana tylko na platformach systemu operacyjnego Windows.

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.

Właściwość ContentType jest zastępowana, gdy obiekt MultipartFormDataContent jest dostarczany dla elementu Body.

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 mogą być używane samodzielnie lub w połączeniu z niektórymi opcjami parametrów uwierzytelniania . W przypadku użycia samodzielnie dostarcza poświadczenia tylko do serwera zdalnego, jeśli serwer zdalny wysyła żądanie żądania uwierzytelniania. W przypadku użycia z opcjami uwierzytelniania poświadczenia są jawnie wysyłane.

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:Current user
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CustomMethod

Określa metodę niestandardową używaną dla żądania internetowego. Może to być używane, jeśli metoda żądania wymagana przez punkt końcowy nie jest dostępna w metodzie. Nie można używać razem metody i metody CustomMethod.

Ten przykład wysyła TEST żądanie HTTP do interfejsu API:

Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Ta funkcja została dodana w programie PowerShell 6.0.0.

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

-DisableKeepAlive

Wskazuje, że polecenie cmdlet ustawia wartość KeepAlive w nagłówku HTTP na False. Domyślnie 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

-Form

Konwertuje słownik na multipart/form-data przesyłanie. Formularz może nie być używany z treścią. Jeśli jest używany typ zawartości , jest on ignorowany.

Klucze słownika są używane jako nazwy pól formularza. Domyślnie wartości formularzy są konwertowane na wartości ciągów.

Jeśli wartość jest obiektem System.IO.FileInfo , zawartość pliku binarnego zostanie przesłana. Nazwa pliku jest przesyłana jako właściwość nazwy pliku . Typ MIME jest ustawiony jako application/octet-stream. Get-Item można użyć do uproszczenia dostarczania obiektu System.IO.FileInfo .

$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

Jeśli wartość jest typem kolekcji, takim jak Tablice lub Listy, pole for jest przesyłane wiele razy. Wartości listy są domyślnie traktowane jako ciągi. Jeśli wartość jest obiektem System.IO.FileInfo , zawartość pliku binarnego zostanie przesłana. Kolekcje zagnieżdżone nie są obsługiwane.

$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

W powyższym przykładzie tags pole jest dostarczane trzy razy w formularzu, raz dla każdego z Vacation, Italyi 2017. pictures Pole jest również przesyłane raz dla każdego pliku w folderze2017-Italy. Zawartość binarna plików w tym folderze są przesyłane jako wartości.

Ta funkcja została dodana w programie PowerShell 6.1.0.

Type:IDictionary
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 User-Agent lub cookie.

Nagłówki powiązane z zawartością, takie jak Content-Type jest zastępowane, gdy obiekt MultipartFormDataContent jest dostarczany dla treści.

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. Wartość domyślna to 5. Wartość 0 (zero) uniemożliwia wszystkie przekierowania.

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

-MaximumRetryCount

Określa, ile razy program PowerShell ponawia próbę połączenia, gdy zostanie odebrany kod błędu z zakresu od 400 do 599 włącznie lub 304. Zobacz również parametr RetryIntervalSec, aby określić liczbę ponownych prób.

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 dla tego parametru to:

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace

Parametr CustomMethod można użyć dla metod żądań, których nie wymieniono powyżej.

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

-NoProxy

Wskazuje, że polecenie cmdlet nie powinno używać serwera proxy do osiągnięcia miejsca docelowego. Jeśli musisz pominąć serwer proxy skonfigurowany w środowisku, użyj tego przełącznika. Ta funkcja została dodana w programie PowerShell 6.0.0.

Type:SwitchParameter
Position:Named
Default value:None
Required:True
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. Nazwa jest traktowana jako ścieżka literału. Nazwy zawierające nawiasy kwadratowe ([]) muszą być ujęte w cudzysłowy (').

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

-PreserveAuthorizationOnRedirect

Wskazuje, że polecenie cmdlet powinno zachować Authorization nagłówek, gdy jest obecny, między przekierowaniami.

Domyślnie polecenie cmdlet usuwa Authorization nagłówek przed przekierowaniem. Określenie tego parametru powoduje wyłączenie tej logiki w przypadkach, w których nagłówek musi być wysyłany do lokalizacji przekierowania.

Ta funkcja została dodana w programie PowerShell 6.0.0.

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 używania serwera proxy określonego przez parametr serwera proxy . Wartość domyślna to użytkownik bieżący.

Wpisz nazwę użytkownika, taką jak User01 lub Domain01\User01, User@Domain.Comlub wprowadź PSCredential obiekt, taki jak 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:Current user
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyUseDefaultCredentials

Wskazuje, że polecenie cmdlet używa poświadczeń bieżącego użytkownika do uzyskiwania 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.

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

-Resume

Wykonuje najlepszą próbę wznowienia pobierania pliku częściowego. Wznawianie wymaga pliku OutFile.

Wznawianie działa tylko na rozmiarze pliku lokalnego i pliku zdalnego i nie wykonuje innej weryfikacji, że plik lokalny i plik zdalny są takie same.

Jeśli rozmiar pliku lokalnego jest mniejszy niż rozmiar pliku zdalnego, polecenie cmdlet próbuje wznowić pobieranie pliku i dołączyć pozostałe bajty na końcu pliku.

Jeśli rozmiar pliku lokalnego jest taki sam jak rozmiar pliku zdalnego, nie zostanie podjęta żadna akcja, a polecenie cmdlet zakłada, że pobieranie zostało już ukończone.

Jeśli rozmiar pliku lokalnego jest większy niż rozmiar pliku zdalnego, plik lokalny zostanie zastąpiony i cały plik zdalny zostanie ponownie pobrany. To zachowanie jest takie samo jak w przypadku korzystania z pliku OutFile bez wznawiania.

Jeśli serwer zdalny nie obsługuje wznawiania pobierania, plik lokalny zostanie zastąpiony i cały plik zdalny zostanie ponownie pobrany. To zachowanie jest takie samo jak w przypadku korzystania z pliku OutFile bez wznawiania.

Jeśli plik lokalny nie istnieje, zostanie utworzony plik lokalny, a cały plik zdalny zostanie pobrany. To zachowanie jest takie samo jak w przypadku korzystania z pliku OutFile bez wznawiania.

Ta funkcja została dodana w programie PowerShell 6.1.0.

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

-RetryIntervalSec

Określa interwał między ponownymi próbami połączenia, gdy zostanie odebrany kod błędu z zakresu od 400 do 599 włącznie lub 304. Zobacz również parametr MaximumRetryCount , aby określić liczbę ponownych prób.

Type:Int32
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 ją w wartości. Wprowadź nazwę zmiennej bez znaku dolara ($).

Po określeniu zmiennej Invoke-WebRequest sesji tworzy obiekt sesji żądania internetowego i przypisuje go do zmiennej o określonej nazwie w sesji programu PowerShell. Możesz użyć zmiennej w sesji, gdy tylko polecenie zakończy się.

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. Można go użyć do udostępniania stanu i danych między żądaniami internetowymi.

Aby użyć sesji żądania internetowego 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 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

-SkipCertificateCheck

Pomija sprawdzanie poprawności certyfikatu. Obejmuje to wszystkie weryfikacje, takie jak wygaśnięcie, odwołanie, zaufany urząd główny itp.

Ostrzeżenie

Użycie tego parametru nie jest bezpieczne i nie jest zalecane. Ten przełącznik ma być używany tylko dla znanych hostów przy użyciu certyfikatu z podpisem własnym do celów testowych. Użyj na własne ryzyko.

Ta funkcja została dodana w programie PowerShell 6.0.0.

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

-SkipHeaderValidation

Wskazuje, że polecenie cmdlet powinno dodać nagłówki do żądania bez walidacji.

Ten przełącznik powinien być używany dla witryn, które wymagają wartości nagłówków, które nie są zgodne ze standardami. Wybranie tego przełącznika powoduje wyłączenie walidacji, aby umożliwić niezaznaczone przekazywanie wartości. Po określeniu wszystkie nagłówki są dodawane bez walidacji.

Ten przełącznik wyłącza walidację wartości przekazanych do parametrów ContentType, Headers i UserAgent .

Ta funkcja została dodana w programie PowerShell 6.0.0.

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

-SkipHttpErrorCheck

Ten parametr powoduje, że polecenie cmdlet ignoruje stany błędów HTTP i kontynuuje przetwarzanie odpowiedzi. Odpowiedzi na błędy są zapisywane w potoku tak, jakby zakończyły się powodzeniem.

Ten parametr został wprowadzony w programie PowerShell 7.

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

-SslProtocol

Ustawia protokoły SSL/TLS, które są dozwolone dla żądania internetowego. Domyślnie wszystkie protokoły SSL/TLS obsługiwane przez system są dozwolone. Protokół SslProtocol umożliwia ograniczenie do określonych protokołów w celach zgodności.

Te wartości są definiowane jako wyliczenie oparte na flagach. Możesz połączyć wiele wartości, aby ustawić wiele flag przy użyciu tego parametru. Wartości można przekazać do parametru SslProtocol jako tablicę wartości lub jako ciąg rozdzielany przecinkami tych wartości. Polecenie cmdlet połączy wartości przy użyciu operacji binarnej OR. Przekazywanie wartości jako tablicy jest najprostszą opcją, a także umożliwia użycie uzupełniania tabulacji wartości. Być może nie można zdefiniować wielu opcji na wszystkich platformach.

Uwaga

Na platformach innych niż Windows może nie być możliwe podanie Tls lub Tls12 jako opcja. Obsługa systemu Tls13 operacyjnego nie jest dostępna we wszystkich systemach operacyjnych i musi zostać zweryfikowana w poszczególnych systemach operacyjnych.

Ta funkcja została dodana w programie PowerShell 6.0.0 i dodano obsługę Tls13 programu PowerShell 7.1.

Type:WebSslProtocol
Accepted values:Default, Tls, Tls11, Tls12
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 nieokreślony limit czasu.

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:0
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Token

Token OAuth lub Bearer do uwzględnienia w żądaniu. Token jest wymagany przez niektóre opcje uwierzytelniania . Nie można jej używać niezależnie.

Token przyjmuje SecureString token zawierający token. Aby ręcznie podać token, użyj następujących elementów:

Invoke-WebRequest -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Ten parametr został wprowadzony w programie PowerShell 6.0.

Type:SecureString
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 dla tego parametru to:

  • Fragmentaryczne
  • Kompresji
  • Deflate
  • Gzip
  • Tożsamość
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 tylko protokół HTTP lub HTTPS.

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

Ten parametr został przestarzały. Począwszy od programu PowerShell 6.0.0, wszystkie żądania internetowe używają tylko podstawowego analizowania. Ten parametr jest uwzględniany tylko w przypadku zgodności z poprzednimi wersjami i żaden z nich nie ma wpływu na działanie polecenia cmdlet.

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. Nie można go używać z uwierzytelnianiem lub poświadczeniami i może nie być obsługiwane na wszystkich platformach.

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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 nieznacznych odmian 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 cmdlet, takiego jak UserAgent lub Credential. Wartości parametrów mają pierwszeństwo przed wartościami w sesji żądania internetowego. Nagłówki powiązane z zawartością, takie jak Content-Type, są również zastępowane, gdy obiekt MultipartFormDataContent jest dostarczany dla elementu Body.

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. Można go 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-WebRequestSessionVariable polecenia. Invoke-WebRequest tworzy sesję i zapisuje ją w zmiennej. W kolejnych poleceniach użyj zmiennej jako wartości parametru WebSession .

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

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

Dane wejściowe

Object

Treść żądania internetowego można przekazać Invoke-WebRequestdo elementu .

Dane wyjściowe

BasicHtmlWebResponseObject

Uwagi

Począwszy od programu PowerShell 6.0.0 Invoke-WebRequest obsługuje tylko podstawowe analizowanie.

Aby uzyskać więcej informacji, zobacz BasicHtmlWebResponseObject.

Ze względu na zmiany w programie .NET Core 3.1 program PowerShell 7.0 i nowsze używają właściwości HttpClient.DefaultProxy w celu określenia konfiguracji serwera proxy.

Wartość tej właściwości jest określana przez platformę:

  • W przypadku systemu Windows: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych. Jeśli te zmienne nie są zdefiniowane, właściwość pochodzi z ustawień serwera proxy użytkownika.
  • W przypadku systemu macOS: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych. Jeśli te zmienne nie są zdefiniowane, właściwość pochodzi z ustawień serwera proxy systemu.
  • W przypadku systemu Linux: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych. Jeśli te zmienne nie są zdefiniowane, właściwość inicjuje nieskonfigurowane wystąpienie, które pomija wszystkie adresy.

Zmienne środowiskowe używane do DefaultProxy inicjowania na platformach opartych na systemach Windows i Unix są następujące:

  • HTTP_PROXY: nazwa hosta lub adres IP serwera proxy używanego na żądaniach HTTP.
  • HTTPS_PROXY: nazwa hosta lub adres IP serwera proxy używanego na żądaniach HTTPS.
  • ALL_PROXY: nazwa hosta lub adres IP serwera proxy używanego na żądaniach HTTP i HTTPS w przypadku HTTP_PROXY lub HTTPS_PROXY nie są zdefiniowane.
  • NO_PROXY: rozdzielona przecinkami lista nazw hostów, które powinny zostać wykluczone z serwera proxy.