Invoke-RestMethod

Referenz

Modul:: Microsoft.PowerShell.Utility

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 reich strukturierte Daten zurückgibt.

Windows PowerShell formatiert die Antwort auf der Grundlage des Datentyps. Bei einem RSS- oder ATOM-Feed gibt Windows PowerShell den Item- oder Entry XML-Knoten zurück. Bei JavaScript Object Notation (JSON) oder XML konvertiert (oder deserialisiert) Windows PowerShell den Inhalt in Objekte.

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://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

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ührtInvoke-RestMethod, um eine POST-Anforderung auf einer Intranetwebsite im organization 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

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

In diesem Beispiel wird veranschaulicht, wie mehrere Header von einer hash-table an eine REST-API übergeben werden.

Parameter

-Body

Gibt den Anforderungstext an. Der Text entspricht dem Inhalt der Anforderung, der auf die Header folgt. Sie können auch einen Textwert an übergeben Invoke-RestMethod.

Der -Body Parameter 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, auch wenn die Größe des Textkörpers bekannt und im Content-Length HTTP-Header gesendet wird.

Wenn der Text ein Formular oder die Ausgabe eines anderen Invoke-WebRequest Aufrufs ist, legt Windows PowerShell den Anforderungsinhalt auf die Formularfelder fest.

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]

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	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 finden, verwenden Sie Get-PfxCertificate das Get-ChildItem Cmdlet auf dem Laufwerk Zertifikat (Cert:) oder verwenden Sie es. Wenn das Zertifikat ungültig ist oder keine qualifizierte Zertifizierungsstelle aufweist, verursacht der Befehl einen Fehler.

Type:	X509Certificate
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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. Sie können nur lokalen Benutzerkonten zugeordnet werden und funktionieren nicht mit Domänenkonten.

Um einen Zertifikatfingerabdruck abzurufen, verwenden Sie den Get-Item Befehl oder Get-ChildItem auf dem Laufwerk Windows PowerShell (Cert:).

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

-ContentType

Gibt den Inhaltstyp der Webanforderung an.

Wenn dieser Parameter nicht angegeben wird und die Anforderungsmethode POST ist, Invoke-RestMethod legt den Inhaltstyp auf "application/x-www-form-urlencoded" fest. Andernfalls wird der Inhaltstyp nicht im Aufruf angegeben.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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. %%amp;quot;User01%%amp;quot; oder %%amp;quot;Domain01\User01%%amp;quot;, oder geben Sie ein PSCredential-Objekt ein, z. B. ein vom Get-Credential-Cmdlet generiertes Objekt.

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

-DisableKeepAlive

Legt den KeepAlive-Wert im HTTP-Header auf „False“ fest. Der Standardwert von KeepAlive ist „True“. KeepAlive richtet eine persistente Verbindung mit dem Server ein, um nachfolgende Anforderungen zu erleichtern.

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

-Headers

Gibt die Header der Webanforderung an. Geben Sie eine Hashtabelle oder ein Wörterbuch ein.

Verwenden Sie den -UserAgent Parameter, um UserAgent-Header festzulegen. Sie können diesen Parameter nicht verwenden, um UserAgent- oder Cookieheader anzugeben.

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

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

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

-Method

Gibt die für die Webanforderung verwendete Methode an. Zulässige Werte für diesen Parameter:

Standard
Löschen
Herunterladen
Head
Zusammenführen
Optionen
Patch
Posten
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

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. Verwenden Sie den Parameter, um die Ergebnisse an eine Datei und an die -Passthru Pipeline zu senden.

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

-PassThru

Gibt die Ergebnisse zurück und schreibt sie in eine Datei. Dieser Parameter ist nur gültig, wenn der -OutFile-Parameter ebenfalls im Befehl verwendet wird.

Type:	SwitchParameter
Position:	Named
Default value:	No output
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

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

-ProxyCredential

Gibt ein Benutzerkonto an, das über die Berechtigung zum Verwenden des Proxyservers verfügt, der durch den -Proxy Parameter angegeben wird. Der Standardwert ist der aktuelle Benutzer.

Dieser Parameter ist nur gültig, wenn der -Proxy-Parameter ebenfalls im Befehl verwendet wird. Sie können die -ProxyCredential Parameter und -ProxyUseDefaultCredentials nicht im gleichen Befehl verwenden.

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

-ProxyUseDefaultCredentials

