Invoke-RestMethod

Syntax

StandardMethod (Standardwert)

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-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>]

StandardMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-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>]

CustomMethod

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

CustomMethodNoProxy

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

Beschreibung

Beispiele

Beispiel 1: Abrufen des PowerShell-RSS-Feeds

Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
  Format-Table -Property Title, pubDate

Title                                                                pubDate
-----                                                                -------
Join the PowerShell 10th Anniversary Celebration!                    Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release                               Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016                       Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources                                    Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery                                       Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon                                      Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release                                   Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934             Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source!                                 Thu, 18 Aug 2016 15:32:02 +0000

Beispiel 2: Ausführen einer POST-Anforderung

$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

Beispiel 3: Folgen Sie den Beziehungslinks

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

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

$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

Beispiel 5: Übergeben mehrerer Header

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

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

$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

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

Beispiel 8: Senden einer Anforderung mit HTTP 2.0

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

Beispiel 9: Senden einer Anforderung an eine Unix-Socketanwendung

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 eigene Gefahr außer Kraft zu setzen, verwenden Sie den parameter AllowInsecureRedirect.

Dieser Parameter wurde in PowerShell 7.4 hinzugefügt.

Parametereigenschaften

Parametersätze

-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 mit https:// beginnt, zu einem Fehler, und die Anforderung wird abgebrochen, um unbeabsichtigte Kommunikation von Geheimnissen im Klartext über unverschlüsselte Verbindungen zu verhindern. Um dieses Verhalten auf eigenes Risiko außer Kraft zu setzen, geben Sie den AllowUnencryptedAuthentication Parameter an.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-Authentication

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

Verfügbare Authentifizierungsoptionen:

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

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

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-Body

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

Der Parameter "Body" kann verwendet werden, um eine Liste von Abfrageparametern anzugeben oder den Inhalt der Anforderung anzugeben. Bei Abfrageparametern verwendet das Cmdlet die System.Net.WebUtility.UrlEncode Methodenmethode zum Codieren der Schlüsselwertpaare. Weitere Informationen zum Codieren von Zeichenfolgen für URLs finden Sie unter der UrlEncode()-Methodenreferenz.

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

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

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

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

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

Parametereigenschaften

Parametersätze

-Certificate

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

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

Parametereigenschaften

Parametersätze

-CertificateThumbprint

Gibt das zertifikat für den digitalen öffentlichen Schlüssel (X509) eines Benutzerkontos an, das über die Berechtigung zum Senden der Anforderung verfügt. Geben Sie den Zertifikatfingerabdruck des Zertifikats ein.

Zertifikate werden in der zertifikatbasierten Clientauthentifizierung verwendet. Zertifikate können nur lokalen Benutzerkonten zugeordnet werden, nicht Domänenkonten.

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

Parametereigenschaften

Parametersätze

-ConnectionTimeoutSeconds

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

Eine DNS-Abfrage (Domain Name System) kann bis zu 15 Sekunden dauern, bis sie abgeschlossen oder ein Timeout eintritt. Wenn Ihre Anforderung einen Hostnamen enthält, dessen Auflösung erforderlich ist, und Sie ConnectionTimeoutSeconds auf einen Wert größer als Null, aber weniger als 15 Sekunden festlegen, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird und Ihre Anforderung abläuft.

Dieser Parameter ersetzte den parameter TimeoutSec in PowerShell 7.4. Sie können TimeoutSec- als Alias für ConnectionTimeoutSecondsverwenden.

Parametereigenschaften

Parametersätze

-ContentType

Gibt den Inhaltstyp der Webanforderung an.

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

Wenn Sie den Parameter weglassen, kann der Inhaltstyp je nach der verwendeten HTTP-Methode unterschiedlich sein:

• Bei einer POST-Methode ist der Inhaltstyp application/x-www-form-urlencoded
• Bei einer PUT-Methode ist der Inhaltstyp application/json
• Bei anderen Methoden wird der Inhaltstyp in der Anforderung nicht angegeben.

