Invoke-RestMethod

Odwołanie

Moduł:: Microsoft.PowerShell.Utility

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

Składnia

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [<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.

Uwaga

Domyślnie kod skryptu na stronie internetowej może być uruchamiany, gdy strona jest analizowana w celu wypełnienia ParsedHtml właściwości. Użyj przełącznika UseBasicParsing , aby pominąć tę opcję.

Przykłady

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

Invoke-RestMethod -Uri https://devblogs.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

To polecenie używa 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.

Przykład 2

W poniższym przykładzie użytkownik uruchamia Invoke-RestMethod polecenie , aby wykonać żądanie POST w witrynie internetowej intranetowej w organizacji użytkownika.

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as
# the output mode, and specifies a time period for returned data that starts two days ago and ends
# one day ago. The body variable specifies values for parameters that apply to the particular REST
# API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file
# name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

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

W tym przykładzie pokazano, jak przekazać wiele nagłówków z hash-table interfejsu API REST do interfejsu API REST.

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

Interfejsy API często wymagają przekazanych nagłówków na potrzeby uwierzytelniania, walidacji itp.

Przykład 3. Przesyłanie danych formularza

Gdy treść jest formularzem lub jest to dane wyjściowe innego Invoke-WebRequest wywołania, program PowerShell ustawia zawartość żądania na pola formularza.

Na przykład:

$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

Przykład 4. 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

Parametry

-Body

Określa treść żądania. Treść jest zawartością żądania, która jest zgodna z nagłówkami. Możesz również przekazać wartość treści do Invoke-RestMethod.

Parametr Treść może służyć do określenia listy parametrów zapytania lub określenia zawartości odpowiedzi.

Gdy dane wejściowe są żądaniem GET, a treść jest IDictionary (zazwyczaj tabelą skrótów), treść jest dodawana do identyfikatora URI jako parametrów zapytania. W przypadku innych typów żądań (takich jak POST) treść jest ustawiana jako wartość treści żądania w standardowym formacie name=value.

Ostrzeżenie

Pełne dane wyjściowe treści POST zakończą się ciągiem with -1-byte payload, mimo że rozmiar treści jest znany i wysyłany w nagłówku Content-Length HTTP.

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

-Certificate

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

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

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

-CertificateThumbprint

Określa cyfrowy certyfikat klucza publicznego (X509) konta użytkownika z uprawnieniami do wysyłania żądania. Wprowadź odcisk palca certyfikatu.

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.

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

-ContentType

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

Jeśli ten parametr zostanie pominięty, a metoda żądania to POST, Invoke-RestMethod ustawia typ zawartości na "application/x-www-form-urlencoded". W przeciwnym razie typ zawartości nie jest określony w wywołaniu.

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

-Credential

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

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

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

Uwaga

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

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableKeepAlive

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

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

-Headers

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

Aby ustawić nagłówki UserAgent, użyj parametru UserAgent . Nie można użyć tego parametru do określenia nagłówków UserAgent lub cookie.

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

-InFile

Pobiera zawartość żądania internetowego z pliku.

Wprowadź ścieżkę i nazwę pliku. Jeśli pominięto ścieżkę, wartość domyślna to bieżąca lokalizacja.

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

-MaximumRedirection

Określa, ile razy program Windows 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.

Type:	Int32
Position:	Named
Default value:	5
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	Default
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutFile

Zapisuje treść odpowiedzi w określonym pliku wyjściowym. Wprowadź ścieżkę i nazwę pliku. Jeśli pominięto ścieżkę, wartość domyślna to bieżąca lokalizacja.

Domyślnie Invoke-RestMethod zwraca wyniki do potoku.

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

-PassThru

Ten parametr jest prawidłowy tylko wtedy, gdy parametr OutFile jest również używany w poleceniu. Intencją jest zapisanie wyników w pliku i potoku.

Uwaga

Gdy używasz parametru PassThru , dane wyjściowe są zapisywane w potoku, ale plik jest pusty. Aby uzyskać więcej informacji, zobacz Problem z programem PowerShell #15409.

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

-Proxy

Używa serwera proxy dla żądania zamiast łączyć się bezpośrednio z zasobem internetowym. Wprowadź identyfikator URI serwera proxy sieci.

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

-ProxyCredential

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

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

Ten parametr jest prawidłowy tylko wtedy, gdy parametr serwera proxy jest również używany w poleceniu . W tym samym poleceniu nie można użyć parametrów ProxyCredential i ProxyUseDefaultCredentials .

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyUseDefaultCredentials

Używa poświadczeń bieżącego użytkownika, aby uzyskać dostęp do serwera proxy określonego przez parametr proxy .

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

-SessionVariable

Tworzy zmienną zawierającą sesję żądania internetowego. Wprowadź nazwę zmiennej bez 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.

W przeciwieństwie do sesji zdalnej sesja żądania sieci Web nie jest trwałym połączeniem. Jest to obiekt, który zawiera informacje o połączeniu i żądaniu, w tym pliki cookie, poświadczenia, maksymalną wartość przekierowania i parametry agenta użytkownika. Służy do udostępniania stanu i danych między żądaniami internetowymi.

Aby użyć sesji żądania sieci Web w kolejnych żądaniach sieci Web, określ zmienną sesji w wartości parametru WebSession . Program PowerShell używa danych w obiekcie sesji żądania internetowego podczas nawiązywania nowego połączenia. Aby zastąpić wartość w sesji żądania internetowego, użyj parametru polecenia cmdlet, takiego jak UserAgent lub Credential. Wartości parametrów mają pierwszeństwo przed wartościami w sesji żądania internetowego.

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

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

-TimeoutSec

Określa, jak długo żądanie może być oczekujące przed upływem limitu czasu. Wprowadź wartość w sekundach. Wartość domyślna 0 określa limit czasu nieokreślony.

Zapytanie systemu nazw domen (DNS) może potrwać do 15 sekund, aby zwrócić lub upłynął limit czasu. Jeśli żądanie zawiera nazwę hosta, która wymaga rozwiązania, i ustawisz wartość TimeoutSec na wartość większą niż zero, ale mniej niż 15 sekund, może upłynąć 15 sekund lub więcej, zanim zostanie zgłoszony wyjątek WebException i przekroczono limit czasu żądania.

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

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

Określa identyfikator URI (Uniform Resource Identifier) zasobu internetowego, do którego jest wysyłane żądanie internetowe. Ten parametr obsługuje wartości HTTP, HTTPS, FTP i FILE.

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

Type:	Uri
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UseBasicParsing

Wskazuje, że polecenie cmdlet używa podstawowego analizowania. Polecenie cmdlet zwraca nieprzetworzone kod HTML w obiekcie String .

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

-UseDefaultCredentials

Używa poświadczeń bieżącego użytkownika do wysłania żądania internetowego.

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

-UserAgent

Określa ciąg agenta użytkownika dla żądania internetowego.

Domyślny agent użytkownika jest podobny do "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.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, Internet Explorer, Opera i Safari.

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

-WebSession

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

Aby zastąpić wartość w sesji żądania internetowego, użyj parametru polecenia cmdlet, takiego jak UserAgent lub Credential. Wartości parametrów mają pierwszeństwo przed wartościami w sesji żądania internetowego.

Aby utworzyć sesję żądania internetowego, wprowadź nazwę zmiennej (bez znaku dolara) w wartości parametru Invoke-RestMethod SessionVariable polecenia. Invoke-RestMethod tworzy sesję i zapisuje ją w zmiennej. W kolejnych poleceniach użyj zmiennej jako wartości parametru WebSession .

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

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

Dane wejściowe

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 Windows PowerShell zawiera następujące aliasy dla programu Invoke-RestMethod:

irm

Invoke-RestMethod

Składnia

Opis

Przykłady

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

Przykład 2

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

Przykład 3. Przesyłanie danych formularza

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

Parametry

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Dane wejściowe

Dane wyjściowe

Uwagi

Opinia

Dodatkowe zasoby

Invoke-RestMethod

Składnia

Opis

Przykłady

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

Przykład 2

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

Przykład 3. Przesyłanie danych formularza

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

Parametry

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Dane wejściowe

Dane wyjściowe

Uwagi

Linki powiązane

Opinia

Dodatkowe zasoby