Invoke-RestMethod

Modul:: Microsoft.PowerShell.Utility Module

Sendet eine HTTP- oder HTTPS-Anforderung an einen RESTful-Webdienst.

Syntax

StandardMethod (Standard)

Invoke-RestMethod
    [-Uri] <Uri>
    [-Method <WebRequestMethod>]
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-RetryIntervalSec <Int32>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

StandardMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -NoProxy
    [-Method <WebRequestMethod>]
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-RetryIntervalSec <Int32>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

CustomMethod

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-RetryIntervalSec <Int32>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

CustomMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-RetryIntervalSec <Int32>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

Beschreibung

Das Cmdlet Invoke-RestMethod 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 oder deserialisiert PowerShell den Inhalt in [PSCustomObject]-Objekte.

Hinweis

Wenn der REST-Endpunkt mehrere Objekte zurückgibt, werden die Objekte als Array empfangen. Wenn Sie die Ausgabe von Invoke-RestMethod an 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.

Ab PowerShell 7.0 unterstützt Invoke-RestMethod die proxykonfiguration, die von Umgebungsvariablen definiert wird. Weitere Informationen finden Sie im Abschnitt Notizen dieses Artikels.

Beispiele

Beispiel 1: Abrufen des PowerShell-RSS-Feeds

In diesem Beispiel wird das Cmdlet Invoke-RestMethod verwendet, um Informationen aus dem RSS-Feed des PowerShell-Blogs abzurufen. Der Befehl verwendet das Cmdlet Format-Table, um die Werte der Title- und pubDate- Eigenschaften jedes Blogs in einer Tabelle anzuzeigen.

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

Beispiel 2: Ausführen einer POST-Anforderung

In diesem Beispiel führt ein Benutzer Invoke-RestMethod aus, um eine POST-Anforderung auf einer Intranetwebsite in der Organisation des Benutzers zu erledigen.

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

Die Anmeldeinformationen werden abgefragt und dann in $Cred gespeichert, und die URL, auf die zugegriffen werden soll, wird in $Urldefiniert.

Die variable $Body beschreibt die Suchkriterien, gibt CSV als Ausgabemodus an und gibt einen Zeitraum für zurückgegebene Daten an, der vor zwei Tagen beginnt und vor einem Tag endet. Die Textvariable gibt Werte für Parameter an, die für die bestimmte REST-API gelten, mit der Invoke-RestMethod kommunizieren.

Der Befehl Invoke-RestMethod wird mit allen Variablen ausgeführt und gibt einen Pfad und Dateinamen für die resultierende CSV-Ausgabedatei an.

Beispiel 3: Folgen Sie den Beziehungslinks

Einige REST-APIs unterstützen die Paginierung über Relations-Links gemäß RFC5988. Anstatt die Kopfzeile zu analysieren, um die URL für die nächste Seite abzurufen, können Sie dies mit dem Cmdlet tun. In diesem Beispiel werden die ersten beiden Seiten von Problemen aus dem PowerShell-GitHub-Repository zurückgegeben.

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Beispiel 4: Vereinfachte Multipart/Formular-Daten-Übermittlung

Einige APIs erfordern multipart/form-data Übermittlungen zum Hochladen von Dateien und gemischten Inhalten. In diesem Beispiel wird veranschaulicht, wie das Profil eines Benutzers aktualisiert wird.

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form

Das Profilformular erfordert folgende Felder: firstName, lastName, email, avatar, birthdayund hobbies. Die API erwartet, dass ein Bild für das Benutzerprofilbild im Feld avatar angegeben wird. Die API akzeptiert auch mehrere hobbies Einträge, die im selben Formular eingereicht werden müssen.

Beim Erstellen der $Form HashTable werden die Schlüsselnamen als Formularfeldnamen verwendet. Standardmäßig werden die Werte der HashTable in Zeichenfolgen konvertiert. Wenn ein System.IO.FileInfo Wert vorhanden ist, wird der Dateiinhalt übermittelt. Wenn eine Sammlung wie Arrays oder Listen vorhanden ist, wird das Formularfeld mehrmals gesendet.

Durch die Verwendung Get-Item des Schlüssels avatar wird das FileInfo Objekt als Wert festgelegt. Das Ergebnis ist, dass die Bilddaten für jdoe.png übermittelt werden.

Wenn Sie dem Schlüssel eine Liste hinzufügen hobbies , wird das hobbies Feld einmal für jedes Listenelement in den Einreichungen angezeigt.

Beispiel 5: Übergeben mehrerer Header

APIs erfordern häufig übergebene Header für die Authentifizierung oder Validierung. In diesem Beispiel wird veranschaulicht, wie mehrere Header aus einer hash-table an eine REST-API übergeben werden.

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

