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 internetowych Representational State Transfer (REST), które zwracają bogato ustrukturyzowane dane.

Windows PowerShell formatuje odpowiedź na podstawie typu danych. W przypadku kanału informacyjnego RSS lub ATOM Windows PowerShell zwraca węzły Item lub Entry XML. W przypadku formatu JavaScript Object Notation (JSON) lub XML Windows PowerShell konwertuje (lub deserializuje) zawartość na obiekty.

To polecenie cmdlet zostało wprowadzone w 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ąć ten element.

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 Invoke-RestMethod polecenia cmdlet do pobierania informacji 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

$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 interfejsu hash-table API REST 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-RestMethodmetody .

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

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

Przykład:

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

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

-Certificate

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

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

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

-CertificateThumbprint

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

Certyfikaty są używane w uwierzytelnianiu opartym na certyfikatach klienta. Mogą być mapowane tylko na konta użytkowników lokalnych; nie działają z kontami domeny.

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

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 , taki jak wygenerowany przez Get-Credential polecenie cmdlet.

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ótów 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ścią domyślną jest 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 Windows PowerShell przekierowuje połączenie do alternatywnego identyfikatora URI (Uniform Resource Identifier) przed niepowodzeniem połączenia. Wartość domyślna to 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 dla tego parametru to:

  • Domyślny
  • Usuń
  • Get
  • Head
  • Merge
  • Opcje
  • Patch
  • Wpis
  • Put
  • Ślad
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ścią domyślną jest bieżąca lokalizacja.

Domyślnie Invoke-RestMethod zwraca wyniki do potoku. Aby wysłać wyniki do pliku i do potoku, użyj parametru -Passthru .

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

-PassThru

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

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 -Proxy przez parametr . Wartość domyślna to użytkownik bieżący.

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

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

Type:PSCredential
Position:Named
Default value: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 -Proxy przez parametr .

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

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

-SessionVariable

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

Po określeniu zmiennej Invoke-RestMethod sesji program tworzy obiekt sesji żądania internetowego i przypisuje go do zmiennej o określonej nazwie w sesji Windows PowerShell. Możesz użyć zmiennej w sesji zaraz po zakończeniu wykonywania polecenia.

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

Zwrócenie lub przekroczenie limitu czasu zapytania systemu nazw domen (DNS) może potrwać do 15 sekund. Jeśli żądanie zawiera nazwę hosta, która wymaga rozwiązania, a właściwość TimeoutSec zostanie ustawiona 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 upłynął 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 dla tego parametru to:

  • Fragmentaryczne
  • Kompresji
  • Deflate
  • Gzip
  • Tożsamość
Type:String
Accepted values:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Uri

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

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

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

-UseBasicParsing

Wskazuje, że polecenie cmdlet używa podstawowego analizowania. Polecenie cmdlet zwraca nieprzetworzonego kodu 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.

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)

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.

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

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

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

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

Dane wejściowe

Object

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

Dane wyjściowe

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

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

PSObject

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