Invoke-RestMethod
Wysyła żądanie HTTP lub HTTPS do usługi internetowej RESTful.
Składnia
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-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>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-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>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-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>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-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>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Opis
Polecenie Invoke-RestMethod
cmdlet wysyła żądania HTTP i HTTPS do usług internetowych Representational State Transfer (REST), które zwracają bogato ustrukturyzowane dane.
Program PowerShell formatuje odpowiedź na podstawie typu danych. W przypadku kanału informacyjnego RSS lub ATOM program PowerShell zwraca węzły XML item lub Entry. W przypadku formatu JavaScript Object Notation (JSON) lub XML program PowerShell konwertuje lub deserializuje zawartość na [PSCustomObject]
obiekty.
Uwaga
Gdy punkt końcowy REST zwraca wiele obiektów, obiekty są odbierane jako tablica. Jeśli dane wyjściowe są przesyłane potokiem do Invoke-RestMethod
innego polecenia, jest on wysyłany jako pojedynczy [Object[]]
obiekt. Zawartość tej tablicy nie jest wyliczana dla następnego polecenia w potoku.
To polecenie cmdlet zostało wprowadzone w Windows PowerShell 3.0.
Począwszy od programu PowerShell 7.0, Invoke-RestMethod
obsługuje konfigurację serwera proxy zdefiniowaną przez zmienne środowiskowe. Zobacz sekcję Uwagi tego artykułu.
Przykłady
Przykład 1. Pobieranie kanału informacyjnego RSS programu PowerShell
W tym przykładzie użyto Invoke-RestMethod
polecenia cmdlet , aby uzyskać informacje z kanału informacyjnego RSS bloga programu PowerShell. Polecenie używa Format-Table
polecenia cmdlet do wyświetlania wartości właściwości Title i pubDate każdego bloga w tabeli.
Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
Format-Table -Property Title, pubDate
Title pubDate
----- -------
Join the PowerShell 10th Anniversary Celebration! Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016 Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934 Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source! Thu, 18 Aug 2016 15:32:02 +0000
Przykład 2. Uruchamianie żądania POST
W tym przykładzie użytkownik uruchamia Invoke-RestMethod
żądanie POST w witrynie internetowej intranetowej w organizacji użytkownika.
$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
output_mode = "csv"
earliest_time = "-2d@d"
latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv
Zostanie wyświetlony monit o podanie poświadczeń, a następnie zapisany w $Cred
pliku i adres URL, do którego będzie uzyskiwany dostęp, jest zdefiniowany w pliku $Url
.
Zmienna $Body
opisuje kryteria wyszukiwania, określa csv jako tryb danych wyjściowych i określa okres dla zwracanych danych, które rozpoczynają się dwa dni temu i kończą się jeden dzień temu. Zmienna treść określa wartości parametrów, które mają zastosowanie do określonego interfejsu API REST, z którym Invoke-RestMethod
komunikuje się.
Polecenie Invoke-RestMethod
jest uruchamiane ze wszystkimi zmiennymi, określając ścieżkę i nazwę pliku dla wynikowego pliku wyjściowego CSV.
Przykład 3. Obserwowanie linków relacyjnych
Niektóre interfejsy API REST obsługują stronicowanie za pośrednictwem linków relacyjnych na RFC5988. Zamiast analizować nagłówek, aby uzyskać adres URL następnej strony, możesz to zrobić za Ciebie. Ten przykład zwraca dwie pierwsze strony problemów z repozytorium GitHub programu PowerShell.
$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2
Przykład 4: Uproszczone przesyłanie danych wieloczęściowych/formularzy
Niektóre interfejsy API wymagają multipart/form-data
przesłania do przekazywania plików i zawartości mieszanej. W tym przykładzie pokazano, jak zaktualizować profil 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-RestMethod -Uri $Uri -Method Post -Form $Form
Formularz profilu wymaga następujących pól: firstName
, , lastName
email
, avatar
, birthday
i hobbies
. Interfejs API oczekuje, że obraz zdjęcia profilu użytkownika zostanie dostarczony w avatar
polu. Interfejs API będzie również akceptować 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 zostaną przekonwertowane na ciągi. System.IO.FileInfo
Jeśli wartość jest obecna, zawartość pliku zostanie przesłana. Jeśli istnieje kolekcja, taka jak tablice lub listy, pole formularza zostanie przesłane wiele razy.
Przy użyciu Get-Item
klucza avatar
FileInfo
obiekt zostanie ustawiony jako wartość. Wynikiem jest to, że dane obrazu dla jdoe.png
elementu zostaną przesłane.
Po podaniu listy do hobbies
klucza hobbies
pole będzie obecne w przesłanych raz dla każdego elementu listy.
Przykład 5. Przekazywanie wielu nagłówków
Interfejsy API często wymagają przekazanych nagłówków na potrzeby uwierzytelniania lub weryfikacji. W tym przykładzie pokazano, jak przekazać wiele nagłówków z interfejsu hash-table
API REST do interfejsu API REST.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
Przykład 6. Wyliczanie zwracanych elementów w potoku
Usługa GitHub zwraca wiele obiektów tablicy. Jeśli dane wyjściowe są przesyłane potokiem do innego polecenia, jest on wysyłany jako pojedynczy [Object[]]
obiekt.
Aby wyliczyć obiekty do potoku, należy przekazać wyniki potokowi lub opakować Write-Output
polecenie cmdlet w nawiasach. Poniższy przykład zlicza liczbę obiektów zwracanych przez usługę GitHub. Następnie zlicza liczbę obiektów wyliczeń do potoku.
$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1
$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30
$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30
Parametry
-AllowUnencryptedAuthentication
Umożliwia wysyłanie poświadczeń i wpisów tajnych za pośrednictwem niezaszyfrowanych połączeń. Domyślnie podanie poświadczeń lub dowolnej opcji uwierzytelniania z identyfikatorem URI , który nie zaczyna się, https://
spowoduje błąd, a żądanie zostanie przerwane, aby zapobiec przypadkowej komunikacji wpisów tajnych w postaci zwykłego tekstu za pośrednictwem niezaszyfrowanych połączeń. Aby zastąpić to zachowanie na własne ryzyko, podaj parametr AllowUnencryptedAuthentication .
Ostrzeżenie
Użycie tego parametru nie jest bezpieczne i nie jest zalecane. Zapewnia ona zgodność tylko ze starszymi systemami, które nie mogą zapewnić szyfrowanych 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: | False |
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. Nie można użyć parametru Authentication z parametrem UseDefaultCredentials .
Dostępne opcje uwierzytelniania:
None
: jest to opcja domyślna, gdy uwierzytelnianie nie jest podane. Nie będzie używane żadne jawne uwierzytelnianie.Basic
: wymaga poświadczeń. Poświadczenia będą używane do wysyłania nagłówka podstawowego uwierzytelnianiaAuthorization: Basic
RFC 7617 w formaciebase64(user:password)
.Bearer
: wymaga parametru Token . Wysyła nagłówek RFC 6750Authorization: Bearer
z podanym tokenem.OAuth
: wymaga parametru Token . Wysyła nagłówek RFC 6750Authorization: Bearer
z podanym tokenem.
Podanie uwierzytelniania zastępuje wszystkie Authorization
nagłówki dostarczone do nagłówków lub uwzględnione w składniku 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ść jest zawartością żądania, która jest zgodna z nagłówkami.
Możesz również przekazać wartość treści do Invoke-RestMethod
metody .
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 (Uniform Resource Identifier) jako parametrów zapytania. W przypadku innych typów żądań (takich jak POST) treść jest ustawiana jako wartość treści żądania w standardowym formacie name=value.
Gdy treść jest formularzem lub jest to dane wyjściowe innego Invoke-WebRequest
wywołania, program PowerShell ustawia zawartość żądania na pola formularza.
Parametr Body może również akceptować obiekt System.Net.Http.MultipartFormDataContent . Ułatwi multipart/form-data
to żądania. Po podaniu obiektu MultipartFormDataContentdla treści wszystkie nagłówki powiązane z zawartością dostarczone do parametrów ContentType, Headers lub WebSession zostaną zastąpione przez nagłówki MultipartFormDataContent
zawartości obiektu. 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, który jest 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 certyfikatu (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. 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-RestMethod
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 zostanie zastąpiona, gdy MultipartFormDataContent
obiekt zostanie dostarczony dla treści.
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świadczenie może być używane samodzielnie lub w połączeniu z niektórymi opcjami parametrów uwierzytelniania . W przypadku użycia tylko poświadczeń do serwera zdalnego należy podać tylko wtedy, gdy serwer zdalny wysyła żądanie żądania uwierzytelnienia. W przypadku użycia z opcjami uwierzytelniania poświadczenia zostaną jawnie wysł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 securestring?.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CustomMethod
Określa niestandardową metodę używaną dla żądania internetowego. Tej opcji można używać z metodą żądania wymaganą przez punkt końcowy nie jest dostępna w metodzie . Metody i metody CustomMethod nie można używać razem.
Przykład:
Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
Spowoduje to wysłanie TEST
żądania HTTP do interfejsu API.
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 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: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FollowRelLink
Wskazuje, że polecenie cmdlet powinno być zgodne z linkami relacyjnymi.
Niektóre interfejsy API REST obsługują stronicowanie za pośrednictwem linków relacyjnych na RFC5988. Zamiast analizować nagłówek, aby uzyskać adres URL następnej strony, możesz to zrobić za Ciebie. Aby ustawić liczbę prób obserwowania linków relacyjnych, użyj parametru MaximumFollowRelLink .
W przypadku korzystania z tego przełącznika polecenie cmdlet zwraca kolekcję stron wyników. Każda strona wyników może zawierać wiele elementów wyników.
Ta funkcja została dodana w programie PowerShell 6.0.0.
Type: | SwitchParameter |
Aliases: | FL |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Form
Konwertuje słownik na multipart/form-data
przesyłanie. Formularz nie może być używany z treścią.
Jeśli właściwość ContentType zostanie zignorowana.
Klucze słownika będą używane jako nazwy pól formularza. Domyślnie wartości formularzy zostaną przekonwertowane na wartości ciągu.
Jeśli wartość jest obiektem System.IO.FileInfo , zawartość pliku binarnego zostanie przesłana.
Nazwa pliku zostanie przesłana jako .filename
Parametr MIME zostanie ustawiony na wartość application/octet-stream
. Get-Item
Można go użyć, aby uprościć dostarczanie obiektu System.IO.FileInfo .
$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
Jeśli wartość jest typem kolekcji, takim jak Tablica lub Lista, pole for zostanie przesłane wiele razy. Wartości listy będą 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 zostanie podane trzy razy w formularzu, raz dla każdego elementu Vacation
, Italy
i 2017
. Pole pictures
zostanie również przesłane raz dla każdego pliku w folderze 2017-Italy
. Zawartość binarna plików w tym folderze zostanie przesłana 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ótów lub słownik.
Aby ustawić nagłówki UserAgent, użyj parametru UserAgent . Nie można użyć tego parametru do określenia User-Agent
lub nagłówków plików cookie.
Nagłówki powiązane z zawartością, takie jak Content-Type
zostaną zastąpione, gdy MultipartFormDataContent
obiekt zostanie dostarczony 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ścią domyślną jest bieżąca lokalizacja.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumFollowRelLink
Określa, ile razy należy użyć linków relacji, jeśli jest używana funkcja FollowRelLink . W przypadku ograniczania przepustowości interfejsu API REST może być wymagana mniejsza wartość z powodu zbyt wielu żądań. Wartość domyślna to [Int32]::MaxValue
. Wartość 0 (zero) uniemożliwia korzystanie z poniższych linków relacyjnych.
Type: | Int32 |
Aliases: | ML |
Position: | Named |
Default value: | Int32.MaxValue |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
Określa, ile razy program PowerShell przekierowuje połączenie do alternatywnego identyfikatora URI (Uniform Resource Identifier), zanim połączenie zakończy się niepowodzeniem. Wartość domyślna to 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 |
-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 służący do określania liczby 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że być używany 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 będzie używać serwera proxy do osiągnięcia miejsca docelowego.
Jeśli musisz pominąć serwer proxy skonfigurowany w programie Internet Explorer lub serwer proxy określony w środowisku, użyj tego przełącznika.
Ten parametr został wprowadzony w programie PowerShell 6.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutFile
Zapisuje treść odpowiedzi w określonym pliku wyjściowym. Wprowadź ścieżkę i nazwę pliku. Jeśli pominięto ścieżkę, wartością domyślną jest bieżąca lokalizacja. Nazwa jest traktowana jako ścieżka literału. Nazwy zawierające nawiasy kwadratowe ([]
) muszą być ujęte w apostrofy ('
).
Domyślnie Invoke-RestMethod
zwraca wyniki do potoku.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Ten parametr jest prawidłowy tylko wtedy, gdy parametr OutFile jest również używany w poleceniu . Intencją jest zapisanie wyników w pliku i potoku.
Uwaga
Gdy używasz parametru PassThru , dane wyjściowe są zapisywane w potoku, ale plik nie jest tworzony. Aby uzyskać więcej informacji, zobacz Problem z programem PowerShell #15409.
Type: | SwitchParameter |
Position: | Named |
Default value: | No output |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Wskazuje, że polecenie cmdlet powinno zachować Authorization
nagłówek , gdy istnieje, 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 zostać wysłany do lokalizacji przekierowania.
Ta funkcja została dodana w programie PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
Używa serwera proxy dla żądania, zamiast łączyć się bezpośrednio z zasobem internetowym. Wprowadź identyfikator URI (Uniform Resource Identifier) serwera proxy sieci.
Ta funkcja została dodana w programie PowerShell 6.0.0.
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, który jest określony przez parametr 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: | None |
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: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ResponseHeadersVariable
Tworzy zmienną zawierającą słownik nagłówków odpowiedzi. Wprowadź nazwę zmiennej bez znaku dolara ($
). Klucze słownika zawierają nazwy pól i wartości nagłówka odpowiedzi zwrócone przez serwer internetowy.
Ta funkcja została dodana w programie PowerShell 6.0.0.
Type: | String |
Aliases: | RHV |
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. Parametr Resume wymaga parametru 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 podejmie próbę wznowienia pobierania pliku i dołącz 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, a cały plik zdalny zostanie całkowicie pobrany ponownie. 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, a cały plik zdalny zostanie całkowicie pobrany ponownie. 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 całkowicie 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: | False |
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
Tworzy zmienną zawierającą sesję żądania internetowego. Wprowadź nazwę zmiennej bez znaku dolara ($
).
Po określeniu zmiennej Invoke-RestMethod
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, które obejmują 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: | False |
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.
Spowoduje to wyłączenie walidacji wartości przekazanych do parametrówContentType, Headers i UserAgent.
Ta funkcja została dodana w programie PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
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 podać wielu wartości 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, Tls13 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StatusCodeVariable
Tworzy zmienną zawierającą wynik kodu stanu HTTP żądania. Wprowadź nazwę zmiennej bez znaku dolara ($
).
Parametr może identyfikować komunikaty o powodzeniu lub komunikaty o niepowodzeniu w przypadku użycia z parametrem SkipHttpErrorCheck .
Wprowadź nazwę zmiennej parametru jako ciąg, taki jak -StatusCodeVariable "scv"
.
Ten parametr został wprowadzony w programie PowerShell 7.
Type: | String |
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: | None |
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 podać token, ręcznie użyj następujących elementów:
Invoke-RestMethod -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. Ten parametr obsługuje wartości HTTP, HTTPS, FTP i FILE.
Ten parametr jest wymagany. Nazwa parametru (URI) jest opcjonalna.
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, a użycie go nie będzie miało wpływu na działanie polecenia cmdlet.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
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: | False |
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.
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. Nagłówki powiązane z zawartością, takie jak Content-Type
, również zostaną zastąpione, gdy obiekt MultipartFormDataContent jest dostarczany dla treści.
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-RestMethod
SessionVariable polecenia. Invoke-RestMethod
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
Treść żądania internetowego można przekazać potokiem do Invoke-RestMethod
.
Dane wyjściowe
System.Int64, System.String, System.Xml.XmlDocument
Dane wyjściowe polecenia cmdlet zależą od formatu pobieranej zawartości.
PSObject
Jeśli żądanie zwraca ciągi JSON, Invoke-RestMethod
zwraca obiekt PSObject reprezentujący ciągi.
Uwagi
Niektóre funkcje mogą nie być dostępne na wszystkich platformach.
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 różna w zależności od platformy:
- W przypadku systemu Windows: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych lub, jeśli nie są one zdefiniowane, z ustawień serwera proxy użytkownika.
- W przypadku systemu macOS: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych lub, jeśli nie są one zdefiniowane, z ustawień serwera proxy systemu.
- W przypadku systemu Linux: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych lub, jeśli nie są one zdefiniowane, ta 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 w żądaniach HTTP.HTTPS_PROXY
: nazwa hosta lub adres IP serwera proxy używanego w żądaniach HTTPS.ALL_PROXY
: nazwa hosta lub adres IP serwera proxy używanego w żądaniach HTTP i HTTPS w przypadkuHTTP_PROXY
lubHTTPS_PROXY
nie są zdefiniowane.NO_PROXY
: rozdzielona przecinkami lista nazw hostów, które powinny być wykluczone z serwera proxy.