Invoke-RestMethod

Moduł:

Microsoft.PowerShell.Utility Module

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

Składnia

StandardMethod (Domyślna)

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]

StandardMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]

CustomMethod

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

Opis

Polecenie cmdlet Invoke-RestMethod 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 XML Item lub Entry. W przypadku notacji obiektów JavaScript (JSON) lub XML program PowerShell konwertuje lub deserializuje zawartość na obiekty [pscustomobject]. Komentarze są dozwolone w danych JSON.

Uwaga / Notatka

Gdy punkt końcowy REST zwraca wiele obiektów, obiekty są odbierane jako tablica. Jeśli przesyłasz dane wyjściowe z Invoke-RestMethod do innego polecenia, jest on wysyłany jako pojedynczy obiekt [Object[]]. Zawartość tej tablicy nie jest przetwarzana dla następnego polecenia w linii poleceń.

Ten cmdlet został wprowadzony 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ę NOTES tego artykułu.

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

Przykłady

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

W tym przykładzie użyto polecenia cmdlet Invoke-RestMethod, aby uzyskać informacje z kanału informacyjnego RSS bloga programu PowerShell. Polecenie używa cmdletu Format-Table 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, aby wykonać żądanie POST w intranetowej witrynie internetowej 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

Polecenie cmdlet wyświetla monit o podanie poświadczeń i przechowuje je w $Cred. $Url zawiera adres URL punktu końcowego REST.

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 się komunikuje.

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 zgodnie z RFC5988. Zamiast analizować nagłówek w celu uzyskania adresu URL do następnej strony, możesz pozwolić, aby cmdlet zrobił to 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 wieloczęściowe/Form-Data

Niektóre interfejsy API wymagają przesłania multipart/form-data plików i różnorodnej zawartości. 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, birthdayi hobbies. API oczekuje dostarczenia obrazu zdjęcia profilowego użytkownika w polu avatar. Interfejs API akceptuje również wiele wpisów hobbies do przesłania w tym samym formularzu.

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

Używając Get-Item na kluczu avatar, obiekt FileInfo jest ustawiany jako wartość. Wynikiem jest to, że dane obrazu dla jdoe.png są przesyłane.

Po podaniu listy do klucza hobbies, pole hobbies jest obecne w przesłanych danych tyle razy, ile jest elementów na liście.

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

Interfejsy API często wymagają podawanych nagłówków w celu uwierzytelniania lub weryfikacji. Przykład ten pokazuje, jak przekazać wiele nagłówków z hash-table 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

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

Aby wyliczyć obiekty do potoku, należy przekazać wyniki do Write-Output lub umieścić polecenie cmdlet w nawiasach. Poniższy przykład zlicza liczbę obiektów zwracanych przez usługę GitHub. Następnie zlicza liczbę obiektów przekazanych 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 polecenie cmdlet Invoke-RestMethod weryfikuje wartości dobrze znanych nagłówków, które mają format wartości zdefiniowany 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ą nieprawidłowe 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 punktowi końcowemu usługi /headers, który zwraca nagłówki żądania jako treść swojej odpowiedzi.

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

Wywołanie Invoke-RestMethod z nieprawidłowymi nagłówkami zwraca błąd informujący, że wartość sformatowana 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 zapytanie dotyczące problemu GitHub jest wykonywane 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. Cmdlet nawiązuje połączenie z demonem Dockera 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łasną odpowiedzialność, użyj parametru AllowInsecureRedirect.

Ten parametr został dodany w programie PowerShell 7.4.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 autentykacji z identyfikatorem URI , który nie zaczyna się od https://, powoduje wystąpienie błędu, a żądanie zostaje przerwane, aby zapobiec niezamierzonej komunikacji tajnych informacji w formie tekstu jawnego przez niezaszyfrowane połączenia. Aby zastąpić to zachowanie na własną odpowiedzialność, użyj parametru 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żywasz na własne ryzyko.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 nie podano uwierzytelniania. Nie jest używane jawne uwierzytelnianie.
• Basic: wymaga poświadczenia . Poświadczenia są używane do wysyłania nagłówka Authorization: Basic uwierzytelniania podstawowego RFC 7617 w formacie base64(user:password).
• Bearer: wymaga parametru tokenu. Wysyła nagłówek RFC 6750 Authorization: Bearer z podanym tokenem.
• OAuth: wymaga parametru tokenu. Wysyła nagłówek RFC 6750 Authorization: Bearer z podanym tokenem.

Podanie authentication zastępuje wszystkie nagłówki Authorization dostarczone do Headers lub dołączone do WebSession.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	WebAuthenticationType
Domyślna wartość:	None
Dopuszczalne wartości:	None, Basic, Bearer, OAuth
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Body