Beispiel 6: 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 der Pipeline aufzulisten, leiten Sie die Ergebnisse an Write-Output weiter oder schließen Sie das Cmdlet in Klammern ein. Im folgenden Beispiel wird die Anzahl der von GitHub zurückgegebenen Objekte gezählt. Zählen Sie dann die Anzahl der aufgelisteten Objekte in der Pipeline.

$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

Beispiel 7: Überspringen der Headerüberprüfung

Standardmäßig überprüft das Invoke-RestMethod Cmdlet die Werte bekannter Header, die über ein standarddefiniertes Wertformat verfügen. Das folgende Beispiel zeigt, wie diese Überprüfung einen Fehler auslösen kann und wie Sie den SkipHeaderValidation Parameter verwenden können, um zu vermeiden, dass Werte für Endpunkte überprüft werden, die ungültig formatierte Werte tolerieren.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org ist ein Dienst, der Informationen zu Webanforderungen und Antworten zur Problembehandlung zurückgibt. Die $Uri Variable wird dem /headers Endpunkt des Diensts zugewiesen, der die Kopfzeilen einer Anforderung als Inhalt in der Antwort zurückgibt.

Der If-Match Anfrage-Header ist in RFC-7232 Abschnitt 3.1 definiert und erfordert, dass der Wert für diesen Header mit umgebenden Anführungszeichen definiert wird. Der $InvalidHeaders Variable wird eine Hashtabelle zugewiesen, bei der der Wert von If-Match ungültig ist, da sie anstelle von 12345als "12345" definiert ist.

Das Aufrufen von Invoke-RestMethod mit den ungültigen Headern gibt einen Fehlerbericht zurück, dass der formatierte Wert ungültig ist. Die Anforderung wird nicht an den Endpunkt gesendet.

Das Aufrufen Invoke-RestMethod mit dem SkipHeaderValidation- Parameter ignoriert den Überprüfungsfehler und sendet die Anforderung an den Endpunkt. Da der Endpunkt nicht kompatible Headerwerte toleriert, gibt das Cmdlet das Antwortobjekt ohne Fehler zurück.

Beispiel 8: Senden einer Anforderung mit HTTP 2.0

In diesem Beispiel wird ein GitHub-Problem mithilfe des HTTP 2.0-Protokolls abgerufen.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

Parameter

-AllowUnencryptedAuthentication

Ermöglicht das Senden von Anmeldeinformationen und geheimen Schlüsseln über unverschlüsselte Verbindungen. Standardmäßig führt das Angeben von Anmeldeinformationen oder einer Authentifizierungsoption mit einem URI , der nicht mit https:// beginnt, zu einem Fehler, und die Anforderung wird abgebrochen, um zu verhindern, dass Geheimnisse unbeabsichtigt im Klartext über unverschlüsselte Verbindungen kommuniziert werden. Um dieses Verhalten auf eigenes Risiko außer Kraft zu setzen, geben Sie den AllowUnencryptedAuthentication Parameter an.

Warnung

Die Verwendung dieses Parameters ist nicht sicher und wird nicht empfohlen. Sie wird nur aus Gründen der Kompatibilität mit Legacy-Systemen bereitgestellt, die keine verschlüsselten Verbindungen bereitstellen können. Verwenden Sie auf eigenes Risiko.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Authentication

Gibt den expliziten Authentifizierungstyp an, der für die Anforderung verwendet werden soll. Der Standardwert ist "None". Der parameter Authentication kann nicht mit dem parameter UseDefaultCredentials verwendet werden.

Verfügbare Authentifizierungsoptionen:

None: Dies ist die Standardoption, wenn die Authentifizierung nicht angegeben wird. Es wird keine explizite Authentifizierung verwendet.
Basic: Erfordert Anmeldeinformationen. Die Anmeldeinformationen werden verwendet, um einen RFC 7617 Basic Authentication-Header Authorization: Basic im Format zu senden.base64(user:password)
Bearer: Erfordert den parameter Token. Sendet einen RFC 6750-Authorization: Bearer-Header mit dem bereitgestellten Token.
OAuth: Erfordert den parameter Token. Sendet einen RFC 6750-Authorization: Bearer-Header mit dem bereitgestellten Token.

Die Angabe von Authentifizierung überschreibt alle Authorization-Header, die an Headers übergeben oder in WebSession enthalten sind.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	WebAuthenticationType
Standardwert:	None
Zulässige Werte:	None, Basic, Bearer, OAuth
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Body

Gibt den Inhalt der Anforderung an. Der Textkörper ist der Inhalt der Anforderung, die den Kopfzeilen folgt. Sie können auch einen Body-Wert an Invoke-RestMethod weiterleiten.

Der parameter Body kann verwendet werden, um eine Liste der Abfrageparameter anzugeben oder den Inhalt der Antwort anzugeben.

Wenn es sich bei der Eingabe um eine POST-Anforderung handelt und der Text ein Stringist, wird der Wert links neben dem ersten Gleichheitszeichen (=) als Schlüssel in den Formulardaten festgelegt, und der verbleibende Text wird als Wert festgelegt. Um mehrere Schlüssel anzugeben, verwenden Sie ein IDictionary--Objekt, wie etwa eine Hashtabelle, für den Body-.

Wenn die Eingabe eine GET-Anforderung ist und der Textkörper ein IDictionary (in der Regel eine Hashtabelle) ist, wird der Textkörper als Abfrageparameter dem URI hinzugefügt. Bei anderen Anfragetypen (wie z. B. PATCH) wird der Body als Wert des Anfragebodys im Standardformat name=value festgelegt, wobei die Werte URL-kodiert sind.

Wenn es sich bei der Eingabe um ein System.Xml.XmlNode-Objekt handelt und die XML-Deklaration eine Codierung angibt, wird diese Codierung für die Daten in der Anforderung verwendet, es sei denn, dies wird vom ContentType Parameter außer Kraft gesetzt.

Wenn es sich bei dem Body um ein Formular oder um die Ausgabe eines anderen Invoke-WebRequest-Aufrufs handelt, legt PowerShell den Inhalt der Anfrage auf die Formularfelder fest.

Der Body-Parameter kann auch ein System.Net.Http.MultipartFormDataContent-Objekt akzeptieren. Dies wird Anfragen erleichtern multipart/form-data . Wenn ein MultipartFormDataContent-Objekt für Body angegeben wird, werden alle inhaltsbezogenen Header, die für die Parameter ContentType, Headers oder WebSession bereitgestellt werden, durch die Inhaltsheader des MultipartFormDataContent Objekts überschrieben. Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	Object
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	True
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Certificate

Gibt das Clientzertifikat an, das für eine sichere Webanforderung verwendet wird. Geben Sie eine Variable ein, die ein Zertifikat enthält oder einen Befehl bzw. Ausdruck zum Abrufen des Zertifikats.

Um ein Zertifikat zu finden, verwenden Sie Get-PfxCertificate oder verwenden Sie das cmdlet Get-ChildItem im Zertifikatlaufwerk (Cert:). Wenn das Zertifikat ungültig ist oder nicht über ausreichende Autorität verfügt, schlägt der Befehl fehl.

Parametereigenschaften

Typ:	X509Certificate
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-CertificateThumbprint

Gibt das zertifikat für den digitalen öffentlichen 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 in der zertifikatbasierten Clientauthentifizierung verwendet. Zertifikate können nur lokalen Benutzerkonten zugeordnet werden, nicht Domänenkonten.

Um den Zertifikatfingerabdruck anzuzeigen, verwenden Sie den Befehl Get-Item oder Get-ChildItem, um das Zertifikat in Cert:\CurrentUser\Myzu finden.

Hinweis

Dieses Feature wird derzeit nur auf Windows-Betriebssystemplattformen unterstützt.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-ContentType

Gibt den Inhaltstyp der Webanforderung an.

Wenn der Wert für ContentType- das Codierungsformat (wie charset) enthält, verwendet das Cmdlet dieses Format, um den Textkörper der Webanforderung zu codieren. Wenn der ContentType- kein Codierungsformat angibt, wird stattdessen das Standardcodierungsformat verwendet. Ein Beispiel für ein ContentType - mit einem Codierungsformat ist text/plain; charset=iso-8859-5, das das lateinische/kyrillische Alphabet angibt.

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

ContentType wird überschrieben, wenn ein MultipartFormDataContent Objekt für Body angegeben wird.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Credential

Gibt ein Benutzerkonto an, das über die Berechtigung zum Senden der Anforderung verfügt. Die Standardeinstellung ist der aktuelle Benutzer.

Geben Sie einen Benutzernamen ein, z. B. User01 oder Domain01\User01, oder geben Sie ein PSCredential-Objekt ein, das vom cmdlet Get-Credential generiert wird.

anmeldeinformationen können allein oder in Verbindung mit bestimmten Authentication Parameteroptionen verwendet werden. Bei alleiniger Verwendung werden Anmeldeinformationen nur dann an den Remoteserver übermittelt, wenn der Remoteserver eine Authentifizierungsanforderung sendet. Bei Verwendung mit Authentifizierungsoptionen werden die Anmeldeinformationen explizit gesendet.

Anmeldeinformationen werden in einem PSCredential-Objekt gespeichert, und das Kennwort wird als SecureString-gespeichert.

Hinweis

Weitere Informationen zu SecureString Datenschutz finden Sie unter Wie sicher ist SecureString?.

