Invoke-RestMethod

Odwołanie

Moduł:: Microsoft.PowerShell.Utility

Wysyła żądanie HTTP lub HTTPS do usługi internetowej RESTful.

Składnia

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Opis

Polecenie Invoke-RestMethod cmdlet wysyła żądania HTTP i HTTPS do usług sieci Web 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 Item lub Entry XML. W przypadku notacji obiektów JavaScript (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. W przypadku potoku danych wyjściowych z Invoke-RestMethod do 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 programie 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.

Począwszy od programu PowerShell 7.4 kodowanie znaków dla żądań domyślnych dla żądań UTF-8 zamiast ASCII. Jeśli potrzebujesz innego kodowania, musisz ustawić charset atrybut w nagłówku Content-Type .

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 wyjściowy i określa okres dla zwracanych danych, które rozpoczynają się dwa dni temu i kończy się jeden dzień temu. Zmienna treść określa wartości parametrów, które mają zastosowanie do określonego interfejsu API REST, za pomocą którego 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 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, emailavatar, 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.

Za pomocą Get-Item avatar klucza 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. Wyliczenie zwracanych elementów w potoku

Usługa GitHub zwraca wiele obiektów tablicy. Jeśli przesyłasz dane wyjściowe do innego polecenia, jest on wysyłany jako pojedynczy [Object[]]obiekt.

Aby wyliczyć obiekty do potoku, należy przekazać wyniki do Write-Output polecenia cmdlet lub opakowować je w nawiasy. Poniższy przykład zlicza liczbę obiektów zwracanych przez usługę GitHub. Następnie zlicza liczbę obiektów wyliczonych 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

Przykład 7. Pomijanie walidacji nagłówka

Domyślnie Invoke-RestMethod polecenie cmdlet weryfikuje wartości dobrze znanych nagłówków, które mają format wartości zdefiniowanej przez standardy. W poniższym przykładzie pokazano, jak ta walidacja może zgłosić błąd i jak można użyć parametru SkipHeaderValidation , aby uniknąć sprawdzania poprawności wartości punktów końcowych, które tolerują niepoprawnie sformatowane wartości.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org to usługa, która zwraca informacje o żądaniach internetowych i odpowiedziach na potrzeby rozwiązywania problemów. Zmienna $Uri jest przypisywana do /headers punktu końcowego usługi, który zwraca nagłówki żądania jako zawartość w odpowiedzi.

Nagłówek If-Match żądania jest zdefiniowany w sekcji RFC-7232 3.1 i wymaga, aby wartość tego nagłówka została zdefiniowana przy użyciu cudzysłowów otaczających. Zmienna $InvalidHeaders ma przypisaną tabelę skrótów If-Match , w której wartość jest nieprawidłowa, ponieważ jest zdefiniowana jako 12345 zamiast "12345".

Wywołanie Invoke-RestMethod z nieprawidłowymi nagłówkami zwraca raportowanie błędów, że sformatowana wartość jest nieprawidłowa. Żądanie nie jest wysyłane do punktu końcowego.

Wywołanie Invoke-RestMethod za pomocą parametru SkipHeaderValidation ignoruje błąd weryfikacji i wysyła żądanie do punktu końcowego. Ponieważ punkt końcowy toleruje niezgodne wartości nagłówka, polecenie cmdlet zwraca obiekt odpowiedzi bez błędu.

Przykład 8. Wysyłanie żądania przy użyciu protokołu HTTP 2.0

W tym przykładzie zapytania dotyczące problemu z usługą GitHub przy użyciu protokołu HTTP 2.0.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

Przykład 9. Wysyłanie żądania do aplikacji gniazda systemu Unix

Niektóre aplikacje, takie jak Docker, uwidaczniają gniazdo systemu Unix na potrzeby komunikacji. Ten przykład wykonuje zapytania dotyczące listy obrazów platformy Docker przy użyciu interfejsu API platformy Docker. Polecenie cmdlet nawiązuje połączenie z demonem platformy Docker przy użyciu gniazda systemu Unix.

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

Parametry

-AllowInsecureRedirect

Umożliwia przekierowywanie z protokołu HTTPS do protokołu HTTP. Domyślnie każde żądanie przekierowane z protokołu HTTPS do protokołu HTTP powoduje wystąpienie błędu i żądanie zostało przerwane, aby zapobiec przypadkowej komunikacji w postaci zwykłego tekstu za pośrednictwem nieszyfrowanych połączeń. Aby zastąpić to zachowanie na własnym ryzyku, użyj parametru AllowInsecureRedirect .

Ten parametr został dodany w programie PowerShell 7.4.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-AllowUnencryptedAuthentication

Umożliwia wysyłanie poświadczeń i wpisów tajnych za pośrednictwem nieszyfrowanych 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 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. Zapewnia ona tylko zgodność ze starszymi systemami, które nie mogą zapewnić zaszyfrowanych połączeń. Użyj własnego ryzyka.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Authentication

Określa jawny typ uwierzytelniania do użycia dla żądania. Wartość domyślna to Brak. Nie można użyć parametru uwierzytelniania 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 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 Authorization nagłówki dostarczone do nagłówków lub zawarte w webSession.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Typ:	WebAuthenticationType
Dopuszczalne wartości:	None, Basic, Bearer, OAuth
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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.

Parametr Treść może służyć do określenia listy parametrów zapytania lub określenia zawartości odpowiedzi. W przypadku parametrów zapytania polecenie cmdlet używa metody Metoda System.Net.WebUtility.UrlEncode w celu zakodowania par klucz-wartość. Aby uzyskać więcej informacji na temat ciągów kodowania adresów URL, zobacz dokumentację metody UrlEncode().

Gdy dane wejściowe są żądaniem POST, a treść jest ciągiem, wartość po lewej stronie pierwszego znaku równości (=) jest ustawiana jako klucz w danych formularza, a pozostały tekst jest ustawiany jako wartość. Aby określić wiele kluczy, użyj obiektu IDictionary , takiego jak tabela skrótów, w polu Treść.

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 PATCH) treść jest ustawiana jako wartość treści żądania w standardowym name=value formacie z wartościami zakodowanymi w adresie URL.

