Invoke-RestMethod

Referens

Modul:: Microsoft.PowerShell.Utility

Skickar en HTTP- eller HTTPS-begäran till en RESTful-webbtjänst.

Syntax

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

Description

Cmdleten Invoke-RestMethod skickar HTTP- och HTTPS-begäranden till REST-webbtjänster (Representational State Transfer) som returnerar mycket strukturerade data.

Windows PowerShell formaterar svaret baserat på datatypen. För en RSS- eller ATOM-feed returnerar Windows PowerShell objekt- eller post-XML-noderna. För JavaScript Object Notation (JSON) eller XML konverterar Windows PowerShell (eller deserialiserar) innehållet till objekt.

Den här cmdleten introduceras i Windows PowerShell 3.0.

Not

Som standard kan skriptkod på webbsidan köras när sidan parsas för att fylla i egenskapen ParsedHtml. Använd växeln -UseBasicParsing för att förhindra detta.

Exempel

Exempel 1: Hämta PowerShell RSS-feeden

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

Det här kommandot använder cmdleten Invoke-RestMethod för att hämta information från POWERShell-bloggens RSS-feed. Kommandot använder cmdleten Format-Table för att visa värdena för Title och pubDate egenskaper för varje blogg i en tabell.

Exempel 2

I följande exempel kör en användare Invoke-RestMethod för att utföra en POST-begäran på en intranätwebbplats i användarens organisation.

$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"}}

Exempel 3: Skicka flera rubriker

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

API:er kräver ofta skickade huvuden för autentisering, validering osv.

Det här exemplet visar hur du skickar flera huvuden från en hash-table till ett REST-API.

Parametrar

-Body

Anger brödtexten i begäran. Brödtexten är innehållet i begäran som följer rubrikerna. Du kan också skicka ett brödtextvärde till Invoke-RestMethod.

Parametern -Body kan användas för att ange en lista med frågeparametrar eller ange innehållet i svaret.

När indata är en GET-begäran och brödtexten är en IDictionary (vanligtvis en hash-tabell) läggs brödtexten till i URI:n som frågeparametrar. För andra typer av begäranden (till exempel POST) anges brödtexten som värdet för begärandetexten i standardformatet name=value.

Warning: De utförliga utdata från en POST-brödtext slutar med with -1-byte payload, även om brödtextens storlek både är känd och skickad i Content-Length HTTP-huvud.

När brödtexten är ett formulär, eller om det är utdata från ett annat Invoke-WebRequest-anrop, anger Windows PowerShell begärandeinnehållet till formulärfälten.

Till exempel:

$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
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	True
Godkänn jokertecken:	False

-Certificate

Anger det klientcertifikat som används för en säker webbbegäran. Ange en variabel som innehåller ett certifikat eller ett kommando eller uttryck som hämtar certifikatet.

Om du vill hitta ett certifikat använder du Get-PfxCertificate eller använder Get-ChildItem-cmdleten på enheten Certifikat (Cert:). Om certifikatet inte är giltigt eller inte har tillräcklig behörighet misslyckas kommandot.

Typ:	X509Certificate
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-CertificateThumbprint

Anger det digitala offentliga nyckelcertifikatet (X509) för ett användarkonto som har behörighet att skicka begäran. Ange certifikatets tumavtryck.

Certifikat används i klientcertifikatbaserad autentisering. De kan endast mappas till lokala användarkonton. de fungerar inte med domänkonton.

Om du vill hämta ett tumavtryck för certifikat använder du kommandot Get-Item eller Get-ChildItem i Windows PowerShell-enheten (Cert:).

Typ:	String
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-ContentType

Anger innehållstypen för webbbegäran.

Om den här parametern utelämnas och begärandemetoden är POST anger Invoke-RestMethod innehållstypen till "application/x-www-form-urlencoded". Annars anges inte innehållstypen i anropet.

Typ:	String
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-Credential

Anger ett användarkonto som har behörighet att skicka begäran. Standardvärdet är den aktuella användaren.

Ange ett användarnamn, till exempel "User01" eller "Domain01\User01", eller ange ett PSCredential- objekt, till exempel ett som genereras av Get-Credential cmdlet.

Typ:	PSCredential
Position:	Named
Standardvärde:	Current user
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-DisableKeepAlive