Wenn Sie den Parameter InFile verwenden, um eine Datei hochzuladen, sollten Sie den Inhaltstyp festlegen. Normalerweise sollte der Typ application/octet-streamwerden. Sie müssen den Inhaltstyp jedoch basierend auf den Anforderungen des Endpunkts festlegen.

ContentType- wird überschrieben, wenn der Body- ein MultipartFormDataContent--Objekt ist.

Ab PowerShell 7.4 wird, wenn Sie sowohl diesen Parameter als auch den Parameter Headers verwenden, um den Content-Type-Header zu definieren, der im Parameter ContentType angegebene Wert verwendet.

Parametereigenschaften

Parametersätze

-Credential

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

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

Sie können Credential allein verwenden oder gemeinsam mit verschiedenen Optionen für den Parameter Authentication. Wenn sie allein verwendet wird, stellt sie nur Anmeldeinformationen an den Remoteserver bereit, wenn der Remoteserver eine Anforderung für die Authentifizierungsabfrage sendet. Bei der Verwendung mit Optionen für Authentication, werden die Anmeldeinformationen ausdrücklich gesendet.

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

Parametereigenschaften

Parametersätze

-CustomMethod

Gibt die benutzerdefinierte Methode an, die für die Webanforderung verwendet wird. Dies kann mit der Anforderungsmethode verwendet werden, die vom Endpunkt benötigt wird, ist aber keine verfügbare Option für die Methode Method. 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.

Parametereigenschaften

Parametersätze

-DisableKeepAlive

Legt den wert KeepAlive im HTTP-Header auf False fest. Standardmäßig ist KeepAlive auf True gesetzt. KeepAlive stellt eine dauerhafte Verbindung mit dem Server her, um nachfolgende Anfragen zu erleichtern.

Parametereigenschaften

Parametersätze

-FollowRelLink

Gibt an, dass das Cmdlet Beziehungslinks folgen soll.

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

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

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-Form

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

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-Typ wird als application/octet-streamfestgelegt. Get-Item können verwendet werden, um die Bereitstellung des System.IO.FileInfo Objekts zu vereinfachen.

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

Wenn der Wert ein Sammlungstyp ist, z. B. ein Array oder eine Liste, wird das Formularfeld mehrmals übermittelt. Die Werte der Liste werden standardmäßig als Zeichenfolgen behandelt. Wenn der Wert ein System.IO.FileInfo-Objekt ist, werden die Binärdateiinhalte übermittelt. Eingebettete Collections werden nicht unterstützt.

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

Im obigen Beispiel wird das feld tags dreimal im Formular angegeben, einmal für jeden der Werte: Vacation, Italyund 2017. Das feld pictures wird einmal für jede Datei im ordner 2017-Italy übermittelt. Der binäre Inhalt der Dateien in diesem Ordner wird als Werte übermittelt.

Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-Headers

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

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

Wenn Sie ab PowerShell 7.4 diesen Parameter verwenden, um den Content-Type-Header zu definieren und ContentType Parameter zu verwenden, wird der im ContentType Parameter angegebene Wert verwendet.

Parametereigenschaften

Parametersätze

-HttpVersion

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

Gültige Werte sind:

• 1,0
• 1.1
• 2.0
• 3.0

Parametereigenschaften

Parametersätze

-InFile

Ruft den Inhalt des Webanforderungstexts aus einer Datei ab. Geben Sie einen Pfad und Dateinamen ein. Wenn Sie den Pfad weglassen, ist die Standardeinstellung der aktuelle Speicherort.

Sie müssen auch den Inhaltstyp der Anforderung festlegen. Um beispielsweise eine Datei hochzuladen, sollten Sie den Inhaltstyp festlegen. Normalerweise sollte der Typ application/octet-streamwerden. Sie müssen den Inhaltstyp jedoch basierend auf den Anforderungen des Endpunkts festlegen.