Parametereigenschaften

Typ:	PSCredential
Standardwert:	Current user
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-CustomMethod

Gibt die benutzerdefinierte Methode an, die für die Webanforderung verwendet wird. Dies kann mit der Anforderungsmethode verwendet werden, die für den Endpunkt erforderlich ist, ist keine verfügbare Option für die Methode. Method und CustomMethod können nicht zusammen verwendet werden.

Beispiel:

Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Dadurch wird eine TEST HTTP-Anforderung an die API gesendet.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	ZENTIMETER

Parametersätze

CustomMethodNoProxy

Position:	Named
Obligatorisch:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CustomMethod

Position:	Named
Obligatorisch:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-DisableKeepAlive

Gibt an, dass das Cmdlet den KeepAlive-Wert im HTTP-Header auf False festlegt. Standardmäßig ist KeepAlive auf True gesetzt. KeepAlive stellt eine dauerhafte Verbindung mit dem Server her, um nachfolgende Anfragen zu erleichtern.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-FollowRelLink

Gibt an, dass das Cmdlet Beziehungslinks folgen soll.

Einige REST-APIs unterstützen die Paginierung über Relations-Links gemäß RFC5988. Anstatt die Kopfzeile zu analysieren, um die URL für die nächste Seite abzurufen, können Sie dies mit dem Cmdlet tun. Verwenden Sie den MaximumFollowRelLink-Parameter, um festzulegen, wie oft Beziehungslinks befolgt werden sollen.

Bei Verwendung dieser Option gibt das Cmdlet eine Sammlung von Seiten mit Ergebnissen zurück. Jede Ergebnisseite kann mehrere Ergebniselemente enthalten.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	FL

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Form

Konvertiert ein Wörterbuch in eine multipart/form-data-Übermittlung. Form darf nicht mit Body verwendet werden. Wenn ContentType ignoriert wird.

Als Namen für die Formularfelder werden die Schlüssel des Wörterbuchs verwendet. Standardmäßig werden Formularwerte in Zeichenfolgenwerte konvertiert.

Wenn es sich bei dem Wert um ein System.IO.FileInfo-Objekt handelt, wird der Inhalt der Binärdatei übermittelt. Der Name der Datei wird als filename. Das MIME wird auf application/octet-stream. Get-Item können verwendet werden, um die Bereitstellung des System.IO.FileInfo Objekts zu vereinfachen.

$Form = @{
    resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf'
}

Wenn es sich bei dem Wert um einen Sammlungstyp handelt, z. B. ein Array oder eine Liste, wird das for-Feld mehrmals übermittelt. Die Werte der Liste werden standardmäßig als Zeichenfolgen behandelt. Wenn es sich bei dem Wert um ein System.IO.FileInfo-Objekt handelt, wird der Inhalt der Binärdatei übermittelt. Eingebettete Collections werden nicht unterstützt.

$Form = @{
    tags     = 'Vacation', 'Italy', '2017'
    pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy\'
}

Im obigen Beispiel wird das tags Feld dreimal in der Form angegeben, einmal für jeweils , VacationItalyund 2017. Das pictures Feld wird auch einmal für jede Datei im 2017-Italy Ordner gesendet. Der binäre Inhalt der Dateien in diesem Ordner wird als Wert übergeben.

Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.

Parametereigenschaften

Typ:	IDictionary
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Headers

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

Inhaltsbezogene Kopfzeilen wie Content-Type werden außer Kraft gesetzt, wenn ein MultipartFormDataContent-Objekt für Body übergeben wird.

Parametereigenschaften

Typ:	IDictionary
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-HttpVersion

Gibt die HTTP-Version an, die für die Anforderung verwendet wird. Der Standardwert lautet 1.1.

Gültige Werte sind:

Parametereigenschaften

Typ:	Version
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-InFile

Ruft den Inhalt der Webanforderung aus einer Datei ab.

Geben Sie einen Pfad und Dateinamen ein. Wenn Sie den Pfad weglassen, ist die Standardeinstellung der aktuelle Speicherort.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-MaximumFollowRelLink

Gibt an, wie oft Beziehungslinks befolgt werden sollen, wenn FollowRelLink- verwendet wird. Ein kleinerer Wert kann erforderlich sein, wenn die REST-API wegen zu vieler Anforderungen verlangsamt. Der Standardwert ist [Int32]::MaxValue. Ein Wert von 0 (Null) verhindert die folgenden Beziehungslinks.

Parametereigenschaften

Typ:	Int32
Standardwert:	Int32.MaxValue
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	Maschinelles Lernen

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-MaximumRedirection

Gibt an, wie oft PowerShell eine Verbindung zu einem alternativen URI (Uniform Resource Identifier) umleitet, bevor die Verbindung fehlschlägt. Der Standardwert ist 5. Ein Wert von 0 (Null) verhindert die gesamte Umleitung.

Parametereigenschaften

Typ:	Int32
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-MaximumRetryCount

Gibt an, wie oft PowerShell eine Verbindung wiederholt, wenn ein Fehlercode zwischen 400 und 599 (einschließlich) oder 304 empfangen wird. Weitere Informationen zum Angeben der Anzahl der Sekunden zwischen den Wiederholungen finden Sie auch unter dem Parameter RetryIntervalSec .

Parametereigenschaften

Typ:	Int32
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Method

Gibt die Methode an, die für die Webanforderung verwendet wird. Die zulässigen Werte für diesen Parameter sind:

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Der parameter CustomMethod kann für Anforderungsmethoden verwendet werden, die oben nicht aufgeführt sind.

Parametereigenschaften

Typ:	WebRequestMethod
Standardwert:	None
Zulässige Werte:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

StandardMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

StandardMethodNoProxy

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-NoProxy

Gibt an, dass das Cmdlet keinen Proxy verwendet, um das Ziel zu erreichen.

Wenn Sie den in Internet Explorer konfigurierten Proxy oder einen in der Umgebung angegebenen Proxy umgehen müssen, verwenden Sie diese Option.

Dieser Parameter wurde in PowerShell 6.0 eingeführt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

StandardMethodNoProxy

Position:	Named
Obligatorisch:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CustomMethodNoProxy

Position:	Named
Obligatorisch:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-OutFile

Speichert den Antworttext in der angegebenen Ausgabedatei. Geben Sie einen Pfad und Dateinamen ein. Wenn Sie den Pfad weglassen, ist die Standardeinstellung der aktuelle Speicherort. Der Name wird als literaler Pfad behandelt. Namen, die eckige Klammern ([]) enthalten, müssen in einfache Anführungszeichen (') eingeschlossen werden.

Standardmäßig gibt Invoke-RestMethod die Ergebnisse an die Pipeline zurück.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-PassThru

Dieser Parameter ist nur gültig, wenn der parameter OutFile 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, aber die Datei wird nicht erstellt. Weitere Informationen finden Sie unter PowerShell-Problem Nr. 15409.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	No output
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-PreserveAuthorizationOnRedirect

Gibt an, dass das Cmdlet die Authorization Kopfzeile, sofern vorhanden, über Umleitungen hinweg beibehalten soll.

Standardmäßig entfernt das Cmdlet den Authorization Header vor der Umleitung. Wenn Sie diesen Parameter angeben, wird diese Logik für Fälle deaktiviert, in denen der Header an das Umleitungsziel gesendet werden muss.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Proxy

Verwendet einen Proxyserver für die Anforderung, anstatt eine direkte Verbindung mit der Internetressource herzustellen. Geben Sie den URI (Uniform Resource Identifier) eines Netzwerkproxyservers ein.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	Uri
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

StandardMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CustomMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-ProxyCredential

Gibt ein Benutzerkonto an, das über die Berechtigung zum Verwenden des Proxyservers verfügt, der durch den Proxyparameter angegeben wird. Die Standardeinstellung ist der aktuelle Benutzer.

Geben Sie einen Benutzernamen ein, z. B. Benutzer01 oder Domäne01\Benutzer01, User@Domain.Comoder geben Sie ein PSCredential Objekt ein, z. B. ein vom Get-Credential Cmdlet generiertes.

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

Parametereigenschaften

Typ:	PSCredential
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

StandardMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CustomMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-ProxyUseDefaultCredentials

Gibt an, dass das Cmdlet die Anmeldeinformationen des aktuellen Benutzers verwendet, um auf den Proxyserver zuzugreifen, der vom parameter Proxy angegeben wird.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

StandardMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CustomMethod

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-ResponseHeadersVariable

Erstellt eine Variable, die ein Antwort-Header-Wörterbuch enthält. Geben Sie einen Variablennamen ohne das Dollarzeichen ($) ein. Die Schlüssel des Wörterbuchs enthalten die Feldnamen und Werte des vom Webserver zurückgegebenen Antwortheaders.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	RHV

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Resume

Führt einen best effort-Versuch aus, das Herunterladen einer Teildatei fortzusetzen. Der Parameter Resume erfordert den Parameter OutFile.

Resume funktioniert nur mit der Größe der lokalen Datei und der Remotedatei und führt keine andere Überprüfung durch, dass die lokale Datei und die Remotedatei identisch sind.

Wenn die lokale Dateigröße kleiner ist als die Größe der Remotedatei, versucht das Cmdlet, den Download der Datei fortzusetzen und die verbleibenden Bytes an das Ende der Datei anzufügen.

Wenn die lokale Dateigröße mit der Remotedateigröße übereinstimmt, wird keine Aktion ausgeführt, und das Cmdlet geht davon aus, dass der Download bereits abgeschlossen ist.

Wenn die lokale Datei größer ist als die Größe der Remote-Datei, wird die lokale Datei überschrieben und die gesamte Remote-Datei wird vollständig erneut heruntergeladen. Dieses Verhalten ist dasselbe wie die Verwendung von OutFile ohne Resume.

Wenn der Remote-Server das Fortsetzen des Downloads nicht unterstützt, wird die lokale Datei überschrieben und die gesamte Remote-Datei wird vollständig erneut heruntergeladen. Dieses Verhalten ist dasselbe wie die Verwendung von OutFile ohne Resume.

Wenn die lokale Datei nicht vorhanden ist, wird die lokale Datei erstellt und die gesamte Remote-Datei vollständig heruntergeladen. Dieses Verhalten ist dasselbe wie die Verwendung von OutFile ohne Resume.

Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-RetryIntervalSec

Gibt das Intervall zwischen Wiederholungen für die Verbindung an, wenn ein Fehlercode zwischen 400 und 599 (einschließlich) oder 304 empfangen wird. Der Wert muss zwischen 1 und [int]::MaxValuesein.

Siehe auch den Parameter MaximumRetryCount, um die Anzahl der Wiederholungen anzugeben.

Parametereigenschaften

Typ:	Int32
Standardwert:	5
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-SessionVariable

Erstellt eine Variable, die die Webanforderungssitzung enthält. Geben Sie einen Variablennamen ohne das Dollarzeichen ($) ein.

Wenn Sie eine Sitzungsvariable angeben, erstellt Invoke-RestMethod ein Webanforderungssitzungsobjekt und weist sie einer Variablen mit dem angegebenen Namen in Ihrer PowerShell-Sitzung zu. Sie können die Variable in Ihrer Sitzung verwenden, sobald der Befehl abgeschlossen ist.

Vor PowerShell 7.4 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 es verwenden, um Status und Daten zwischen Webanforderungen auszutauschen.

Ab PowerShell 7.4 ist die Webanforderungssitzung dauerhaft, solange die Eigenschaften der Sitzung in einer nachfolgenden Anforderung nicht überschrieben werden. Wenn dies der Zeitpunkt ist, erstellt das Cmdlet die Sitzung mit den neuen Werten neu. Die persistenten Sitzungen reduzieren den Aufwand für wiederholte Anforderungen und machen sie viel schneller.

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 anmeldeinformationen. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.

Sie können die parameter SessionVariable und WebSession- nicht im selben Befehl verwenden.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	SV

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-SkipCertificateCheck

Überspringt Zertifikatsüberprüfungen, die alle Prüfungen umfassen, wie Ablaufdatum, Widerruf, vertrauenswürdige Stammzertifizierungsstelle usw.

Warnung

Die Verwendung dieses Parameters ist nicht sicher und wird nicht empfohlen. Dieser Schalter ist nur dafür vorgesehen, gegen bekannte Hosts mit einem selbstsignierten Zertifikat zu Testzwecken verwendet zu werden. Verwenden Sie auf eigenes Risiko.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-SkipHeaderValidation

Gibt an, dass das Cmdlet der Anforderung ohne Überprüfung Header hinzufügen soll.

Diese Option sollte für Websites verwendet werden, die Headerwerte erfordern, die nicht den Standards entsprechen. Wenn Sie diesen Schalter angeben, wird die Überprüfung deaktiviert, damit der Wert ohne Überprüfung übergeben werden kann. Wenn angegeben, werden alle Header ohne Überprüfung hinzugefügt.

Dadurch wird die Validierung von Werten deaktiviert, die an die Parameter ContentType, Headers und UserAgent übergeben werden.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-SkipHttpErrorCheck

Dieser Parameter bewirkt, dass das Cmdlet HTTP-Fehlerstatus ignoriert und weiterhin Antworten verarbeitet. Die Fehlerantworten werden genauso in die Pipeline geschrieben, als wären sie erfolgreich.

Dieser Parameter wurde in PowerShell 7 eingeführt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-SslProtocol

Legt die SSL/TLS-Protokolle fest, die für die Webanforderung zulässig sind. Standardmäßig sind ssl/TLS-Protokolle, die vom System unterstützt werden, zulässig. SslProtocol- ermöglicht die Beschränkung auf bestimmte Protokolle für Compliancezwecke.

Diese Werte werden als auf Flaggen basierende Enumeration definiert. Sie können mehrere Werte kombinieren, um mehrere Flags mithilfe dieses Parameters festzulegen. Die Werte können an den SslProtocol Parameter als Array von Werten oder als kommagetrennte Zeichenfolge dieser Werte übergeben werden. Das Cmdlet kombiniert die Werte mithilfe eines Binary-OR-Vorgangs. Das Übergeben von Werten als Array ist die einfachste Option und ermöglicht Ihnen auch die Verwendung der Tab-Vervollständigung für die Werte. Möglicherweise können Sie nicht auf allen Plattformen mehrere Werte angeben.

Hinweis

Auf Nicht-Windows-Plattformen ist es möglicherweise nicht möglich, Tls oder Tls12 als Option zu liefern. Die Unterstützung für Tls13 ist nicht auf allen Betriebssystemen verfügbar und muss pro Betriebssystem überprüft werden.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt, und die Unterstützung für Tls13 wurde in PowerShell 7.1 hinzugefügt.

Parametereigenschaften

Typ:	WebSslProtocol
Standardwert:	None
Zulässige Werte:	Default, Tls, Tls11, Tls12, Tls13
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-StatusCodeVariable

Erstellt eine Variable, die ein HTTP-Statuscodeergebnis der Anforderung enthält. Geben Sie einen Variablennamen ohne das Dollarzeichen ($) ein.

Der Parameter kann Erfolgsmeldungen oder Fehlermeldungen identifizieren, wenn er mit dem parameter SkipHttpErrorCheck verwendet wird.

Geben Sie den Variablennamen des Parameters als Zeichenfolge wie -StatusCodeVariable "scv"ein.

Dieser Parameter wurde in PowerShell 7 eingeführt.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-TimeoutSec

Gibt an, wie lange die Anforderung ausstehen kann, bevor es zu einer Zeitüberschreitung kommt. Bitte geben Sie einen Wert in Sekunden ein. Der Standardwert 0 gibt ein unbestimmtes Timeout an.

Es kann bis zu 15 Sekunden dauern, bis eine DNS-Abfrage (Domain Name System) zurückgegeben wird, oder es kommt zu einer Zeitüberschreitung. Wenn Ihre Anforderung einen Hostnamen enthält, der aufgelöst werden muss, und Sie TimeoutSec auf einen Wert größer als Null, aber weniger als 15 Sekunden festlegen, kann es 15 Sekunden oder länger dauern, bis eine WebException ausgelöst wird und bei der Anforderung ein Timeout auftritt.

Parametereigenschaften

Typ:	Int32
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Token

Das OAuth- oder Bearer-Token, das in die Anforderung eingeschlossen werden soll. Der Token ist für bestimmte Authentifizierungsoptionen erforderlich. Sie kann nicht unabhängig verwendet werden.

Token nimmt ein SecureString, das das Token enthält. Wenn Sie das Token bereitstellen möchten, verwenden Sie manuell Folgendes:

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Dieser Parameter wurde in PowerShell 6.0 eingeführt.

Parametereigenschaften

Typ:	SecureString
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-TransferEncoding

Gibt einen Wert für den Transfer-Encoding-Header der HTTP-Antwort an. Die zulässigen Werte für diesen Parameter sind:

In Blöcken aufgeteilt
Komprimieren
Luft ablassen
GZip
Identität

Parametereigenschaften

Typ:	String
Standardwert:	None
Zulässige Werte:	chunked, compress, deflate, gzip, identity
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	Uri
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	0
Obligatorisch:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-UseBasicParsing

Dieser Parameter ist veraltet. Ab PowerShell 6.0.0 verwenden alle Webanforderungen nur die grundlegende Analyse. Dieser Parameter ist nur aus Gründen der Abwärtskompatibilität enthalten, und seine Verwendung hat keine Auswirkungen auf den Betrieb des Cmdlets.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-UseDefaultCredentials

Gibt an, dass das Cmdlet die Anmeldeinformationen des aktuellen Benutzers verwendet, um die Webanforderung zu senden. Dies kann nicht mit Authentifizierung oder Anmeldeinformationen verwendet werden und wird möglicherweise nicht auf allen Plattformen unterstützt.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-UserAgent

Gibt eine Benutzer-Agent-Zeichenfolge für die Webanforderung an.

Der Standardbenutzer-Agent ähnelt Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 mit geringfügigen Variationen für jedes Betriebssystem und jede Plattform.

Um eine Website mit der standardmäßigen User-Agent-Zeichenfolge zu testen, die von den meisten Internetbrowsern verwendet wird, verwenden Sie die Eigenschaften der PSUserAgent-Klasse , z. B. Chrome, FireFox, InternetExplorer, Opera und Safari.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-WebSession

Gibt eine Webanfragesitzung 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 anmeldeinformationen. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung. Inhaltsbezogene Header, z. B Content-Type. , werden ebenfalls überschrieben, wenn ein MultipartFormDataContent-Objekt für Body bereitgestellt wird.

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 es verwenden, um Status und Daten zwischen Webanforderungen auszutauschen.

Um eine Webanforderungssitzung zu erstellen, geben Sie einen Variablennamen ohne Dollarzeichen in den Wert des SessionVariable Parameter 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.

Parametereigenschaften

Typ:	WebRequestSession
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CommonParameters

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

Eingaben

Object

Sie können den Textkörper einer Webanforderung an dieses Cmdlet weiterleiten.

Ausgaben

Int64

Wenn die Anforderung eine ganze Zahl zurückgibt, gibt dieses Cmdlet diese ganze Zahl zurück.

String

Wenn die Anforderung eine Zeichenfolge zurückgibt, gibt dieses Cmdlet diese Zeichenfolge zurück.

XmlDocument

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, der die Daten darstellt.

Hinweise

PowerShell enthält die folgenden Aliase für Invoke-RestMethod:

Alle Plattformen:
- irm

Einige Features sind möglicherweise nicht auf allen Plattformen verfügbar.

Aufgrund von Änderungen in .NET Core 3.1 verwenden PowerShell 7.0 und höher die HttpClient.DefaultProxy-Eigenschaft, um die Proxykonfiguration zu bestimmen.

Der Wert dieser Eigenschaft ist je nach Plattform unterschiedlich:

Für Windows: Liest die Proxy-Konfiguration aus Umgebungsvariablen oder, falls diese nicht definiert sind, aus den Proxy-Einstellungen des Benutzers.
Für macOS: Liest die Proxy-Konfiguration aus Umgebungsvariablen oder, falls diese nicht definiert sind, aus den Proxy-Einstellungen des Systems.
Für Linux: Liest die Proxy-Konfiguration aus Umgebungsvariablen oder, falls diese nicht definiert sind, initialisiert diese Eigenschaft eine nicht konfigurierte Instanz, die alle Adressen umgeht.

Die Umgebungsvariablen, die für DefaultProxy Initialisierung auf Windows- und Unix-basierten Plattformen verwendet werden, sind:

HTTP_PROXY: der Hostname oder die IP-Adresse des Proxyservers, der für HTTP-Anforderungen verwendet wird.
HTTPS_PROXY: der Hostname oder die IP-Adresse des Proxyservers, der für HTTPS-Anforderungen verwendet wird.
ALL_PROXY: Der Hostname oder die IP-Adresse des Proxy-Servers, die für HTTP- und HTTPS-Anfragen verwendet werden, falls HTTP_PROXY oder HTTPS_PROXY nicht definiert sind.
NO_PROXY: eine durch Trennzeichen getrennte Liste von Hostnamen, die von der Proxyerstellung ausgeschlossen werden sollten.

Freigeben über

Invoke-RestMethod

Syntax

StandardMethod (Standard)

StandardMethodNoProxy

CustomMethod

CustomMethodNoProxy

Beschreibung

Beispiele

Beispiel 1: Abrufen des PowerShell-RSS-Feeds

Beispiel 2: Ausführen einer POST-Anforderung

Beispiel 3: Folgen Sie den Beziehungslinks

Beispiel 4: Vereinfachte Multipart/Formular-Daten-Übermittlung

Beispiel 5: Übergeben mehrerer Header

Beispiel 6: Aufzählen zurückgegebener Elemente in der Pipeline

Beispiel 7: Überspringen der Headerüberprüfung

Beispiel 8: Senden einer Anforderung mit HTTP 2.0

Parameter

-AllowUnencryptedAuthentication

Parametereigenschaften

Parametersätze

-Authentication

Parametereigenschaften

Parametersätze

-Body

Parametereigenschaften

Parametersätze

-Certificate

Parametereigenschaften

Parametersätze

-CertificateThumbprint

Parametereigenschaften

Parametersätze

-ContentType

Parametereigenschaften

Parametersätze

-Credential

Parametereigenschaften

Parametersätze

-CustomMethod

Parametereigenschaften

Parametersätze

-DisableKeepAlive

Parametereigenschaften

Parametersätze

-FollowRelLink

Parametereigenschaften

Parametersätze

-Form

Parametereigenschaften

Parametersätze

-Headers

Parametereigenschaften

Parametersätze

-HttpVersion

Parametereigenschaften

Parametersätze

-InFile

Parametereigenschaften

Parametersätze

-MaximumFollowRelLink

Parametereigenschaften

Parametersätze

-MaximumRedirection

Parametereigenschaften

Parametersätze

-MaximumRetryCount

Parametereigenschaften

Parametersätze

-Method

Parametereigenschaften

Parametersätze

-NoProxy

Parametereigenschaften

Parametersätze

-OutFile

Parametereigenschaften

Parametersätze

-PassThru

Parametereigenschaften