Anger värdet KeepAlive i HTTP-huvudet till False. Som standard är KeepAlive- Sant. KeepAlive upprättar en beständig anslutning till servern för att underlätta efterföljande begäranden.

Typ:	SwitchParameter
Position:	Named
Standardvärde:	KeepAlive
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-Headers

Anger sidhuvudena för webbbegäran. Ange en hash-tabell eller ordlista.

Om du vill ange UserAgent-huvuden använder du parametern -UserAgent. Du kan inte använda den här parametern för att ange UserAgent- eller cookierubriker.

Typ:	IDictionary
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-InFile

Hämtar innehållet i webbbegäran från en fil.

Ange en sökväg och ett filnamn. Om du utelämnar sökvägen är standardinställningen den aktuella platsen.

Typ:	String
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-MaximumRedirection

Avgör hur många gånger Windows PowerShell omdirigerar en anslutning till en alternativ URI (Uniform Resource Identifier) innan anslutningen misslyckas. Standardvärdet är 5. Värdet 0 (noll) förhindrar all omdirigering.

Typ:	Int32
Position:	Named
Standardvärde:	5
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-Method

Anger den metod som används för webbbegäran. De godtagbara värdena för den här parametern är:

Standard
Ta bort
Få
Huvud
Slå ihop
Alternativ
Lapp
Post
Ställa
Spåra

Typ:	WebRequestMethod
Godkända värden:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Standardvärde:	Default
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-OutFile

Sparar svarstexten i den angivna utdatafilen. Ange en sökväg och ett filnamn. Om du utelämnar sökvägen är standardinställningen den aktuella platsen.

Som standard returnerar Invoke-RestMethod resultatet till pipelinen. Om du vill skicka resultatet till en fil och till pipelinen använder du parametern -Passthru.

Typ:	String
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-PassThru

Returnerar resultatet, förutom att skriva dem till en fil. Den här parametern är endast giltig när parametern -OutFile också används i kommandot .

Typ:	SwitchParameter
Position:	Named
Standardvärde:	No output
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-Proxy

Använder en proxyserver för begäran i stället för att ansluta direkt till Internetresursen. Ange URI för en nätverksproxyserver.

Typ:	Uri
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-ProxyCredential

Anger ett användarkonto som har behörighet att använda proxyservern som anges av parametern -Proxy. Standardvärdet är den aktuella användaren.

Ange ett användarnamn, till exempel "User01" eller "Domain01\User01", eller ange ett PSCredential- objekt, till exempel ett som genereras av Get-Credential cmdlet.

Den här parametern är endast giltig när parametern -Proxy också används i kommandot . Du kan inte använda parametrarna -ProxyCredential och -ProxyUseDefaultCredentials i samma kommando.

Typ:	PSCredential
Position:	Named
Standardvärde:	Current user
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-ProxyUseDefaultCredentials

Använder den aktuella användarens autentiseringsuppgifter för att komma åt proxyservern som anges av parametern -Proxy.

Den här parametern är endast giltig när parametern -Proxy också används i kommandot . Du kan inte använda parametrarna -ProxyCredential och -ProxyUseDefaultCredentials i samma kommando.

Typ:	SwitchParameter
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-SessionVariable

Skapar en webbbegärandesession och sparar den i värdet för den angivna variabeln. Ange ett variabelnamn utan symbolen dollartecken ($).

När du anger en sessionsvariabel skapar Invoke-RestMethod ett sessionsobjekt för webbbegäran och tilldelar det till en variabel med det angivna namnet i Windows PowerShell-sessionen. Du kan använda variabeln i sessionen så snart kommandot har slutförts.

Till skillnad från en fjärrsession är webbbegärandesessionen inte en beständig anslutning. Det är ett objekt som innehåller information om anslutningen och begäran, inklusive cookies, autentiseringsuppgifter, maximalt omdirigeringsvärde och användaragentsträngen. Du kan använda den för att dela tillstånd och data mellan webbbegäranden.

Om du vill använda webbbegärandesessionen i efterföljande webbbegäranden anger du sessionsvariabeln i värdet för parametern -WebSession. Windows PowerShell använder data i sessionsobjektet för webbbegäran när den nya anslutningen upprättas. Om du vill åsidosätta ett värde i webbförfrågningssessionen använder du en cmdlet-parameter, till exempel -UserAgent eller -Credential. Parametervärden har företräde framför värden i webbbegärandesessionen.

Du kan inte använda parametrarna -SessionVariable och -WebSession i samma kommando.

Typ:	String
Alias:	SV
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-TimeoutSec

Anger hur länge begäran kan vänta innan tidsgränsen uppnås. Ange ett värde i sekunder. Standardvärdet 0 anger en tidsgräns på obestämd tid.

En DNS-fråga (Domain Name System) kan ta upp till 15 sekunder att returnera eller överskrida tidsgränsen. Om din begäran innehåller ett värdnamn som kräver lösning och du anger TimeoutSec till ett värde som är större än noll, men mindre än 15 sekunder, kan det ta 15 sekunder eller mer innan en WebException utlöses och din begäran överskrider tidsgränsen.

Typ:	Int32
Position:	Named
Standardvärde:	0
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-TransferEncoding

Anger ett värde för http-svarshuvudet för överföringskodning. De godtagbara värdena för den här parametern är:

Chunked
Komprimera
Tömma
GZip
Identitet

Typ:	String
Godkända värden:	chunked, compress, deflate, gzip, identity
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-Uri

Anger URI (Uniform Resource Identifier) för den Internetresurs som webbbegäran skickas till. Den här parametern stöder HTTP-, HTTPS-, FTP- och FILE-värden.

Den här parametern krävs. Parameternamnet (-Uri) är valfritt.

Typ:	Uri
Position:	0
Standardvärde:	None
Obligatorisk:	True
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-UseBasicParsing

Anger att cmdleten använder grundläggande parsning. Cmdleten returnerar den råa HTML-koden i ett String-objekt.

Typ:	SwitchParameter
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-UseDefaultCredentials

Använder den aktuella användarens autentiseringsuppgifter för att skicka webbbegäran.

Typ:	SwitchParameter
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-UserAgent

Anger en användaragentsträng för webbbegäran.

Standardanvändaragenten liknar "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" med små variationer för varje operativsystem och plattform.

Om du vill testa en webbplats med standardanvändaragentsträngen som används av de flesta webbläsare använder du egenskaperna för PSUserAgent-klass, till exempel Chrome, FireFox, Internet Explorer, Opera och Safari.

Följande kommando använder till exempel användaragentsträngen för Internet

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

Typ:	String
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

-WebSession

Anger en webbförfrågningssession. Ange variabelnamnet, inklusive dollartecknet ($).

Om du vill åsidosätta ett värde i webbförfrågningssessionen använder du en cmdlet-parameter, till exempel -UserAgent eller -Credential. Parametervärden har företräde framför värden i webbbegärandesessionen.

Om du vill skapa en webbförfrågningssession anger du ett variabelnamn (utan dollartecken) i värdet för parametern -SessionVariable för ett Invoke-RestMethod kommando. Invoke-RestMethod skapar sessionen och sparar den i variabeln. I efterföljande kommandon använder du variabeln som värdet för parametern -WebSession.

Du kan inte använda parametrarna -SessionVariable och -WebSession i samma kommando.

Typ:	WebRequestSession
Position:	Named
Standardvärde:	None
Obligatorisk:	False
Godkänn pipeline-indata:	False
Godkänn jokertecken:	False

Indata

Object

Du kan skicka brödtexten i en webbbegäran till Invoke-RestMethod.

Utdata

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

Cmdletens utdata beror på formatet på innehållet som hämtas.

PSObject

Om begäran returnerar JSON-strängar returnerar Invoke-RestMethod en PSObject som representerar strängarna.

Dela via

Invoke-RestMethod

Syntax

Description

Exempel

Exempel 1: Hämta PowerShell RSS-feeden

Exempel 2

Exempel 3: Skicka flera rubriker

Parametrar

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Indata

Utdata

Ytterligare resurser

Dela via

Invoke-RestMethod

Syntax

Description

Exempel

Exempel 1: Hämta PowerShell RSS-feeden

Exempel 2

Exempel 3: Skicka flera rubriker

Parametrar

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Indata

Utdata

Relaterade länkar

Ytterligare resurser