Parametereigenschaften

Parametersätze

-MaximumFollowRelLink

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

Parametereigenschaften

Parametersätze

-MaximumRedirection

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

Parametereigenschaften

Parametersätze

-MaximumRetryCount

Gibt an, wie oft PowerShell eine Verbindung wiederholt, wenn ein Fehlercode zwischen 400 und 599 (einschließlich) oder 304 empfangen wird. Siehe auch RetryIntervalSec Parameter zum Angeben des Intervalls zwischen Wiederholungen.

Parametereigenschaften

Parametersätze

-Method

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

• Default
• Delete
• Get
• Head
• Merge
• Options
• Patch
• Post
• Put
• Trace

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

Parametereigenschaften

Parametersätze

-NoProxy

Gibt an, dass das Cmdlet keinen Proxy verwendet, um das Ziel zu erreichen. Verwenden Sie dies, um den in Ihren Interneteinstellungen konfigurierten oder in der Umgebung angegebenen Proxy zu umgehen.

Dieser Parameter wurde in PowerShell 6.0 eingeführt.

Parametereigenschaften

Parametersätze

-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 zum Herunterladen mehrere Minuten benötigt, wird nicht abgebrochen, es sei denn, der Datenstrom bleibt länger als 30 Sekunden stehen.

Parametereigenschaften

Parametersätze

-OutFile

