Invoke-RestMethod
Sendet eine HTTP- oder HTTPS-Anforderung an einen RESTful-Webdienst.
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>]
Beschreibung
Das Invoke-RestMethod
Cmdlet sendet HTTP- und HTTPS-Anforderungen an Rest-Webdienste (Representational State Transfer), die umfangreiche strukturierte Daten zurückgeben.
PowerShell formatiert die Antwort basierend auf dem Datentyp. Bei einem RSS- oder ATOM-Feed gibt PowerShell die Element- oder Eintrags-XML-Knoten zurück. Bei JavaScript Object Notation (JSON) oder XML konvertiert PowerShell den Inhalt [PSCustomObject]
in Objekte oder deserialisiert.
Hinweis
Wenn der REST-Endpunkt mehrere Objekte zurückgibt, werden die Objekte als Array empfangen. Wenn Sie die Ausgabe an Invoke-RestMethod
einen anderen Befehl senden, wird sie als einzelnes [Object[]]
Objekt gesendet. Der Inhalt dieses Arrays wird für den nächsten Befehl in der Pipeline nicht aufgezählt.
Dieses Cmdlet wird in Windows PowerShell 3.0 eingeführt.
Hinweis
Standardmäßig kann Skriptcode auf der Webseite ausgeführt werden, wenn die Seite analysiert wird, um die ParsedHtml
Eigenschaft aufzufüllen. Verwenden Sie den UseBasicParsing-Schalter , um dies zu unterdrücken.
Beispiele
Beispiel 1: Abrufen des PowerShell-RSS-Feeds
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
Dieser Befehl verwendet das Invoke-RestMethod
Cmdlet, um Informationen aus dem RSS-Feed des PowerShell-Blogs abzurufen. Der Befehl verwendet das Format-Table
Cmdlet, um die Werte der Title- und pubDate-Eigenschaften jedes Blogs in einer Tabelle anzuzeigen.
Beispiel 2
Im folgenden Beispiel wird ein Benutzer ausgeführt Invoke-RestMethod
, um eine POST-Anforderung auf einer Intranetwebsite in der Organisation des Benutzers auszuführen.
$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"}}
Beispiel 3: Übergeben mehrerer Header
In diesem Beispiel wird veranschaulicht, wie mehrere Header von einer hash-table
an eine REST-API übergeben werden.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
APIs erfordern häufig übergebene Header für Authentifizierung, Validierung usw.
Beispiel 3: Senden von Formulardaten
Wenn der Textkörper ein Formular ist oder die Ausgabe eines anderen Invoke-WebRequest
Aufrufs ist, legt PowerShell den Anforderungsinhalt auf die Formularfelder fest.
Zum Beispiel:
$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]
Beispiel 4: Aufzählen zurückgegebener Elemente in der Pipeline
GitHub gibt mehrere Objekte eines Arrays zurück. Wenn Sie die Ausgabe an einen anderen Befehl senden, wird sie als einzelnes [Object[]]
Objekt gesendet.
Um die Objekte in die Pipeline aufzulisten, führen Sie die Ergebnisse an Write-Output
das Cmdlet in Klammern aus oder umbrechen sie. Im folgenden Beispiel wird die Anzahl der von GitHub zurückgegebenen Objekte gezählt. Zählt dann die Anzahl der Objekte, die an die Pipeline aufgezählt werden.
$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
Parameter
-Body
Gibt den Anforderungstext an. Der Text entspricht dem Inhalt der Anforderung, der auf die Header folgt.
Sie können auch einen Textkörperwert an Invoke-RestMethod
.
Der Parameter "Body" kann verwendet werden, um eine Liste von Abfrageparametern anzugeben oder den Inhalt der Antwort anzugeben.
Wenn die Eingabe eine GET-Anforderung und der Text ein IDictionary-Objekt (i. d. r. eine Hashtabelle) ist, wird der Text dem URI als Abfrageparameter hinzugefügt. Für andere Anforderungstypen (z. B. POST) wird der Text als Wert des Anforderungstexts im Format „Standardname=Wertformat“ festgelegt.
Warnung
Die ausführliche Ausgabe eines POST-Texts endet mit with -1-byte payload
, obwohl die Größe des Textkörpers sowohl bekannt als auch im Content-Length
HTTP-Header gesendet wird.
Typ: | Object |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | True |
Platzhalterzeichen akzeptieren: | False |
-Certificate
Gibt das Clientzertifikat an, das für eine sichere Webanforderung verwendet wird. Geben Sie eine Variable ein, die ein Zertifikat, einen Befehl oder einen Ausdruck enthält, durch die das Zertifikat abgerufen wird.
Um ein Zertifikat zu suchen, verwenden oder verwenden Sie Get-PfxCertificate
das Get-ChildItem
Cmdlet auf dem Zertifikatlaufwerk (Cert:
Zertifikat). Wenn das Zertifikat ungültig ist oder keine qualifizierte Zertifizierungsstelle aufweist, verursacht der Befehl einen Fehler.
Typ: | X509Certificate |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-CertificateThumbprint
Gibt das digitale Zertifikat für öffentliche Schlüssel (X509) eines Benutzerkontos an, das über die Berechtigung zum Senden der Anforderung verfügt. Geben Sie den Zertifikatfingerabdruck des Zertifikats ein.
Zertifikate werden bei der clientzertifikatbasierten Authentifizierung verwendet. Zertifikate können nur lokalen Benutzerkonten zugeordnet werden, nicht Domänenkonten.
Um den Zertifikatfingerabdruck anzuzeigen, verwenden Sie den Befehl oder Get-ChildItem
den Get-Item
Befehl, um das Zertifikat in Cert:\CurrentUser\My
.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ContentType
Gibt den Inhaltstyp der Webanforderung an.
Wenn dieser Parameter nicht angegeben wird und die Anforderungsmethode POST ist, Invoke-RestMethod
wird der Inhaltstyp auf "application/x-www-form-urlencoded" festgelegt. Andernfalls wird der Inhaltstyp nicht im Aufruf angegeben.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Credential
Gibt ein Benutzerkonto an, das über die Berechtigung zum Senden der Anforderung verfügt. Der Standardwert ist der aktuelle Benutzer.
Geben Sie einen Benutzernamen ein, z. B. "User01" oder "Domain01\User01", oder geben Sie ein vom Cmdlet generiertes Get-Credential
PSCredential-Objekt ein.
Anmeldeinformationen werden in einem PSCredential-Objekt gespeichert, und das Kennwort wird als SecureString gespeichert.
Hinweis
Weitere Informationen zum Schutz von SecureString finden Sie unter "Wie sicher ist SecureString?".
Typ: | PSCredential |
Position: | Named |
Standardwert: | Current user |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-DisableKeepAlive
Legt den KeepAlive-Wert im HTTP-Header auf False fest. "KeepAlive" ist standardmäßig "True". KeepAlive stellt eine dauerhafte Verbindung mit dem Server her, um nachfolgende Anforderungen zu erleichtern.
Typ: | SwitchParameter |
Position: | Named |
Standardwert: | KeepAlive |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Headers
Gibt die Header der Webanforderung an. Geben Sie eine Hashtabelle oder ein Wörterbuch ein.
Verwenden Sie zum Festlegen von UserAgent-Headern den Parameter "UserAgent ". Sie können diesen Parameter nicht verwenden, um UserAgent- oder Cookieheader anzugeben.
Typ: | IDictionary |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-InFile
Ruft den Inhalt der Webanforderung aus einer Datei ab.
Geben Sie einen Pfad- und Dateinamen ein. Wenn Sie den Pfad weglassen, wird der aktuelle Speicherort als Standard verwendet.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-MaximumRedirection
Bestimmt, wie oft Windows PowerShell eine Verbindung an einen alternativen URI (Uniform Resource Identifier) umleitet, bevor die Verbindung fehlschlägt. Der Standardwert ist 5. Der Wert 0 (null) unterbindet sämtliche Umleitungen.
Typ: | Int32 |
Position: | Named |
Standardwert: | 5 |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Method
Gibt die für die Webanforderung verwendete Methode an. Zulässige Werte für diesen Parameter:
Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace
Typ: | WebRequestMethod |
Zulässige Werte: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Standardwert: | Default |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-OutFile
Speichert den Antworttext in der angegebenen Ausgabedatei. Geben Sie einen Pfad- und Dateinamen ein. Wenn Sie den Pfad weglassen, wird der aktuelle Speicherort als Standard verwendet.
Gibt standardmäßig Invoke-RestMethod
die Ergebnisse an die Pipeline zurück.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-PassThru
Dieser Parameter ist nur gültig, wenn der OutFile-Parameter auch im Befehl verwendet wird. Die Absicht besteht darin, die Ergebnisse in die Datei und in die Pipeline zu schreiben.
Hinweis
Wenn Sie den PassThru-Parameter verwenden, wird die Ausgabe in die Pipeline geschrieben, die Datei ist jedoch leer. Weitere Informationen finden Sie unter PowerShell-Problem Nr. 15409.
Typ: | SwitchParameter |
Position: | Named |
Standardwert: | No output |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Proxy
Verwendet einen Proxyserver für die Anforderung, anstatt eine direkte Verbindung mit der Internetressource herzustellen. Geben Sie den URI des Netzwerk-Proxyservers ein.
Typ: | Uri |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ProxyCredential
Gibt ein Benutzerkonto an, das über die Berechtigung zum Verwenden des Proxyservers verfügt, der durch den Proxyparameter angegeben wird. Der Standardwert ist der aktuelle Benutzer.
Geben Sie einen Benutzernamen ein, z. B. "User01" oder "Domain01\User01", oder geben Sie ein PSCredential-Objekt ein, z. B. ein vom Get-Credential
Cmdlet generiertes Objekt.
Dieser Parameter ist nur gültig, wenn der Proxyparameter auch im Befehl verwendet wird. Sie können die Parameter ProxyCredential und ProxyUseDefaultCredentials nicht im selben Befehl verwenden.
Typ: | PSCredential |
Position: | Named |
Standardwert: | Current user |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ProxyUseDefaultCredentials
Verwendet die Anmeldeinformationen des aktuellen Benutzers, um auf den Proxyserver zuzugreifen, der vom Proxyparameter angegeben wird.
Dieser Parameter ist nur gültig, wenn der Proxyparameter auch im Befehl verwendet wird. Sie können die Parameter ProxyCredential und ProxyUseDefaultCredentials nicht im selben Befehl verwenden.
Typ: | SwitchParameter |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-SessionVariable
Erstellt eine Variable, die die Webanforderungssitzung enthält. Geben Sie einen Variablennamen ohne das Dollarzeichen ($
) ein.
Wenn Sie eine Sitzungsvariable angeben, Invoke-RestMethod
wird ein Webanforderungssitzungsobjekt erstellt und einer Variablen mit dem angegebenen Namen in Ihrer PowerShell-Sitzung zugewiesen. Sie können die Variable in der Sitzung verwenden, sobald der Befehl abgeschlossen wurde.
Im Gegensatz zu einer Remotesitzung ist die Webanforderungssitzung keine dauerhafte Verbindung. Es handelt sich um ein Objekt, das Informationen über die Verbindung und die Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, maximaler Umleitungswert und der Benutzer-Agent-Zeichenfolge. Sie können das Objekt verwenden, um den Zustand und die Daten übergreifend für Webanforderungen zu nutzen.
Um die Webanforderungssitzung in nachfolgenden Webanforderungen zu verwenden, geben Sie die Sitzungsvariable im Wert des WebSession-Parameters an. PowerShell verwendet die Daten im Webanforderungssitzungsobjekt beim Herstellen der neuen Verbindung. Um einen Wert in der Webanforderungssitzung außer Kraft zu setzen, verwenden Sie einen Cmdlet-Parameter, z . B. UserAgent oder Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.
Sie können die Parameter "SessionVariable " und "WebSession " nicht im selben Befehl verwenden.
Typ: | String |
Aliase: | SV |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-TimeoutSec
Gibt an, wie lange die Anforderung ausstehen kann, bevor ein Zeitüberschreitung erfolgt. Geben Sie einen Wert in Sekunden ein. Der Standardwert 0 (null) steht für einen unbegrenzten Zeitüberschreitungswert.
Eine DNS-Abfrage (Domain Name System) kann bis zu 15 Sekunden dauern, bis ein Timeout zurückgegeben oder beendet wird. Wenn Ihre Anforderung einen Hostnamen enthält, der eine Auflösung erfordert, und Sie TimeoutSec auf einen Wert größer als Null festlegen, aber weniger als 15 Sekunden, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird, und Die Anforderung timeoutout.
Typ: | Int32 |
Position: | Named |
Standardwert: | 0 |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-TransferEncoding
Gibt einen Wert für den HTTP-Antwortheader transfer-encoding an. Zulässige Werte für diesen Parameter:
Chunked
Compress
Deflate
GZip
Identity
Typ: | String |
Zulässige Werte: | chunked, compress, deflate, gzip, identity |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Uri
Gibt den URI (Uniform Resource Identifier) der Internetressource an, an die die Webanforderung gesendet wird. Dieser Parameter unterstützt HTTP-, HTTPS-, FTP- und FILE-Werte.
Dieser Parameter ist erforderlich. Der Parametername (URI) ist optional.
Typ: | Uri |
Position: | 0 |
Standardwert: | None |
Erforderlich: | True |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-UseBasicParsing
Gibt an, dass das Cmdlet grundlegende Analyse verwendet. Das Cmdlet gibt den unformatierten HTML-Code in einem String-Objekt zurück.
Typ: | SwitchParameter |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-UseDefaultCredentials
Er verwendet die Anmeldeinformationen des aktuellen Benutzers, um die Webanforderung zu senden.
Typ: | SwitchParameter |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-UserAgent
Gibt eine Benutzer-Agent-Zeichenfolge für die Webanforderung an.
Der Standard-Benutzer-Agent ähnelt „Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0“ mit geringfügigen Abweichungen für die einzelnen Betriebssysteme und Plattformen.
Um eine Website mit der standardmäßigen Benutzer-Agent-Zeichenfolge zu testen, die von den meisten Internetbrowsern verwendet wird, verwenden Sie die Eigenschaften der PSUserAgent-Klasse , z. B. Chrome, FireFox, Internet Explorer, Opera und Safari.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-WebSession
Gibt eine Webanforderungssitzung an. Geben Sie den Variablennamen ein, einschließlich des Dollarzeichens ($
).
Um einen Wert in der Webanforderungssitzung außer Kraft zu setzen, verwenden Sie einen Cmdlet-Parameter, z . B. UserAgent oder Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.
Im Gegensatz zu einer Remotesitzung besteht bei der Webanforderungssitzung keine persistente Verbindung. Es handelt sich um ein Objekt, das Informationen über die Verbindung und die Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, dem Maximalwert für Umleitungen und der Zeichenfolge des Benutzer-Agents. Sie können das Objekt verwenden, um den Zustand und die Daten übergreifend für Webanforderungen zu nutzen.
Um eine Webanforderungssitzung zu erstellen, geben Sie einen Variablennamen (ohne Dollarzeichen) in den Wert des SessionVariable-Parameters eines Invoke-RestMethod
Befehls ein. Invoke-RestMethod
erstellt die Sitzung und speichert sie in der Variablen. Verwenden Sie in nachfolgenden Befehlen die Variable als Wert des WebSession-Parameters .
Sie können die Parameter "SessionVariable " und "WebSession " nicht im selben Befehl verwenden.
Typ: | WebRequestSession |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
Eingaben
Sie können den Textkörper einer Webanforderung an dieses Cmdlet weiterleiten.
Ausgaben
Wenn die Anforderung eine ganze Zahl zurückgibt, gibt dieses Cmdlet diese ganze Zahl zurück.
Wenn die Anforderung eine Zeichenfolge zurückgibt, gibt dieses Cmdlet diese Zeichenfolge zurück.
Wenn die Anforderung gültige XML-Daten zurückgibt, gibt dieses Cmdlet es als XmlDocument zurück.
PSObject
Wenn die Anforderung JSON-Zeichenfolgen zurückgibt, gibt dieses Cmdlet ein PSObject zurück, das die Daten darstellt.
Hinweise
Windows PowerShell enthält die folgenden Aliase für Invoke-RestMethod
:
irm