Gdy dane wejściowe są obiektem System.Xml.XmlNode , a deklaracja XML określa kodowanie, to kodowanie jest używane dla danych w żądaniu, chyba że zostanie zastąpione przez parametr ContentType .

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ż zaakceptować obiekt System.Net.Http.MultipartFormDataContent . Ułatwi multipart/form-data to żądania. Gdy obiekt MultipartFormDataContent jest dostarczany dla elementu Body, wszystkie nagłówki powiązane z zawartością dostarczane 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.

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

Uwaga

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

Typ:	String
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-ConnectionTimeoutSeconds

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 parametr ConnectionTimeoutSeconds 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.

Ten parametr zastąpił parametr TimeoutSec w programie PowerShell 7.4. Możesz użyć wartości TimeoutSec jako aliasu dla parametru ConnectionTimeoutSeconds.

Typ:	Int32
Aliasy:	TimeoutSec
Position:	Named
Domyślna wartość:	0
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-ContentType

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

Jeśli wartość parametru ContentType zawiera format kodowania (jako charset), polecenie cmdlet używa tego formatu do kodowania treści żądania internetowego. Jeśli właściwość ContentType nie określa formatu kodowania, zamiast tego zostanie użyty domyślny format kodowania. Przykładem elementu ContentType z formatem kodowania jest text/plain; charset=iso-8859-5, który określa alfabet łaciński/cyrylica .

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 elementu Body.

Począwszy od programu PowerShell 7.4, jeśli używasz tego zarówno tego parametru, jak i parametru Headers do zdefiniowania nagłówka Content-Type , używana jest wartość określona w parametrze ContentType .

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 mogą być używane samodzielnie lub w połączeniu z niektórymi opcjami parametrów uwierzytelniania . Jeśli jest używany sam, podasz poświadczenia do serwera zdalnego 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 protokół SecureString?.

Typ:	PSCredential
Position:	Named
Domyślna wartość:	Current user
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-CustomMethod

Określa metodę niestandardową używaną dla żądania internetowego. Może to być używane z metodą żądania wymaganą przez punkt końcowy nie jest dostępną opcją 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.

Typ:	String
Aliasy:	CM
Position:	Named
Domyślna wartość:	None
Wymagane:	True
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ść:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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ć, ile razy ma być zgodne z linkami relacji, 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.

Typ:	SwitchParameter
Aliasy:	FL
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Form

Konwertuje słownik na multipart/form-data przesyłanie. Formularz może nie 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 formularza zostaną przekonwertowane na wartości ciągu.

Jeśli wartość jest obiektem System.IO.FileInfo , zostanie przesłana zawartość pliku binarnego. Nazwa pliku zostanie przesłana jako .filename Plik MIME zostanie 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 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 , zostanie przesłana zawartość pliku binarnego. 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, Italyi 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.

Typ:	IDictionary
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.

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

Począwszy od programu PowerShell 7.4, jeśli używasz tego parametru do zdefiniowania nagłówka Content-Type i używania parametru ContentType, używana jest wartość określona w parametrze ContentType.

Typ:	IDictionary
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-HttpVersion

Określa wersję PROTOKOŁU HTTP używaną dla żądania. Wartość domyślna to 1.1.

Prawidłowe wartości to:

Typ:	Version
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

-MaximumFollowRelLink