Określa treść żądania. Ciało to zawartość żądania, które następuje po nagłówkach. Możesz również przekazać wartość ciała do Invoke-RestMethod.

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

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

Gdy dane wejściowe są żądaniem GET, a treść to IDictionary (zazwyczaj tabela skrótów), jest ona dodawana do identyfikatora URI jako parametry zapytania. W przypadku innych typów żądań (takich jak PATCH) treść jest ustawiana jako zawartość ciała żądania w standardowym formacie name=value z wartościami zakodowanymi w formacie URL.

Gdy dane wejściowe są obiektem System.Xml.XmlNode, a deklaracja XML określa kodowanie, 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 wywołania Invoke-WebRequest, program PowerShell ustawia zawartość żądania na pola formularza.

Parametr Body może również przyjąć obiekt System.Net.Http.MultipartFormDataContent, co ułatwia wysyłanie żądań multipart/form-data. Gdy obiekt MultipartFormDataContent jest dostarczany dla Body, wszelkie nagłówki dotyczące zawartości, dostarczane przez ContentType, Headers, lub parametry WebSession, są zastępowane nagłówkami obiektu MultipartFormDataContent. Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	Object
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	True
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Certificate

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

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

Właściwości parametru

Typ:	X509Certificate
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 polecenia Get-Item lub Get-ChildItem, aby znaleźć certyfikat w Cert:\CurrentUser\My.

Uwaga / Notatka

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

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-ConnectionTimeoutSeconds

Określa, jak długo żądanie może być oczekiwane, zanim upłynie limit czasu. Wprowadź wartość w sekundach. Wartość domyślna 0 określa limit czasu nieokreślony.

Zapytanie systemu nazw domen (DNS) może trwać do 15 sekund, zanim zostanie zakończone lub zanim upłynie jego limit czasu. Jeśli twoje żądanie zawiera nazwę hosta, która wymaga rozpoznania, i ustawisz ConnectionTimeoutSeconds na wartość większą niż zero, ale mniejszą niż 15 sekund, może upłynąć 15 sekund lub więcej, zanim zostanie wywołany błąd WebException i twoje żądanie przekroczy limit czasu.

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

Właściwości parametru

Typ:	Int32
Domyślna wartość:	0
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	Limit czasowy

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-ContentType

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

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

Jeśli pominięto parametr, typ zawartości może być inny w zależności od używanej metody HTTP:

• W przypadku metody POST typ zawartości jest application/x-www-form-urlencoded
• W przypadku metody PUT typ zawartości to application/json
• W przypadku innych metod typ zawartości nie jest określony w żądaniu

Jeśli używasz parametru InFile do przekazania pliku, należy ustawić typ zawartości. Zazwyczaj typ powinien być application/octet-stream. Należy jednak ustawić typ zawartości na podstawie wymagań punktu końcowego.

ContentType jest zastępowany, gdy treść jest obiektem MultipartFormDataContent.

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.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Credential

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

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

Można użyć poświadczenia samodzielnie lub w połączeniu z niektórymi opcjami parametrów uwierzytelniania . Jeśli jest używany sam, dostarcza poświadczenia tylko do serwera zdalnego, gdy ten wysyła żądanie uwierzytelnienia. W przypadku użycia z opcjami uwierzytelniania , poświadczenia są przesyłane w sposób jawny.

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

Uwaga / Notatka

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

Właściwości parametru

Typ:	PSCredential
Domyślna wartość:	Current user
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-CustomMethod

Określa metodę niestandardową używaną dla żądania internetowego. To można użyć w przypadku, gdy metoda żądania wymagana przez punkt końcowy nie jest dostępna jako opcja w Method. Metoda i CustomMethod nie mogą być używane razem.

Przykład:

Invoke-RestMethod -Uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Powoduje to wysłanie żądania HTTP TEST do interfejsu API.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	CENTYMETR

Zestawy parametrów

CustomMethod

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CustomMethodNoProxy

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-DisableKeepAlive

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

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-FollowRelLink

Wskazuje, że polecenie cmdlet powinno śledzić powiązania relacyjne.

Niektóre interfejsy API REST obsługują stronicowanie za pośrednictwem Linków Relacyjnych zgodnie z RFC5988. Zamiast analizować nagłówek w celu uzyskania adresu URL do następnej strony, możesz pozwolić, aby cmdlet zrobił to za Ciebie. Aby ustawić, ile razy należy użyć linków relacyjnych, użyj parametru MaximumFollowRelLink.