Verwendet die Anmeldeinformationen des aktuellen Benutzers, um auf den Proxyserver zuzugreifen, der durch den -Proxy Parameter angegeben wird.

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

-SessionVariable

Erstellt eine Webanforderungssitzung und speichert sie in dem Wert der angegebenen Variablen. Geben Sie einen Variablennamen ohne das Dollarzeichen ($)-Symbol ein.

Wenn Sie eine Sitzungsvariable angeben, Invoke-RestMethod erstellen Sie ein Webanforderungssitzungsobjekt und weisen es einer Variablen mit dem angegebenen Namen in Ihrer Windows PowerShell-Sitzung zu. Sie können die Variable in der Sitzung verwenden, sobald der Befehl abgeschlossen wurde.

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 die Webanforderungssitzung in nachfolgenden Webanforderungen zu verwenden, geben Sie die Sitzungsvariable im Wert des Parameters an -WebSession . Windows PowerShell verwendet die Daten im Objekt der Webanforderungssitzung beim Herstellen der neuen Verbindung. Um einen Wert in der Webanforderungssitzung zu überschreiben, verwenden Sie einen Cmdletparameter, z -UserAgent . B. oder -Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.

Sie können die -SessionVariable Parameter und -WebSession nicht im gleichen Befehl verwenden.

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

-TimeoutSec

Gibt an, wie lange die Anforderung ausstehen kann, bevor das Zeitlimit fällt. 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 sie zurückgegeben wird oder ein Timeout erfolgt. Wenn Ihre Anforderung einen Hostnamen enthält, für den eine Auflösung erforderlich ist, und Sie TimeoutSec auf einen Wert größer als 00, aber weniger als 15 Sekunden festlegen, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird und die Anforderung ein Timeoutout hat.

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

-TransferEncoding

Gibt einen Wert für den HTTP-Antwortheader transfer-encoding an. Zulässige Werte für diesen Parameter:

Segmentiert
Komprimieren
Deflate
GZip
Identität

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

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.

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

-UseBasicParsing

Gibt an, dass das Cmdlet die grundlegende Analyse verwendet. Das Cmdlet gibt den unformatierten HTML-Code in einem String-Objekt zurück.

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

-UseDefaultCredentials

Er verwendet die Anmeldeinformationen des aktuellen Benutzers, um die Webanforderung zu senden.

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

Verwenden Sie zum Testen einer Website mit der Standard-Benutzer-Agent-Zeichenfolge, die von den meisten Internetbrowsern verwendet wird, die Eigenschaften der PSUserAgent-Klasse, z. B. Chrome, FireFox, Internet Explorer, Opera und Safari.

Beispielsweise verwendet der folgende Befehl die Benutzer-Agent-Zeichenfolge für den Internet Explorer:

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

Gibt eine Webanforderungssitzung an. Geben Sie den Variablennamen ein, einschließlich des Dollarzeichens ($).

Um einen Wert in der Webanforderungssitzung zu überschreiben, verwenden Sie einen Cmdletparameter, z -UserAgent . B. oder -Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.

Um eine Webanforderungssitzung zu erstellen, geben Sie einen Variablennamen (ohne Dollarzeichen) in den Wert des -SessionVariable Parameters eines Befehls ein Invoke-RestMethod . 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 -SessionVariable Parameter und -WebSession nicht im gleichen Befehl verwenden.

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

Eingaben

Object

Sie können den Text einer Webanforderung an übergeben Invoke-RestMethod.

Ausgaben

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

Die Ausgabe des Cmdlets hängt vom Format des abgerufenen Inhalts ab.

PSObject

Wenn die Anforderung JSON-Zeichenfolgen zurückgibt, Invoke-RestMethod gibt ein PSObject zurück, das die Zeichenfolgen darstellt.

Freigeben über

Invoke-RestMethod

Syntax

Beschreibung

Beispiele

Beispiel 1: Abrufen des PowerShell-RSS-Feeds

Beispiel 2

Beispiel 3: Übergeben mehrerer Header

Parameter

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Eingaben

Ausgaben

Zusätzliche Ressourcen

Freigeben über

Invoke-RestMethod

Syntax

Beschreibung

Beispiele

Beispiel 1: Abrufen des PowerShell-RSS-Feeds

Beispiel 2

Beispiel 3: Übergeben mehrerer Header

Parameter

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Eingaben

Ausgaben

Ähnliche Themen

Zusätzliche Ressourcen