Określa, ile razy należy postępować zgodnie z linkami relacji, jeśli jest używany link FollowRelLink . W przypadku ograniczania przepływności interfejsu API REST z powodu zbyt wielu żądań może być wymagana mniejsza wartość. Domyślna wartość to [Int32]::MaxValue. Wartość 0 (zero) uniemożliwia korzystanie z poniższych linków relacyjnych.

Typ:	Int32
Aliasy:	ML
Position:	Named
Domyślna wartość:	Int32.MaxValue
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

-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 określający interwał między ponownymi próbami.

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

Parametr CustomMethod może być używany dla metod żądań, które nie zostały wymienione powyżej.

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

-NoProxy

Wskazuje, że polecenie cmdlet nie będzie używać serwera proxy do dotarcia do 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.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-OperationTimeoutSeconds

Ten limit czasu dotyczy odczytów danych w strumieniu, a nie do czasu strumienia jako całości. Wartość domyślna, 0, określa limit czasu nieokreślony.

Ustawienie wartości na 30 sekund oznacza, że każde opóźnienie dłuższe niż 30 sekund między danymi w strumieniu kończy żądanie. Duży plik, który trwa kilka minut do pobrania, nie zakończy się, chyba że strumień zostanie zatrzymany przez ponad 30 sekund.

Typ:	Int32
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-OutFile

Domyślnie Invoke-RestMethod zwraca wyniki do potoku. Gdy używasz parametru OutFile , wyniki są zapisywane w określonym pliku i nie są zwracane do potoku. Wprowadź ścieżkę i nazwę pliku. Aby wysłać wyniki do pliku i do potoku, dodaj parametr PassThru .

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 apostrofy (').

Począwszy od programu PowerShell 7.4, można określić ścieżkę folderu bez nazwy pliku. Gdy to zrobisz, polecenie używa nazwy pliku z ostatniego segmentu rozpoznanego identyfikatora URI po wszelkich przekierowaniach. Po określeniu ścieżki folderu dla elementu OutFile nie można użyć parametru Resume .

Typ:	String
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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. Jest to naprawione w programie PowerShell 7.5-preview.4. Aby uzyskać więcej informacji, zobacz Problem z programem PowerShell #15409.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	No output
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-PreserveHttpMethodOnRedirect

Wskazuje, że polecenie cmdlet powinno zachować metodę żądania między przekierowaniami.

Domyślnie polecenie cmdlet zmienia metodę na GET po przekierowaniu. Określenie tego parametru wyłącza tę logikę, aby upewnić się, że docelowa metoda może być używana z przekierowaniem.

Ta funkcja została dodana w programie PowerShell 7.4.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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.

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

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 .

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-ResponseHeadersVariable

Tworzy zmienną zawierającą słownik nagłówków odpowiedzi. Wprowadź nazwę zmiennej bez symbolu 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.

Typ:	String
Aliasy:	RHV
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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łą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, a cały plik zdalny zostanie całkowicie ponownie pobrany. To zachowanie jest takie samo jak w przypadku używania elementu 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 ponownie pobrany. To zachowanie jest takie samo jak w przypadku używania elementu 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 używania elementu OutFile bez wznawiania.

Ta funkcja została dodana w programie PowerShell 6.1.0.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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. Wartość musi zawierać się między 1 i [int]::MaxValue. Jeśli kod błędu to 429, a odpowiedź zawiera właściwość Retry-After w nagłówkach, polecenie cmdlet używa tej wartości dla interwału ponawiania, nawet jeśli ten parametr jest określony.

Zobacz również parametr MaximumRetryCount, aby określić liczbę ponownych prób.

Typ:	Int32
Position:	Named
Domyślna wartość:	5
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-SessionVariable

Tworzy zmienną zawierającą sesję żądania internetowego. Wprowadź nazwę zmiennej bez symbolu znaku dolara ($).

Po określeniu zmiennej Invoke-RestMethod 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.

Przed programem PowerShell 7.4 sesja żądania internetowego 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.

Począwszy od programu PowerShell 7.4, sesja żądania internetowego jest trwała, o ile właściwości sesji nie są zastępowane w kolejnym żądaniu. Gdy tak, polecenie cmdlet ponownie utworzy sesję przy użyciu nowych wartości. Sesje trwałe zmniejszają obciążenie dla powtarzających się żądań, dzięki czemu są znacznie szybsze.

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

-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 na znanych hostach przy użyciu certyfikatu z podpisem własnym do celów testowych. Użyj własnego ryzyka.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-SkipHeaderValidation

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

Ten przełącznik powinien być używany w przypadku witryn wymagających wartości nagłówka, które nie są zgodne ze standardami. Określenie 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 sprawdzania poprawności wartości przekazywanych do parametrów ContentType, Headers i UserAgent .

Ta funkcja została dodana w programie PowerShell 6.0.0.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-SkipHttpErrorCheck

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

Ten parametr został wprowadzony w programie PowerShell 7.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-SslProtocol

Ustawia protokoły SSL/TLS, które są dozwolone dla żądania internetowego. Domyślnie dozwolone są protokoły SSL/TLS obsługiwane przez system. 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 ze sobą, 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 binary-OR. Przekazywanie wartości jako tablicy jest najprostszą opcją, a także umożliwia użycie uzupełniania tabulatorów na wartościach. Może nie być możliwe podanie wielu wartości na wszystkich platformach.

Uwaga

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

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

Typ:	WebSslProtocol
Dopuszczalne wartości:	Default, Tls, Tls11, Tls12, Tls13
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-StatusCodeVariable

Tworzy zmienną zawierającą wynik kodu stanu HTTP żądania. Wprowadź nazwę zmiennej bez symbolu znaku dolara ($).

Parametr może identyfikować komunikaty o powodzeniu lub komunikaty o błędach 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.

Typ:	String
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Token

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

Token przyjmuje SecureString token zawierający token. Aby podać token, ręcznie użyj następującego polecenia:

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

Ten parametr został wprowadzony w programie PowerShell 6.0.

Typ:	SecureString
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:

Fragmentaryczne
Kompresować
Deflate
GZip
Tożsamość

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

-UnixSocket

Określa nazwę gniazda systemu Unix do nawiązania połączenia. Ten parametr jest obsługiwany w systemach unix i windows w wersji 1803 lub nowszej. Aby uzyskać więcej informacji na temat obsługi gniazd systemu Unix w systemie Windows, zobacz wpis w blogu Windows/WSL Interop z AF_UNIX .

Ten parametr został dodany w programie PowerShell 7.4.

Typ:	UnixDomainSocketEndPoint
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. Ten parametr obsługuje wartości HTTP, HTTPS, FTP i FILE.

Ten parametr jest wymagany. Nazwa parametru (Uri) jest opcjonalna.

Typ:	Uri
Position:	0
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-UseBasicParsing

Ten parametr został przestarzały. Począwszy od programu PowerShell 6.0.0, wszystkie żądania sieci Web używają tylko podstawowego analizowania. Ten parametr jest uwzględniany tylko w przypadku zgodności z poprzednimi wersjami i użycie go nie będzie miało wpływu na działanie polecenia cmdlet.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
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. Nie można tego używać z uwierzytelnianiem lub poświadczeniami i może nie być obsługiwane na wszystkich platformach.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.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.

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. Nagłówki powiązane z zawartością, takie jak Content-Type, również zostaną zastąpione, gdy obiekt MultipartFormDataContent jest dostarczany dla treść.

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 .

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

Object

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

Dane wyjściowe

Int64

Gdy żądanie zwraca liczbę całkowitą, to polecenie cmdlet zwraca tę liczbę całkowitą.

String

Gdy żądanie zwraca ciąg, to polecenie cmdlet zwraca ten ciąg.

XmlDocument

Gdy żądanie zwraca prawidłowy kod XML, to polecenie cmdlet zwraca je jako element XmlDocument.

PSObject

Gdy żądanie zwraca ciągi JSON, to polecenie cmdlet zwraca obiekt PSObject reprezentujący dane.

Uwagi

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

Wszystkie platformy:
- irm

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 te nie są 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 to:

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 w żądaniach HTTPS.
ALL_PROXY: nazwa hosta lub adres IP serwera proxy używanego w żą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 być wykluczone z serwera proxy.

Program PowerShell 7.4 dodał obsługę algorytmu kompresji Brotli.

Udostępnij za pośrednictwem

Invoke-RestMethod

Składnia

Opis

Przykłady

Przykład 1. Pobieranie kanału informacyjnego RSS programu PowerShell

Przykład 2. Uruchamianie żądania POST

Przykład 3. Obserwowanie linków relacyjnych

Przykład 4: Uproszczone przesyłanie danych wieloczęściowych/formularzy

Przykład 5. Przekazywanie wielu nagłówków

Przykład 6. Wyliczenie zwracanych elementów w potoku

Przykład 7. Pomijanie walidacji nagłówka

Przykład 8. Wysyłanie żądania przy użyciu protokołu HTTP 2.0

Przykład 9. Wysyłanie żądania do aplikacji gniazda systemu Unix

Parametry

-AllowInsecureRedirect

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ConnectionTimeoutSeconds

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-HttpVersion

-InFile

-MaximumFollowRelLink

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OperationTimeoutSeconds

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-PreserveHttpMethodOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-ResponseHeadersVariable

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-StatusCodeVariable

-Token

-TransferEncoding

-UnixSocket

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Dane wejściowe

Dane wyjściowe

Uwagi

Linki powiązane

Dodatkowe zasoby