Korzystając z tego przełącznika, polecenie cmdlet zwraca kolekcję stron z wynikami. Każda strona wyników może zawierać wiele elementów wyników.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	FL

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Form

Konwertuje słownik na zgłoszenie typu multipart/form-data. formularz nie może być używany z treścią. ContentType jest ignorowany.

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

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

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

Jeśli wartość jest typem kolekcji, takim jak Tablica lub Lista, pole formularza jest przesyłane wiele razy. Wartości listy są domyślnie traktowane jako ciągi. Jeśli wartość jest obiektem System.IO.FileInfo, zawartość pliku binarnego jest przesył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 pole tags jest dostarczane trzy razy w formularzu, raz dla każdej z wartości: Vacation, Italyi 2017. Pole pictures jest przesyłane raz dla każdego pliku w folderze 2017-Italy. Zawartość binarna plików w tym folderze jest przesyłana jako wartości.

Ta funkcja została dodana w programie PowerShell 6.1.0.

Właściwości parametru

Typ:	IDictionary
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Headers

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

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

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

Właściwości parametru

Typ:	IDictionary
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-HttpVersion

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

Prawidłowe wartości to:

• 1.0
• 1.1
• 2.0
• 3.0

Właściwości parametru

Typ:	Version
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-InFile

Pobiera zawartość treści żądania internetowego z pliku. Wprowadź ścieżkę i nazwę pliku. Jeśli pominięto ścieżkę, wartość domyślna to bieżąca lokalizacja.

Należy również ustawić typ zawartości żądania. Aby na przykład przekazać plik, należy ustawić typ zawartości. Zazwyczaj typ powinien być application/octet-stream. Należy jednak ustawić typ zawartości na podstawie wymagań punktu końcowego.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-MaximumFollowRelLink

Określa, ile razy należy śledzić linki powiązań, jeśli jest używana opcja FollowRelLink. W przypadku ograniczenia przepustowości interfejsu API REST z powodu zbyt wielu żądań, może być wymagana mniejsza wartość. Wartość domyślna to [int32]::MaxValue. Wartość 0 (zero) uniemożliwia korzystanie z poniższych linków relacyjnych.

Właściwości parametru

Typ:	Int32
Domyślna wartość:	Int32.MaxValue
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	ML

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-MaximumRedirection

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

Właściwości parametru

Typ:	Int32
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 w celu określenia interwału między ponownymi próbami.

Właściwości parametru

Typ:	Int32
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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żna użyć dla metod żądań, których nie wymieniono powyżej.

Właściwości parametru

Typ:	WebRequestMethod
Domyślna wartość:	None
Dopuszczalne wartości:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

StandardMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

StandardMethodNoProxy

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-NoProxy

Wskazuje, że polecenie cmdlet nie będzie używać serwera proxy do dotarcia do miejsca docelowego. Użyj tego polecenia, aby pominąć serwer proxy skonfigurowany w ustawieniach internetu lub określony w środowisku.

Ten parametr został wprowadzony w programie PowerShell 6.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

StandardMethodNoProxy

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CustomMethodNoProxy

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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.

Właściwości parametru

Typ:	Int32
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-OutFile

