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 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 Windows PowerShell formatuje odpowiedź na podstawie typu danych. W przypadku kanału informacyjnego RSS lub ATOM program Windows PowerShell zwraca węzły Item lub Entry XML. W przypadku notacji obiektów JavaScript (JSON) lub XML program Windows PowerShell konwertuje (lub deserializuje) zawartość na obiekty.

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

Nuta

Domyślnie kod skryptu na stronie internetowej może być uruchamiany, gdy strona jest analizowana w celu wypełnienia właściwości ParsedHtml. Aby pominąć ten element, użyj przełącznika -UseBasicParsing.

Przykłady

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

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

To polecenie używa polecenia cmdlet Invoke-RestMethod, aby uzyskać informacje z kanału informacyjnego RSS bloga programu PowerShell. Polecenie używa polecenia cmdlet Format-Table do wyświetlania wartości Title i pubDate właściwości każdego bloga w tabeli.

Przykład 2

W poniższym przykładzie użytkownik uruchamia Invoke-RestMethod, aby wykonać żądanie POST w intranetowej witrynie internetowej 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

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

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

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 -Body 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ę with -1-byte payload, mimo że rozmiar treści jest znany i wysyłany w nagłówku http Content-Length.

Gdy treść jest formularzem lub jest to dane wyjściowe innego wywołania Invoke-WebRequest, program Windows 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]

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 lub użyj polecenia cmdlet Get-ChildItem na dysku Certificate (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. Mogą być mapowane tylko na konta użytkowników lokalnych; nie działają z kontami domeny.

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

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

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

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

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	KeepAlive
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.

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.

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

-MaximumRedirection

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

Typ:	Int32
Position:	Named
Domyślna wartość:	5
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:

Domyślny
Usunąć
Pobierz
Głowa
Połączyć
Opcje
Łata
Post
Kłaść
Ślad

Typ:	WebRequestMethod
Dopuszczalne wartości:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Domyślna wartość:	Default
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	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. Aby wysłać wyniki do pliku i do potoku, użyj parametru -Passthru.

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

-PassThru

Zwraca wyniki oprócz zapisywania ich w pliku. Ten parametr jest prawidłowy tylko wtedy, gdy parametr -OutFile jest również używany w poleceniu .

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	No output
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 serwera proxy sieci.

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 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 -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ść:	Current user
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-ProxyUseDefaultCredentials

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ść:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-SessionVariable

Tworzy sesję żądania internetowego i zapisuje ją w wartości określonej zmiennej. Wprowadź nazwę zmiennej bez znaku dolara ($) symbolu.

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 Windows 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 Windows PowerShell używa danych w obiekcie sesji żądania sieci Web 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

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

Typ:	Int32
Position:	Named
Domyślna wartość:	0
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

-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

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

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

-UseDefaultCredentials

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

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	None
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; 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, takiej jak Chrome, FireFox, Internet Explorer, Opera i Safari.

Na przykład następujące polecenie używa ciągu agenta użytkownika dla Internetu

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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.

Aby utworzyć sesję żądania internetowego, wprowadź nazwę zmiennej (bez znaku dolara) w wartości parametru -SessionVariable polecenia 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.

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

Dane wejściowe

Object

Treść żądania internetowego można przekazać potokiem, aby Invoke-RestMethod.

Dane wyjściowe

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

Dane wyjściowe polecenia cmdlet zależą od formatu pobranej zawartości.

PSObject

Jeśli żądanie zwraca ciągi JSON, Invoke-RestMethod zwraca obiekt PSObject reprezentujący ciągi.

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

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

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

Dodatkowe zasoby

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

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

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

Linki powiązane

Dodatkowe zasoby