Invoke-RestMethod
Sendet eine HTTP- oder HTTPS-Anforderung an einen RESTful-Webdienst.
Syntax
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-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]
[-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>]
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-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]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-RestMethod
-CustomMethod <String>
[-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]
[-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>]
Invoke-RestMethod
-CustomMethod <String>
[-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]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Beschreibung
Das Invoke-RestMethod
Cmdlet sendet HTTP- und HTTPS-Anforderungen an REST-Webdienste (Representational State Transfer), die reich strukturierte Daten zurückgeben.
PowerShell formatiert die Antwort basierend auf dem Datentyp. Für einen RSS- oder ATOM-Feed gibt PowerShell die XML-Knoten Element oder Eintrag zurück. Für 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 von Invoke-RestMethod
an einen anderen Befehl übergeben, wird sie als einzelnes [Object[]]
Objekt gesendet. Der Inhalt dieses Arrays wird nicht für den nächsten Befehl in der Pipeline aufgelistet.
Dieses Cmdlet wird in Windows PowerShell 3.0 eingeführt.
Ab PowerShell 7.0 werden Proxykonfigurationen unterstützt, Invoke-RestMethod
die durch Umgebungsvariablen definiert werden. Weitere Informationen finden Sie im Abschnitt Notizen dieses Artikels.
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 +0000
Beispiel 2: Ausführen einer POST-Anforderung
In diesem Beispiel führt Invoke-RestMethod
ein Benutzer eine POST-Anforderung auf einer Intranetwebsite im organization 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.csv
Die Anmeldeinformationen werden zur Eingabe aufgefordert und dann in $Cred
gespeichert, und die URL, auf die zugriff erfolgen soll, wird in $Url
definiert.
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 jeweilige REST-API gelten, mit der kommuniziert Invoke-RestMethod
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 Beziehungslinks pro RFC5988. Anstatt den Header zu analysieren, um die URL für die nächste Seite abzurufen, können Sie dies vom Cmdlet für Sie ausführen lassen. 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 mehrteilige/Formulardatenübermittlung
Einige APIs erfordern multipart/form-data
Übermittlungen, um Dateien und gemischte Inhalte hochzuladen. 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
Für das Profilformular sind die folgenden Felder erforderlich: firstName
, lastName
, email
, avatar
, birthday
und 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 derselben Form ü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 Sammlung wie Arrays oder Listen vorhanden ist, wird das Formularfeld mehrmals übermittelt.
Get-Item
Mithilfe des Schlüssels avatar
wird das FileInfo
Objekt als Wert festgelegt. Das Ergebnis ist, dass die Bilddaten für jdoe.png
übermittelt werden.
Durch Das Bereitstellen einer Liste für den hobbies
Schlüssel wird das hobbies
Feld einmal für jedes Listenelement in den Übermittlungen vorhanden.
Beispiel 5: Übergeben mehrerer Header
APIs erfordern häufig übergebene Header für die Authentifizierung oder Überprüfung. In diesem Beispiel wird veranschaulicht, wie mehrere Header von einer hash-table
an eine REST-API übergeben werden.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
Beispiel 6: Auflisten zurückgegebener Elemente in der Pipeline
GitHub gibt mehrere Objekte eines Arrays zurück. Wenn Sie die Ausgabe an einen anderen Befehl übergeben, wird sie als einzelnes [Object[]]
Objekt gesendet.
Um die Objekte in der Pipeline aufzulisten, leiten Sie die Ergebnisse an das Cmdlet weiter, Write-Output
oder umschließen Sie sie in Klammern. Im folgenden Beispiel wird die Anzahl der von GitHub zurückgegebenen Objekte gezählt. Zählt dann die Anzahl der Objekte, die für die Pipeline aufgelistet sind.
$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 ein standardards-definiertes 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 die Überprüfung von Werten für Endpunkte zu vermeiden, 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 Header einer Anforderung als Inhalt der Antwort zurückgibt.
Der Anforderungsheader If-Match
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
Variablen wird eine Hashtabelle zugewiesen, in der der Wert von If-Match
ungültig ist, da er als 12345
anstelle von "12345"
definiert ist.
Das Aufrufen Invoke-RestMethod
mit den ungültigen Headern gibt einen Fehler zurück, der meldet, 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 Validierungsfehler 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 mithilfe von HTTP 2.0
In diesem Beispiel wird das GitHub-Problem mithilfe des HTTP 2.0-Protokolls abfragt.
$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 Geheimnissen über unverschlüsselte Verbindungen. Standardmäßig führt die Angabe von Anmeldeinformationen oder einer beliebigen Authentifizierungsoption mit einem URI , der nicht mit https://
beginnt, zu einem Fehler, und die Anforderung wird abgebrochen, um zu verhindern, dass geheimnisse ungewollt im Nur-Text über unverschlüsselte Verbindungen kommuniziert werden. Um dieses Verhalten auf eigenes Risiko zu überschreiben, geben Sie den Parameter AllowUnencryptedAuthentication an .
Warnung
Die Verwendung dieses Parameters ist nicht sicher und wird nicht empfohlen. Sie wird nur zur Kompatibilität mit Legacysystemen bereitgestellt, die keine verschlüsselten Verbindungen bereitstellen können. Die Verwendung erfolgt auf eigene Gefahr.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Authentication
Gibt den expliziten Authentifizierungstyp an, der für die Anforderung verwendet werden soll. Der Standardwert ist None (Kein). Der Authentication-Parameter 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: Basic
im Formatbase64(user:password)
zu senden.Bearer
: Erfordert den Token-Parameter . Sendet einen RFC 6750-HeaderAuthorization: Bearer
mit dem angegebenen Token.OAuth
: Erfordert den Token-Parameter . Sendet einen RFC 6750-HeaderAuthorization: Bearer
mit dem angegebenen Token.
Die Angabe der Authentifizierung überschreibt alle Authorization
Header, die für Header bereitgestellt oder in WebSession enthalten sind.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | WebAuthenticationType |
Accepted values: | None, Basic, Bearer, OAuth |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Body
Gibt den Anforderungstext an. Der Text entspricht dem Inhalt der Anforderung, der auf die Header folgt.
Sie können auch einen Textwert an übergeben Invoke-RestMethod
.
Der Body-Parameter kann verwendet werden, um eine Liste von Abfrageparametern oder den Inhalt der Antwort anzugeben.
Wenn die Eingabe eine POST-Anforderung ist und der Text eine Zeichenfolge ist, wird der Wert links vom 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 , z. B. eine Hashtabelle, für den Text.
Wenn es sich bei der Eingabe um eine GET-Anforderung handelt und der Text ein IDictionary (in der Regel eine Hashtabelle) ist, wird der Text dem URI als Abfrageparameter hinzugefügt. Bei anderen Anforderungstypen (z. B. PATCH) wird der Text als Wert des Anforderungstexts im Standardformat name=value
mit den Werten URL-codiert festgelegt.
Wenn die Eingabe ein System.Xml ist. XmlNode-Objekt und die XML-Deklaration geben eine Codierung an, die für die Daten in der Anforderung verwendet wird, es sei denn, der ContentType-Parameter überschreibt.
Wenn der Text ein Formular 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 für die Parameter ContentType, Headers oder WebSession bereitgestellt werden, von den Inhaltsheadern des MultipartFormDataContent
Objekts überschrieben. Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Certificate
Gibt das Clientzertifikat an, das für eine sichere Webanforderung verwendet wird. Geben Sie eine Variable ein, die ein Zertifikat, einen Befehl oder einen Ausdruck enthält, durch die das Zertifikat abgerufen wird.
Um ein Zertifikat zu finden, verwenden Sie Get-PfxCertificate
das Get-ChildItem
Cmdlet im Laufwerk Zertifikat (Cert:
) oder verwenden Sie es. Wenn das Zertifikat ungültig ist oder nicht über eine ausreichende Autorität verfügt, schlägt der Befehl fehl.
Type: | X509Certificate |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
Gibt das digitale Zertifikat für öffentliche Schlüssel (X509) eines Benutzerkontos an, das über die Berechtigung zum Senden der Anforderung verfügt. Geben Sie den Zertifikatfingerabdruck des Zertifikats ein.
Zertifikate werden bei der clientzertifikatbasierten Authentifizierung verwendet. Zertifikate können nur lokalen Benutzerkonten und nicht Domänenkonten zugeordnet werden.
Um den Zertifikatfingerabdruck anzuzeigen, verwenden Sie den Get-Item
Befehl oder Get-ChildItem
, um das Zertifikat in Cert:\CurrentUser\My
zu suchen.
Hinweis
Dieses Feature wird derzeit nur auf Windows-Betriebssystemplattformen unterstützt.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ContentType
Gibt den Inhaltstyp der Webanforderung an.
Wenn der Wert für ContentType das Codierungsformat (als charset
) enthält, verwendet das Cmdlet dieses Format, um den Text der Webanforderung zu codieren. Wenn 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
legt den Inhaltstyp auf fest 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.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Credential
Gibt ein Benutzerkonto an, das über die Berechtigung zum Senden der Anforderung verfügt. Der Standardwert ist der aktuelle Benutzer.
Geben Sie einen Benutzernamen ein, z. B. User01 oder Domain01\User01, oder geben Sie ein vom Get-Credential
Cmdlet generiertes PSCredential-Objekt ein.
Anmeldeinformationen können allein oder in Verbindung mit bestimmten Authentifizierungsparameteroptionen verwendet werden. Bei alleiniger Verwendung werden nur Anmeldeinformationen an den Remoteserver bereitgestellt, wenn der Remoteserver eine Anforderung zur 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 zum Schutz von SecureString-Daten finden Sie unter Wie sicher ist SecureString?.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | String |
Aliases: | CM |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-DisableKeepAlive
Gibt an, dass das Cmdlet den KeepAlive-Wert im HTTP-Header auf False festlegt. Der Standardwert von KeepAlive ist „True“. KeepAlive richtet eine persistente Verbindung mit dem Server ein, um nachfolgende Anforderungen zu erleichtern.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FollowRelLink
Gibt an, dass das Cmdlet Beziehungslinks folgen soll.
Einige REST-APIs unterstützen die Paginierung über Beziehungslinks pro RFC5988. Anstatt die Kopfzeile zu analysieren, um die URL für die nächste Seite abzurufen, können Sie das Cmdlet für Sie ausführen lassen. Verwenden Sie den Parameter MaximumFollowRelLink , um festzulegen, wie oft beziehungsverknüpft werden soll.
Bei Verwendung dieses Schalters gibt das Cmdlet eine Sammlung von Ergebnisseiten zurück. Jede Ergebnisseite kann mehrere Ergebniselemente enthalten.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | SwitchParameter |
Aliases: | FL |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Form
Konvertiert ein Wörterbuch in eine multipart/form-data
Übermittlung. Formular darf nicht mit Body 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
übermittelt. Der MIME wird auf application/octet-stream
festgelegt. 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 für 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 = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
Im obigen Beispiel wird das tags
Feld dreimal im Formular bereitgestellt, einmal für jede von Vacation
, Italy
und 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.
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Headers
Gibt die Header der Webanforderung an. Geben Sie eine Hashtabelle oder ein Wörterbuch ein.
Inhaltsbezogene Header, z Content-Type
. B. werden überschrieben, wenn ein MultipartFormDataContent
Objekt für Body bereitgestellt wird.
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-HttpVersion
Gibt die für die Anforderung verwendete HTTP-Version an. Der Standardwert lautet 1.1
.
Gültige Werte sind:
- 1.0
- 1.1
- 2.0
- 3.0
Type: | Version |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InFile
Ruft den Inhalt der Webanforderung aus einer Datei ab.
Geben Sie einen Pfad- und Dateinamen ein. Wenn Sie den Pfad weglassen, wird der aktuelle Speicherort als Standard verwendet.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumFollowRelLink
Gibt an, wie oft Beziehungslinks verfolgt werden sollen, wenn FollowRelLink verwendet wird. Möglicherweise ist ein kleinerer Wert erforderlich, wenn die REST-API aufgrund zu vieler Anforderungen drosselt. Standardwert: [Int32]::MaxValue
. Der Wert 0 (null) verhindert das Folgen von Beziehungslinks.
Type: | Int32 |
Aliases: | ML |
Position: | Named |
Default value: | Int32.MaxValue |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
Gibt an, wie oft PowerShell eine Verbindung an einen alternativen URI (Uniform Resource Identifier) umleitet, bevor die Verbindung fehlschlägt. Der Standardwert ist 5. Der Wert 0 (null) unterbindet sämtliche Umleitungen.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRetryCount
Gibt an, wie oft PowerShell eine Verbindung wiederholt, wenn ein Fehlercode zwischen 400 und 599, einschließlich oder 304, empfangen wird. Lesen Sie auch den RetryIntervalSec-Parameter , um die Anzahl der Sekunden zwischen Wiederholungen anzugeben.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Method
Gibt die für die Webanforderung verwendete Methode an. Zulässige Werte für diesen Parameter:
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.
Type: | WebRequestMethod |
Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 Schalter.
Dieser Parameter wurde in PowerShell 6.0 eingeführt.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutFile
Speichert den Antworttext in der angegebenen Ausgabedatei. Geben Sie einen Pfad und dateinamen ein. Wenn Sie den Pfad weglassen, wird der aktuelle Speicherort als Standard verwendet. Der Name wird als Literalpfad behandelt. Namen, die Klammern ([]
) enthalten, müssen in einfache Anführungszeichen ('
) eingeschlossen werden.
Standardmäßig Invoke-RestMethod
werden die Ergebnisse an die Pipeline zurückgegeben.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Dieser Parameter ist nur gültig, wenn der OutFile-Parameter ebenfalls 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 #15409.
Type: | SwitchParameter |
Position: | Named |
Default value: | No output |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Gibt an, dass das Cmdlet den Authorization
Header beibehalten soll, sofern vorhanden, über Umleitungen hinweg.
Standardmäßig entfernt das Cmdlet den Header vor der Authorization
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.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
Verwendet einen Proxyserver für die Anforderung, anstatt eine direkte Verbindung mit der Internetressource herzustellen. Geben Sie den URI (Uniform Resource Identifier) eines Netzwerkproxyservers ein.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | Uri |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
Gibt ein Benutzerkonto an, das über die Berechtigung zur Verwendung des Proxyservers verfügt, der durch den Proxy-Parameter 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 PSCredential
Objekt ein, z. B. ein vom Get-Credential
Cmdlet generiertes.
Dieser Parameter ist nur gültig, wenn der Proxyparameter auch im Befehl verwendet wird. Sie können die Parameter ProxyCredential und ProxyUseDefaultCredentials nicht im gleichen Befehl verwenden.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 gleichen Befehl verwenden.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ResponseHeadersVariable
Erstellt eine Variable, die ein Antwortheaderwörterbuch enthält. Geben Sie einen Variablennamen ohne das Dollarzeichensymbol ($
) ein. Die Schlüssel des Wörterbuchs enthalten die Feldnamen und Werte des Antwortheaders, der vom Webserver zurückgegeben wird.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | String |
Aliases: | RHV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Resume
Führt einen Versuch nach bestem Bemühen aus, den Download einer Teildatei fortzusetzen. Der Resume-Parameter erfordert den OutFile-Parameter .
Resume funktioniert nur auf die 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 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 Dateigröße größer als die Remotedateigröße ist, wird die lokale Datei überschrieben, und die gesamte Remotedatei wird vollständig erneut heruntergeladen. Dieses Verhalten ist identisch mit der Verwendung von OutFile ohne Resume.
Wenn der Remoteserver die Fortsetzung des Downloads nicht unterstützt, wird die lokale Datei überschrieben, und die gesamte Remotedatei wird vollständig erneut heruntergeladen. Dieses Verhalten ist identisch mit der Verwendung von OutFile ohne Resume.
Wenn die lokale Datei nicht vorhanden ist, wird die lokale Datei erstellt, und die gesamte Remotedatei wird vollständig heruntergeladen. Dieses Verhalten ist identisch mit der Verwendung von OutFile ohne Resume.
Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 sein [int]::MaxValue
.
Informationen zum Angeben der Anzahl von Wiederholungsversuchen finden Sie auch im Parameter MaximumRetryCount .
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
Erstellt eine Variable, die die Webanforderungssitzung enthält. Geben Sie einen Variablennamen ohne das Dollarzeichensymbol ($
) ein.
Wenn Sie eine Sitzungsvariable angeben, Invoke-RestMethod
erstellt ein Webanforderungssitzungsobjekt und weist es einer Variablen mit dem angegebenen Namen in Ihrer PowerShell-Sitzung zu. 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, des maximalen Umleitungswerts und der Zeichenfolge des Benutzer-Agents. 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 persistent, 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 Mehraufwand für wiederholte Anforderungen, sodass sie viel schneller sind.
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 zu überschreiben, verwenden Sie einen Cmdletparameter wie UserAgent oder Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.
Sie können die Parameter SessionVariable und WebSession nicht im gleichen Befehl verwenden.
Type: | String |
Aliases: | SV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipCertificateCheck
Überspringt Zertifikatüberprüfungen, die alle Überprüfungen wie Ablauf, Sperrung, vertrauenswürdige Stammzertifizierungsstelle usw. enthalten.
Warnung
Die Verwendung dieses Parameters ist nicht sicher und wird nicht empfohlen. Dieser Switch ist nur für bekannte Hosts vorgesehen, die ein selbstsigniertes Zertifikat zu Testzwecken verwenden. Die Verwendung erfolgt auf eigene Gefahr.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHeaderValidation
Gibt an, dass das Cmdlet der Anforderung Ohne Validierung Header hinzufügen soll.
Dieser Schalter 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 ungeprüft übergeben werden kann. Wenn angegeben, werden alle Header ohne Validierung hinzugefügt.
Dadurch wird die Überprüfung für Werte deaktiviert, die an die Parameter ContentType, Header undUserAgent übergeben werden.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHttpErrorCheck
Dieser Parameter bewirkt, dass das Cmdlet HTTP-Fehlerstatus ignoriert und die Antworten weiter verarbeitet. Die Fehlerantworten werden so in die Pipeline geschrieben, als wären sie erfolgreich.
Dieser Parameter wurde in PowerShell 7 eingeführt.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SslProtocol
Legt die SSL/TLS-Protokolle fest, die für die Webanforderung zulässig sind. Standardmäßig sind alle vom System unterstützten SSL-/TLS-Protokolle zulässig. SslProtocol ermöglicht die Beschränkung auf bestimmte Protokolle zu Konformitätszwecken.
Diese Werte werden als flagbasierte Enumeration definiert. Mit diesem Parameter können Sie mehrere Werte kombinieren, um mehrere Flags festzulegen. Die Werte können als Array von Werten oder als durch Trennzeichen getrennte 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 es Ihnen auch, die Tabulatorvervollständigung für die Werte zu verwenden. Möglicherweise können Sie nicht auf allen Plattformen mehrere Werte angeben.
Hinweis
Auf Nicht-Windows-Plattformen ist es möglicherweise nicht möglich, oder Tls12
als Option bereitzustellenTls
. 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.
Type: | WebSslProtocol |
Accepted values: | Default, Tls, Tls11, Tls12, Tls13 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StatusCodeVariable
Erstellt eine Variable, die ein HTTP-status Codeergebnis der Anforderung enthält. Geben Sie einen Variablennamen ohne das Dollarzeichensymbol ($
) ein.
Der Parameter kann Erfolgs- oder Fehlermeldungen identifizieren, wenn er mit dem SkipHttpErrorCheck-Parameter verwendet wird.
Geben Sie den Variablennamen des Parameters als Zeichenfolge ein, z. B -StatusCodeVariable "scv"
. .
Dieser Parameter wurde in PowerShell 7 eingeführt.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TimeoutSec
Gibt an, wie lange die Anforderung ausstehen kann, bevor ein Zeitlimit aufgetreten ist. Geben Sie einen Wert in Sekunden ein. Der Standardwert 0 (null) steht für einen unbegrenzten Zeitüberschreitungswert.
Eine DNS-Abfrage (Domain Name System) kann bis zu 15 Sekunden dauern, bis sie zurückgegeben oder ein Timeout ausgeführt wird. Wenn Ihre Anforderung einen Hostnamen enthält, der eine Auflösung erfordert, und Sie TimeoutSec auf einen Wert größer als 0 (null) festlegen, aber weniger als 15 Sekunden, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird und ein Timeout für Ihre Anforderung auftritt.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Token
Das OAuth- oder Bearertoken, das in die Anforderung eingeschlossen werden soll. Token ist für bestimmte Authentifizierungsoptionen erforderlich. Es kann nicht unabhängig verwendet werden.
Token akzeptiert ein SecureString
, das das Token enthält. Verwenden Sie zum Bereitstellen des Tokens manuell Folgendes:
Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
Dieser Parameter wurde in PowerShell 6.0 eingeführt.
Type: | SecureString |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TransferEncoding
Gibt einen Wert für den HTTP-Antwortheader transfer-encoding an. Zulässige Werte für diesen Parameter:
- Segmentiert
- Komprimieren
- Deflate
- GZip
- Identität
Type: | String |
Accepted values: | chunked, compress, deflate, gzip, identity |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Uri
Gibt den URI (Uniform Resource Identifier) der Internetressource an, an die die Webanforderung gesendet wird. Dieser Parameter unterstützt HTTP-, HTTPS-, FTP- und FILE-Werte.
Dieser Parameter ist erforderlich. Der Parametername (URI) ist optional.
Type: | Uri |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseBasicParsing
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 von hat keine Auswirkungen auf den Vorgang des Cmdlets.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UserAgent
Gibt eine Benutzer-Agent-Zeichenfolge für die Webanforderung an.
Der Standardbenutzer-Agent ähnelt mit Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0
geringfügigen Variationen für jedes Betriebssystem und jede Plattform.
Verwenden Sie zum Testen einer Website mit der standardmäßigen Benutzer-Agent-Zeichenfolge, die von den meisten Internetbrowsern verwendet wird, die Eigenschaften der PSUserAgent-Klasse , z. B. Chrome, FireFox, InternetExplorer, Opera und Safari.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WebSession
Gibt eine Webanforderungssitzung an. Geben Sie den Variablennamen ein, einschließlich des Dollarzeichens ($
).
Um einen Wert in der Webanforderungssitzung zu überschreiben, verwenden Sie einen Cmdletparameter wie UserAgent oder Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung. Inhaltsbezogene Header, z Content-Type
. B. , werden auch ü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, des maximalen Umleitungswerts und der Zeichenfolge des Benutzer-Agents. Sie können das Objekt verwenden, um den Zustand und die Daten übergreifend für Webanforderungen zu nutzen.
Um eine Webanforderungssitzung zu erstellen, geben Sie einen Variablennamen ohne Dollarzeichen in den Wert des SessionVariable-Parameters eines Befehls ein Invoke-RestMethod
. Invoke-RestMethod
erstellt die Sitzung und speichert sie in der Variablen. In allen nachfolgenden Befehlen verwenden Sie die Variable als Wert für den WebSession-Parameter.
Sie können die Parameter SessionVariable und WebSession nicht im gleichen Befehl verwenden.
Type: | WebRequestSession |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Eingaben
Sie können den Text 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 einen gültigen XML-Code zurückgibt, gibt dieses Cmdlet sie 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: Liest die Proxykonfiguration aus Umgebungsvariablen oder, falls diese nicht definiert sind, aus den Proxyeinstellungen des Benutzers.
- Für macOS: Liest die Proxykonfiguration aus Umgebungsvariablen oder, falls diese nicht definiert sind, aus den Proxyeinstellungen des Systems.
- Für Linux: Liest die Proxykonfiguration aus Umgebungsvariablen. Falls diese nicht definiert sind, initialisiert diese Eigenschaft eine nicht konfigurierte instance, 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_PROXY
oderHTTPS_PROXY
nicht definiert sind.NO_PROXY
: Eine durch Trennzeichen getrennte Liste mit Hostnamen, die aus der Proxyfunktion ausgeschlossen werden sollen.