Domyślnie Invoke-RestMethod zwraca wyniki do potoku. Jeśli 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 dosłowna ścieżka. Nazwy zawierające nawiasy ([]) muszą być ujęte w pojedyncze cudzysłowy (').

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 OutFilenie można użyć parametru Resume.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-PassThru

Ten parametr jest prawidłowy tylko wtedy, gdy parametr OutFile jest również używany w poleceniu . Zamierzamy zapisać wyniki do pliku i do potoku danych.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	No output
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-PreserveAuthorizationOnRedirect

Wskazuje, że polecenie cmdlet powinno zachować nagłówek Authorization, jeśli jest obecny, podczas przekierowań.

Domyślnie polecenie cmdlet usuwa nagłówek Authorization 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.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-PreserveHttpMethodOnRedirect

Wskazuje, że polecenie cmdlet powinno zachować metodę żądania dla wszystkich przekierowań.

Domyślnie polecenie cmdlet zmienia metodę na GET w wyniku przekierowania. 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.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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.

Właściwości parametru

Typ:	Uri
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

StandardMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CustomMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-ProxyCredential

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

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

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.

Właściwości parametru

Typ:	PSCredential
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

StandardMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CustomMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-ProxyUseDefaultCredentials

Używa poświadczeń bieżącego użytkownika, aby uzyskać dostęp 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.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

StandardMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CustomMethod

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 zwracane przez serwer internetowy.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	RHV

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Resume

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

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

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

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

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

Jeśli serwer zdalny nie obsługuje wznawiania pobierania, plik lokalny zostanie zastąpiony i cały plik zdalny zostanie ponownie pobrany. To zachowanie jest takie samo jak użycie OutFile bez Resume.

Jeśli plik lokalny nie istnieje, zostanie utworzony plik lokalny i zostanie pobrany cały plik zdalny. To zachowanie jest takie samo jak użycie OutFile bez Resume.

Ta funkcja została dodana w programie PowerShell 6.1.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 a [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.

Właściwości parametru

Typ:	Int32
Domyślna wartość:	5
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-SessionVariable

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

Po określeniu zmiennej sesji Invoke-RestMethod 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. Możesz używać tego do udostępniania stanu i danych między żądaniami HTTP.

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. Kiedy tak się dzieje, 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 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.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	SV

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 jest przeznaczony do użycia tylko na znanych hostach z samopodpisanym certyfikatem do celów testowych. Używasz na własne ryzyko.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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.

Ten przełącznik wyłącza sprawdzanie poprawności wartości przekazywanych do parametrów ContentType, nagłówkóworaz UserAgent.

Ta funkcja została dodana w programie PowerShell 6.0.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-SkipHttpErrorCheck

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

Ten parametr został wprowadzony w programie PowerShell 7.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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. 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 tablicy wartości lub jako ciąg rozdzielany przecinkami tych wartości. Polecenie cmdlet łączy wartości przy użyciu operacji binary-OR. Przekazywanie wartości jako tablicy jest najprostszą opcją i umożliwia skorzystanie z funkcji automatycznego uzupełniania dla wartości tablicy. Może nie być możliwe podanie wielu wartości na wszystkich platformach.

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

Właściwości parametru

Typ:	WebSslProtocol
Domyślna wartość:	None
Dopuszczalne wartości:	Default, Tls, Tls11, Tls12, Tls13
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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, który zawiera ten 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.

Właściwości parametru

Typ:	SecureString
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-TransferEncoding

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

• Podzielone na kawałki
• Kompresować
• Deflate
• GZip
• Tożsamość

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Dopuszczalne wartości:	chunked, compress, deflate, gzip, identity
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 na blogu "Windows/WSL Interop with AF_UNIX" ( Międzyoperacyjność Windows/WSL z AF_UNIX).

Ten parametr został dodany w programie PowerShell 7.4.

Właściwości parametru

Typ:	UnixDomainSocketEndPoint
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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.

Właściwości parametru

Typ:	Uri
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	0
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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. Gdy jest używany, nie ma wpływu na działanie polecenia cmdlet.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-UseDefaultCredentials

Wskazuje, że polecenie cmdlet używa poświadczeń bieżącego użytkownika do wysłania żądania sieciowego. Nie można tego używać z Authentication lub Credential i może nie być obsługiwane na wszystkich platformach.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	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 z niewielkimi odmianami 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.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-WebSession

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

Aby zastąpić wartość w sesji żądania internetowego, użyj parametru cmdlet, takiego jak UserAgent lub Credential. Wartości parametrów mają pierwszeństwo przed wartościami w sesji żądania internetowego. Nagłówki powiązane z zawartością, takie jak Content-Type, są zastępowane, 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. Możesz używać tego do udostępniania stanu i danych między żądaniami HTTP.

Aby utworzyć sesję żądania internetowego, wprowadź nazwę zmiennej bez znaku dolara jako wartość parametru SessionVariable w poleceniu Invoke-RestMethod. 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.

Właściwości parametru

Typ:	WebRequestSession
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

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

PSObject

Gdy żądanie zwraca ciągi JSON, to polecenie cmdlet zwraca psObject reprezentujące dane.

Uwagi

Program PowerShell zawiera następujące aliasy dla 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 różni się w zależności od platformy:

• dla systemu Windows: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych lub, jeśli nie są one zdefiniowane, z ustawień serwera proxy użytkownika.
• Dla systemu macOS: odczytuje konfigurację serwera proxy ze zmiennych środowiskowych lub, jeśli nie są one zdefiniowane, z ustawień serwera proxy systemu.
• Dla 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 inicjowania DefaultProxy na platformach opartych na systemach Windows i Unix są następujące:

• HTTP_PROXY: nazwa hosta lub adres IP serwera proxy używanego na żądaniach HTTP.
• HTTPS_PROXY: nazwa hosta lub adres IP serwera proxy używanego w żądaniach HTTPS.
• ALL_PROXY: nazwa hosta lub adres IP serwera proxy używanego w żądaniach HTTP i HTTPS w przypadku, gdy 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.

Linki powiązane

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest