Invoke-RestMethod
Sendet eine HTTP- oder HTTPS-Anforderung an einen RESTful-Webdienst.
Syntax
Invoke-RestMethod
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
[-Method <WebRequestMethod>]
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Invoke-RestMethod
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
[-Method <WebRequestMethod>]
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-NoProxy]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Invoke-RestMethod
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
-CustomMethod <String>
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Invoke-RestMethod
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
-CustomMethod <String>
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-NoProxy]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<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.
Ab PowerShell 7.0 unterstützt die Proxykonfiguration, Invoke-RestMethod die von Umgebungsvariablen definiert wird. Weitere Informationen finden Sie im Abschnitt "Hinweise " dieses Artikels.
Ab PowerShell 7.4 ist die Zeichencodierung für Anforderungen standardmäßig auf UTF-8 anstelle von ASCII festgelegt. Wenn Sie eine andere Codierung benötigen, müssen Sie das charset Attribut in der Content-Type Kopfzeile festlegen.
Beispiele
Beispiel 1: Abrufen des PowerShell-RSS-Feeds
In diesem Beispiel wird das Invoke-RestMethod Cmdlet verwendet, 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.
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 +0000Beispiel 2: Ausführen einer POST-Anforderung
In diesem Beispiel führt Invoke-RestMethod ein Benutzer eine POST-Anforderung auf einer Intranetwebsite in der Organisation des Benutzers aus.
$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.csvDie Anmeldeinformationen werden aufgefordert und dann gespeichert$Cred, und die URL, auf die zugegriffen werden soll, wird definiert.$Url
Die $Body Variable 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 kommuniziert wird.
Der Invoke-RestMethod Befehl wird mit allen Variablen ausgeführt und gibt einen Pfad und Dateinamen für die resultierende CSV-Ausgabedatei an.
Beispiel 3: Folgen von Beziehungslinks
Einige REST-APIs unterstützen die Paginierung über Relationslinks pro 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 2Beispiel 4: Vereinfachte mehrteilige/Formulardatenü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 $FormDas Profilformular erfordert folgende Felder: firstName, , lastName, email, avatar, , birthdayund hobbies. Die API erwartet, dass ein Bild für das Benutzerprofilbild im avatar Feld bereitgestellt wird. Die API akzeptiert auch mehrere hobbies Einträge, die in demselben Formular übermittelt werden sollen.
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 Auflistung wie Arrays oder Listen vorhanden sind, wird das Formularfeld mehrmals übermittelt.
Get-Item Mithilfe des avatar Schlüssels wird das FileInfo Objekt als Wert festgelegt. Das Ergebnis ist, dass die Bilddaten jdoe.png übermittelt werden.
Durch Angeben einer Liste an den hobbies Schlüssel ist das hobbies Feld einmal in den Übermittlungen für jedes Listenelement vorhanden.
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 von einer hash-table an eine REST-API übergeben werden.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $bodyBeispiel 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 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
30Beispiel 7: Überspringen der Headerüberprüfung
Standardmäßig überprüft das Invoke-RestMethod Cmdlet die Werte bekannter Header, die ein standardsdefiniertes Wertformat aufweisen. 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 Anforderungsheader If-Match wird in RFC-7232 Abschnitt 3.1 definiert und erfordert, dass der Wert für diesen Header mit umgebenden Anführungszeichen definiert wird. Der $InvalidHeaders Variablen wird eine Hashtabelle zugewiesen, bei der der Wert If-Match ungültig ist, da sie anstelle 12345 von "12345".
Das Aufrufen Invoke-RestMethod mit den ungültigen Headern gibt eine Fehlerberichterstattung zurück, dass der formatierte Wert ungültig ist. Die Anforderung wird nicht an den Endpunkt gesendet.
Das Aufrufen Invoke-RestMethod mit dem Parameter SkipHeaderValidation 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 -SkipCertificateCheckBeispiel 9: Senden einer Anforderung an eine Unix-Socketanwendung
Einige Anwendungen, z. B. Docker, machen einen Unix-Socket für die Kommunikation verfügbar. In diesem Beispiel wird eine Liste von Docker-Images mithilfe der Docker-API abfragen. Das Cmdlet stellt mithilfe des Unix-Sockets eine Verbindung mit dem Docker-Daemon bereit.
Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"Parameter
-AllowInsecureRedirect
Ermöglicht die Umleitung von HTTPS zu HTTP. Standardmäßig führt jede Anforderung, die von HTTPS zu HTTP umgeleitet wird, zu einem Fehler und die Anforderung wird abgebrochen, um unbeabsichtigte Kommunikation in Nur-Text über unverschlüsselte Verbindungen zu verhindern. Um dieses Verhalten auf eigenes Risiko außer Kraft zu setzen, verwenden Sie den Parameter AllowInsecureRedirect .
Dieser Parameter wurde in PowerShell 7.4 hinzugefügt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-AllowUnencryptedAuthentication
Ermöglicht das Senden von Anmeldeinformationen und geheimen Schlüsseln über unverschlüsselte Verbindungen. Standardmäßig führt das Bereitstellen von Anmeldeinformationen oder einer Authentifizierungsoption mit einem URI, der nicht beginnthttps://, zu einem Fehler, und die Anforderung wird abgebrochen, um unbeabsichtigte Kommunikation geheimer Schlüssel im Nur-Text über unverschlüsselte Verbindungen zu verhindern. Um dieses Verhalten auf eigenes Risiko außer Kraft zu setzen, geben Sie den Parameter AllowUnencryptedAuthentication an.
Warnung
Die Verwendung dieses Parameters ist nicht sicher und wird nicht empfohlen. Es wird nur zur Kompatibilität mit älteren 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.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-Authentication
Gibt den expliziten Authentifizierungstyp an, der für die Anforderung verwendet werden soll. Der Standardwert ist None (Kein). Der Authentifizierungsparameter 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-HeaderAuthorization: Basicim Format vonbase64(user:password).Bearer: Erfordert den Token-Parameter . Sendet einen RFC 6750-HeaderAuthorization: Bearermit dem bereitgestellten Token.OAuth: Erfordert den Token-Parameter . Sendet einen RFC 6750-HeaderAuthorization: Bearermit dem bereitgestellten Token.
Durch die Bereitstellung der Authentifizierung werden alle Authorization Header außer Kraft gesetzt, die für Header bereitgestellt oder in WebSession enthalten sind.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
| Typ: | WebAuthenticationType |
| Zulässige Werte: | None, Basic, Bearer, OAuth |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-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. Für Abfrageparameter verwendet das Cmdlet die System.Net.WebUtility.UrlEncode-Methode , um die Schlüsselwertpaare zu codieren. Weitere Informationen zur Codierung von Zeichenfolgen für URLs finden Sie in der UrlEncode()-Methodenreferenz.
Wenn es sich bei der Eingabe um eine POST-Anforderung handelt und der Textkörper eine Zeichenfolge ist, wird der Wert links neben dem ersten Gleichheitszeichen (=) als Schlüssel in den Formulardaten festgelegt, und der verbleibende Text wird als Wert festgelegt. Verwenden Sie zum Angeben mehrerer Schlüssel ein IDictionary-Objekt , z. B. eine Hashtabelle, für den Textkörper.
Wenn es sich bei der Eingabe um eine GET-Anforderung handelt und der Textkörper ein IDictionary (in der Regel eine Hashtabelle) ist, wird der Textkörper als Abfrageparameter dem URI hinzugefügt. Bei anderen Anforderungstypen (z. B. PATCH) wird der Textkörper als Wert des Anforderungstexts im Standardformat name=value mit den Werten URL-codiert festgelegt.
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 überschrieben.
Wenn der Textkörper ein Formular ist oder die Ausgabe eines anderen Invoke-WebRequest Aufrufs ist, legt PowerShell den Anforderungsinhalt auf die Formularfelder fest.
Der Body-Parameter kann auch ein System.Net.Http.MultipartFormDataContent-Objekt akzeptieren. Dies erleichtert multipart/form-data Anforderungen. Wenn ein MultipartFormDataContent-Objekt für "Body" bereitgestellt wird, werden alle inhaltsbezogenen Header, die den Parametern ContentType, Headers oder WebSession bereitgestellt werden, von den Inhaltsheadern des MultipartFormDataContent Objekts überschrieben. Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
| 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 nicht über ausreichende Autorität verfügt, schlägt der Befehl fehl.
| 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.
Hinweis
Dieses Feature wird derzeit nur auf Windows-Betriebssystemplattformen unterstützt.
| Typ: | String |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-ConnectionTimeoutSeconds
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 "ConnectionTimeoutSeconds" auf einen Wert größer als 0 festlegen, aber weniger als 15 Sekunden, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird, und die Zeitüberschreitung der Anforderung.
Dieser Parameter ersetzte den TimeoutSec-Parameter in PowerShell 7.4. Sie können TimeoutSec als Alias für ConnectionTimeoutSeconds verwenden.
| Typ: | Int32 |
| Aliase: | TimeoutSec |
| Position: | Named |
| Standardwert: | 0 |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-ContentType
Gibt den Inhaltstyp der Webanforderung an.
Wenn der Wert für ContentType das Codierungsformat (as 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 einen 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, Invoke-RestMethod wird der Inhaltstyp auf application/x-www-form-urlencoded. Andernfalls wird der Inhaltstyp nicht im Aufruf angegeben.
ContentType wird überschrieben, wenn ein MultipartFormDataContent Objekt für Body bereitgestellt wird.
Ab PowerShell 7.4 wird der im ContentType-Parameter angegebene Wert verwendet, wenn Sie diesen Parameter und den Headerparameter verwenden, um den Content-Type Header zu definieren.
| 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 können allein oder in Verbindung mit bestimmten Authentifizierungsparameteroptionen verwendet werden. Wenn sie allein verwendet wird, werden nur Anmeldeinformationen für den Remoteserver angegeben, wenn der Remoteserver eine Anforderung an Authentifizierungsabfragen 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 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 |
-CustomMethod
Gibt die benutzerdefinierte Methode an, die für die Webanforderung verwendet wird. Dies kann mit der vom Endpunkt erforderlichen Anforderungsmethode verwendet werden, ist keine verfügbare Option für die Methode. Methode 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.
| Typ: | String |
| Aliase: | CM |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | True |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-DisableKeepAlive
Gibt an, dass das Cmdlet den KeepAlive-Wert im HTTP-Header auf False festlegt. "KeepAlive" ist standardmäßig "True". KeepAlive stellt eine dauerhafte Verbindung mit dem Server her, um nachfolgende Anforderungen zu erleichtern.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-FollowRelLink
Gibt an, dass das Cmdlet Beziehungslinks folgen soll.
Einige REST-APIs unterstützen die Paginierung über Relationslinks pro 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 Parameter "MaximumFollowRelLink ", 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.
| Typ: | SwitchParameter |
| Aliase: | FL |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-Form
Konvertiert ein Wörterbuch in eine multipart/form-data Übermittlung. Das Formular kann nicht mit Textkörper verwendet werden.
Wenn ContentType ignoriert wird.
Die Schlüssel des Wörterbuchs werden als Formularfeldnamen verwendet. Standardmäßig werden Formularwerte in Zeichenfolgenwerte konvertiert.
Wenn der Wert ein System.IO.FileInfo-Objekt ist, wird der Inhalt der Binärdatei übermittelt.
Der Name der Datei wird als .filename Die MIME wird als application/octet-stream. Get-Item kann verwendet werden, um die Bereitstellung des System.IO.FileInfo-Objekts zu vereinfachen.
$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
Wenn der Wert ein Sammlungstyp ist, z. B. ein Array oder eine Liste, wird das Feld mehrmals übermittelt. Die Werte der Liste werden standardmäßig als Zeichenfolgen behandelt. Wenn der Wert ein System.IO.FileInfo-Objekt ist, wird der Inhalt der Binärdatei übermittelt. Geschachtelte Sammlungen werden nicht unterstützt.
$Form = @{ tags = 'Urlaub', 'Italien', '2017' Bilder = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
Im obigen Beispiel wird das tags Feld dreimal im Formular angegeben, einmal für jedes von Vacation, Italyund 2017. Das pictures Feld wird auch einmal für jede Datei im 2017-Italy Ordner übermittelt. Der binäre Inhalt der Dateien in diesem Ordner wird als Werte übermittelt.
Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.
| Typ: | IDictionary |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-Headers
Gibt die Header der Webanforderung an. Geben Sie eine Hashtabelle oder ein Wörterbuch ein.
Inhaltsbezogene Kopfzeilen, z Content-Type . B. werden überschrieben, wenn ein MultipartFormDataContent Objekt für Textkörper bereitgestellt wird.
Ab PowerShell 7.4 wird der im ContentType-Parameter angegebene Wert verwendet, wenn Sie diesen Parameter verwenden, um den Content-Type Header zu definieren und den ContentType-Parameter zu verwenden.
| Typ: | IDictionary |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-HttpVersion
Gibt die HTTP-Version an, die für die Anforderung verwendet wird. Der Standardwert ist 1.1.
Gültige Werte sind:
- 1.0
- 1.1
- 2.0
- 3.0
| Typ: | Version |
| 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 |
-MaximumFollowRelLink
Gibt an, wie oft Beziehungslinks befolgt werden sollen, wenn FollowRelLink verwendet wird. Ein kleinerer Wert kann erforderlich sein, wenn die REST-API aufgrund zu vieler Anforderungen drosselt. Der Standardwert ist [Int32]::MaxValue. Ein Wert von 0 (Null) verhindert die folgenden Beziehungslinks.
| Typ: | Int32 |
| Aliase: | ML |
| Position: | Named |
| Standardwert: | Int32.MaxValue |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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. Der Wert 0 (null) unterbindet sämtliche Umleitungen.
| Typ: | Int32 |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-MaximumRetryCount
Gibt an, wie oft PowerShell eine Verbindung wiederholt, wenn ein Fehlercode zwischen 400 und 599 (einschließlich) oder 304 empfangen wird. Siehe auch den Parameter "RetryIntervalSec ", um das Intervall zwischen Wiederholungen anzugeben.
| Typ: | Int32 |
| Position: | Named |
| Standardwert: | None |
| 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:
DefaultDeleteGetHeadMergeOptionsPatchPostPutTrace
Der Parameter CustomMethod kann für Anforderungsmethoden verwendet werden, die oben nicht aufgeführt sind.
| Typ: | WebRequestMethod |
| Zulässige Werte: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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 diesen Switch.
Dieser Parameter wurde in PowerShell 6.0 eingeführt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | True |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-OperationTimeoutSeconds
Dieses Timeout gilt für Datenlesevorgänge innerhalb eines Datenstroms, nicht für die gesamte Datenstromzeit. Der Standardwert 0 gibt ein unbestimmtes Timeout an.
Das Festlegen des Werts auf 30 Sekunden bedeutet, dass eine Verzögerung von mehr als 30 Sekunden zwischen Daten im Datenstrom die Anforderung beendet. Eine große Datei, die mehrere Minuten zum Herunterladen dauert, wird erst beendet, wenn der Datenstrom länger als 30 Sekunden dauert.
| Typ: | Int32 |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-OutFile
Gibt standardmäßig Invoke-RestMethod die Ergebnisse an die Pipeline zurück. Wenn Sie den Parameter OutFile verwenden, werden die Ergebnisse in der angegebenen Datei gespeichert und nicht an die Pipeline zurückgegeben. Geben Sie einen Pfad und Dateinamen ein. Um die Ergebnisse an eine Datei und an die Pipeline zu senden, fügen Sie den PassThru-Parameter hinzu.
Wenn Sie den Pfad weglassen, wird der aktuelle Speicherort als Standard verwendet. Der Name wird als Literalpfad behandelt.
Namen, die eckige Klammern ([]) enthalten, müssen in einfache Anführungszeichen (') eingeschlossen werden.
Ab PowerShell 7.4 können Sie einen Ordnerpfad ohne dateinamen angeben. Wenn Sie dies tun, verwendet der Befehl den Dateinamen aus dem letzten Segment des aufgelösten URI nach allen Umleitungen. Wenn Sie einen Ordnerpfad für OutFile angeben, können Sie den Parameter Resume nicht verwenden.
| 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 wird jedoch nicht erstellt. Dies wurde in PowerShell 7.5-preview.4 behoben. Weitere Informationen finden Sie unter PowerShell-Problem Nr. 15409.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | No output |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-PreserveAuthorizationOnRedirect
Gibt an, dass das Cmdlet den Authorization Header beibehalten soll, wenn vorhanden, über Umleitungen hinweg.
Standardmäßig entfernt das Cmdlet die Authorization Kopfzeile vor der Umleitung. Wenn Sie diesen Parameter angeben, wird diese Logik für Fälle deaktiviert, in denen der Header an den Umleitungsspeicherort gesendet werden muss.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-PreserveHttpMethodOnRedirect
Gibt an, dass das Cmdlet die Methode der Anforderung über Umleitungen beibehalten soll.
Standardmäßig ändert das Cmdlet die Methode GET , wenn sie umgeleitet wird. Wenn Sie diesen Parameter angeben, wird diese Logik deaktiviert, um sicherzustellen, dass die beabsichtigte Methode mit Umleitung verwendet werden kann.
Dieses Feature wurde in PowerShell 7.4 hinzugefügt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| 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 (Uniform Resource Identifier) eines Netzwerkproxyservers ein.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
| 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", User@Domain.Comoder geben Sie ein Objekt ein, z. B. einenPSCredential, der Get-Credential vom Cmdlet generiert wurde.
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: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-ProxyUseDefaultCredentials
Gibt an, dass das Cmdlet die Anmeldeinformationen des aktuellen Benutzers verwendet, um auf den Proxyserver zuzugreifen, der durch den 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: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-ResponseHeadersVariable
Erstellt eine Variable, die ein Antwortheaderwö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.
| Typ: | String |
| Aliase: | RHV |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-Resume
Führt einen best effort-Versuch aus, das Herunterladen einer Teildatei fortzusetzen. Der Resume-Parameter erfordert den OutFile-Parameter .
"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 als die Remotedateigröße ist, versucht das Cmdlet, den Download der Datei fortzusetzen und die verbleibenden Bytes am 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 Dateigröße größer als die Remotedatei ist, wird die lokale Datei überschrieben, und die gesamte Remotedatei wird vollständig erneut heruntergeladen. Dieses Verhalten entspricht der Verwendung von OutFile ohne Lebenslauf.
Wenn der Remoteserver das Fortsetzen des Downloads nicht unterstützt, wird die lokale Datei überschrieben, und die gesamte Remotedatei wird vollständig erneut heruntergeladen. Dieses Verhalten entspricht der Verwendung von OutFile ohne Lebenslauf.
Wenn die lokale Datei nicht vorhanden ist, wird die lokale Datei erstellt, und die gesamte Remotedatei wird vollständig heruntergeladen. Dieses Verhalten entspricht der Verwendung von OutFile ohne Lebenslauf.
Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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]::MaxValue.
Wenn der Fehlercode 429 ist und die Antwort die Retry-After-Eigenschaft in den Headern enthält, verwendet das Cmdlet diesen Wert für das Wiederholungsintervall, auch wenn dieser Parameter angegeben ist.
Siehe auch den Parameter MaximumRetryCount zum Angeben der Anzahl von Wiederholungen.
| Typ: | Int32 |
| Position: | Named |
| Standardwert: | 5 |
| 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.
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 das Objekt verwenden, um den Zustand und die Daten übergreifend für Webanforderungen zu nutzen.
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 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 |
-SkipCertificateCheck
Überspringt Zertifikatüberprüfungen, die alle Überprüfungen umfassen, z. B. Ablauf, Sperrung, vertrauenswürdige Stammzertifizierungsstelle usw.
Warnung
Die Verwendung dieses Parameters ist nicht sicher und wird nicht empfohlen. Dieser Switch soll nur für bekannte Hosts mit einem selbstsignierten Zertifikat zu Testzwecken verwendet werden. Verwenden Sie auf eigenes Risiko.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-SkipHeaderValidation
Gibt an, dass das Cmdlet der Anforderung ohne Überprüfung Header hinzufügen soll.
Dieser Switch sollte für Websites verwendet werden, für die Headerwerte erforderlich sind, die nicht den Standards entsprechen. Wenn Sie diesen Schalter angeben, wird die Überprüfung deaktiviert, damit der Wert deaktiviert wird. Wenn angegeben, werden alle Header ohne Überprüfung hinzugefügt.
Dadurch wird die Überprüfung für Werte deaktiviert, die an die Parameter "ContentType", "Header" und "UserAgent " übergeben werden.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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 das Einschränken auf bestimmte Protokolle für Compliancezwecke.
Diese Werte werden als flagbasierte Enumeration definiert. Sie können mehrere Werte kombinieren, um mehrere Flags mithilfe dieses Parameters festzulegen. Die Werte können als Array von Werten oder als kommagetrennte Zeichenfolge dieser Werte an den SslProtocol-Parameter ü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 des Tabstopps 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, sie oder Tls12 als Option zu liefernTls. 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 dieses Feature wurde in PowerShell 7.1 hinzugefügt.
| Typ: | WebSslProtocol |
| Zulässige Werte: | Default, Tls, Tls11, Tls12, Tls13 |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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 ein, z -StatusCodeVariable "scv". B. .
Dieser Parameter wurde in PowerShell 7 eingeführt.
| Typ: | String |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-Token
Das OAuth- oder Bearer-Token, das in die Anforderung eingeschlossen werden soll. Token ist für bestimmte Authentifizierungsoptionen erforderlich. Sie kann nicht unabhängig verwendet werden.
Token akzeptiert ein SecureString Token, 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.
| Typ: | SecureString |
| Position: | Named |
| Standardwert: | None |
| 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:
- Segmentiert
- Komprimieren
- Deflate
- GZip
- Identität
| Typ: | String |
| Zulässige Werte: | chunked, compress, deflate, gzip, identity |
| Position: | Named |
| Standardwert: | None |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | False |
-UnixSocket
Gibt den Namen des Unix-Sockets an, mit dem eine Verbindung hergestellt werden soll. Dieser Parameter wird auf Unix-basierten Systemen und Windows Version 1803 und höher unterstützt. Weitere Informationen zur Windows-Unterstützung von Unix-Sockets finden Sie im Windows/WSL Interop mit AF_UNIX Blogbeitrag.
Dieser Parameter wurde in PowerShell 7.4 hinzugefügt.
| Typ: | UnixDomainSocketEndPoint |
| 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
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 jede Verwendung hat keine Auswirkungen auf den Vorgang des Cmdlets.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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.
| Typ: | SwitchParameter |
| Position: | Named |
| Standardwert: | False |
| Erforderlich: | False |
| Pipelineeingabe akzeptieren: | False |
| Platzhalterzeichen akzeptieren: | 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 geringfügigen Abweichungen für jedes Betriebssystem und jede Plattform.
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, InternetExplorer, 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. Inhaltsbezogene Kopfzeilen, z Content-Type. B. , werden auch überschrieben, wenn ein MultipartFormDataContent-Objekt für Textkörper 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 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
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: Die Proxykonfiguration wird aus den Umgebungsvariablen gelesen, sofern definiert. Andernfalls wird sie aus den Proxyeinstellungen des Benutzers gelesen.
- Für macOS: Die Proxykonfiguration wird aus den Umgebungsvariablen gelesen, sofern definiert. Andernfalls wird sie aus den Proxyeinstellungen des Systems gelesen.
- Für Linux: Die Proxykonfiguration wird aus den Umgebungsvariablen gelesen, sofern definiert. Andernfalls initialisiert diese Eigenschaft eine nicht konfigurierte Instanz, die alle Adressen umgeht.
Für die Initialisierung von DefaultProxy auf Windows- und Unix-basierten Plattformen werden folgende Umgebungsvariablen verwendet:
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 Proxyservers, der für HTTP- und HTTPS-Anforderungen verwendet wird, fallsHTTP_PROXYoderHTTPS_PROXYnicht definiert sind.NO_PROXY: Eine durch Trennzeichen getrennte Liste mit Hostnamen, die aus der Proxyfunktion ausgeschlossen werden sollen.
PowerShell 7.4 hat Unterstützung für den Brotli-Komprimierungsalgorithmus hinzugefügt.