Standardmäßig gibt 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, ist die Standardeinstellung der aktuelle Speicherort. Der Name wird als literaler Pfad behandelt. Namen, die eckige Klammern ([]) enthalten, müssen in einfache Anführungszeichen (') eingeschlossen werden.

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.

Parametereigenschaften

Parametersätze

-PassThru

Dieser Parameter ist nur gültig, wenn der parameter OutFile auch im Befehl verwendet wird. Die Absicht besteht darin, die Ergebnisse in die Datei und in die Pipeline zu schreiben.

Parametereigenschaften

Parametersätze

-PreserveAuthorizationOnRedirect

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

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

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-PreserveHttpMethodOnRedirect

Gibt an, dass das Cmdlet die Methode der Anforderung über Umleitungen beibehalten soll.

Standardmäßig ändert das Cmdlet die Methode beim Umleiten auf GET. 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.

Parametereigenschaften

Parametersätze

-Proxy

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

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-ProxyCredential

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

Geben Sie einen Benutzernamen ein, z. B. "User01" oder "Domain01\User01", oder geben Sie ein PSCredential--Objekt ein, z. B. ein objekt, das vom Cmdlet Get-Credential generiert wurde.

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

Parametereigenschaften

Parametersätze

-ProxyUseDefaultCredentials

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

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

Parametereigenschaften

Parametersätze

-ResponseHeadersVariable

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

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-Resume

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

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

Wenn die lokale Dateigröße kleiner 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 erneut heruntergeladen. Dieses Verhalten ist dasselbe wie die Verwendung von OutFile ohne Resume.

Wenn der Remoteserver das Fortsetzen des Downloads nicht unterstützt, wird die lokale Datei überschrieben, und die gesamte Remotedatei wird erneut heruntergeladen. Dieses Verhalten ist dasselbe wie die Verwendung von OutFile ohne Resume.

Wenn die lokale Datei nicht vorhanden ist, wird die lokale Datei erstellt und die gesamte Remotedatei heruntergeladen. Dieses Verhalten ist dasselbe wie die Verwendung von OutFile ohne Resume.

Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-RetryIntervalSec

Gibt das Intervall zwischen Wiederholungen für die Verbindung an, wenn ein Fehlercode zwischen 400 und 599 (einschließlich) oder 304 empfangen wird. Der Wert muss zwischen 1 und [int]::MaxValuesein. 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, um die Anzahl der Wiederholungen anzugeben.

Parametereigenschaften

Parametersätze

-SessionVariable

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

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

Vor PowerShell 7.4 ist die Webanforderungssitzung keine dauerhafte Verbindung. Es handelt sich um ein Objekt, das Informationen über die Verbindung und die Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, maximaler Umleitungswert und der Benutzer-Agent-Zeichenfolge. Sie können es verwenden, um Status und Daten zwischen Webanforderungen auszutauschen.

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

Um die Webanforderungssitzung in nachfolgenden Webanforderungen zu verwenden, geben Sie die Sitzungsvariable im Wert des WebSession--Parameters an. PowerShell verwendet die Daten im Webanforderungssitzungsobjekt beim Herstellen der neuen Verbindung. Um einen Wert in der Webanforderungssitzung außer Kraft zu setzen, verwenden Sie einen Cmdlet-Parameter, z. B. UserAgent- oder anmeldeinformationen. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.

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

Parametereigenschaften

Parametersätze

-SkipCertificateCheck

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

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-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 ohne Überprüfung übergeben werden kann. Wenn angegeben, werden alle Header ohne Überprüfung hinzugefügt.

Mit diesem Schalter wird die Überprüfung für Werte deaktiviert, die an die ContentType-, Headerund UserAgent Parameter übergeben werden.

Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.

Parametereigenschaften

Parametersätze

-SkipHttpErrorCheck

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

Dieser Parameter wurde in PowerShell 7 eingeführt.

Parametereigenschaften

Parametersätze

-SslProtocol

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

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

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

Parametereigenschaften

Parametersätze

-StatusCodeVariable

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

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

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

Dieser Parameter wurde in PowerShell 7 eingeführt.

Parametereigenschaften

Parametersätze

-Token

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

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

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

Dieser Parameter wurde in PowerShell 6.0 eingeführt.

Parametereigenschaften

Parametersätze

-TransferEncoding

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

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

Parametereigenschaften

Parametersätze

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

Parametereigenschaften

Parametersätze

-Uri

Gibt den URI (Uniform Resource Identifier) der Internetressource an, an die die Webanforderung gesendet wird. Dieser Parameter unterstützt HTTP-, HTTPS-, FTP- und FILE-Werte.

Dieser Parameter ist erforderlich. Der Parametername (Uri) ist optional.

Parametereigenschaften

Parametersätze

-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. Wenn sie verwendet wird, hat sie keine Auswirkungen auf die Funktion des Cmdlets.

Parametereigenschaften

Parametersätze

-UseDefaultCredentials

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

Parametereigenschaften

Parametersätze

-UserAgent

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

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

Um eine Website mit der standardmäßigen 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.

Parametereigenschaften

Parametersätze

-WebSession

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

Um einen Wert in der Webanforderungssitzung außer Kraft zu setzen, verwenden Sie einen Cmdlet-Parameter, z. B. UserAgent- oder anmeldeinformationen. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung. Inhaltsbezogene Header, wie z. B. Content-Type, werden außer Kraft gesetzt, wenn ein MultipartFormDataContent-Objekt für Body übergeben wird.

Im Gegensatz zu einer Remotesitzung ist die Webanforderungssitzung keine dauerhafte Verbindung. Es handelt sich um ein Objekt, das Informationen über die Verbindung und die Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, maximaler Umleitungswert und der Benutzer-Agent-Zeichenfolge. Sie können es verwenden, um Status und Daten zwischen Webanforderungen auszutauschen.

Um eine Webanforderungssitzung zu erstellen, geben Sie einen Variablennamen ohne Dollarzeichen in den Wert des SessionVariable Parameter eines Invoke-RestMethod Befehls ein. Invoke-RestMethod erstellt die Sitzung und speichert sie in der Variablen. Verwenden Sie in nachfolgenden Befehlen die Variable als Wert des WebSession--Parameters.

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

Parametereigenschaften

Parametersätze

CommonParameters

Eingaben

Object

Ausgaben

Int64

String

XmlDocument

PSObject

Hinweise

Ähnliche Themen

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest