Invoke-WebRequest
Ruft Inhalte von einer Webseite im Internet ab.
Syntax
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
[-Method <WebRequestMethod>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
[-Method <WebRequestMethod>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
-CustomMethod <String>
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
-CustomMethod <String>
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Beschreibung
Das Invoke-WebRequest
Cmdlet sendet HTTP- und HTTPS-Anforderungen an eine Webseite oder einen Webdienst. Er analysiert die Antwort und gibt Auflistungen von Links, Bildern und anderen wichtigen HTML-Elementen zurück.
Dieses Cmdlet wurde in PowerShell 3.0 eingeführt.
Ab PowerShell 7.0 unterstützt die Proxykonfiguration, Invoke-WebRequest
die durch Umgebungsvariablen definiert wird. Weitere Informationen finden Sie im Abschnitt "Hinweise " dieses Artikels.
Wichtig
Die Beispiele in diesem Artikel beziehen sich auf Hosts in der contoso.com
Domäne. Dies ist eine fiktive Domäne, die von Microsoft als Beispiel verwendet wird. In den Beispielen wird die Verwendung der Cmdlets veranschaulicht.
Da die contoso.com
Websites jedoch nicht vorhanden sind, funktionieren die Beispiele nicht. Passen Sie die Beispiele an Hosts in Ihrer Umgebung an.
Beispiele
Beispiel 1: Senden einer Webanforderung
In diesem Beispiel wird das Invoke-WebRequest
Cmdlet verwendet, um eine Webanforderung an die Bing.com Website zu senden.
$Response = Invoke-WebRequest -URI https://www.bing.com/search?q=how+many+feet+in+a+mile
$Response.InputFields | Where-Object {
$_.name -like "* Value*"
} | Select-Object Name, Value
name value
---- -----
From Value 1
To Value 5280
Der erste Befehl gibt die Anforderung aus und speichert die Antwort in der $Response
Variablen.
Der zweite Befehl ruft ein Beliebiges InputField ab , bei dem die Name-Eigenschaft wie folgt "* Value"
lautet. Die gefilterten Ergebnisse werden an Select-Object
weitergeleitet, um die Eigenschaften Name und Wert auszuwählen.
Beispiel 2: Verwenden eines zustandsbehafteten Webdiensts
In diesem Beispiel wird gezeigt, wie Sie das Invoke-WebRequest
Cmdlet mit einem zustandsbehafteten Webdienst verwenden.
$Body = @{
User = 'jdoe'
password = 'P@S$w0rd!'
}
$LoginResponse = Invoke-WebRequest 'https://www.contoso.com/login/' -SessionVariable 'Session' -Body $Body -Method 'POST'
$Session
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session
$ProfileResponse
Der erste Aufruf von Invoke-WebRequest
sendet eine Anmeldeanforderung. Der Befehl gibt den Wert "Session" für den Wert des Parameters -SessionVariable an und speichert das Ergebnis in der $LoginResponse
Variablen. Wenn der Befehl abgeschlossen ist, enthält die $LoginResponse
Variable ein BasicHtmlWebResponseObject
und die $Session
Variable ein WebRequestSession
-Objekt. Dadurch wird der Benutzer bei der Website protokolliert.
Der Aufruf von $Session
allein zeigt das WebRequestSession
-Objekt in der Variablen an.
Der zweite Aufruf von ruft Invoke-WebRequest
das Profil des Benutzers ab, was erfordert, dass der Benutzer bei der Website angemeldet ist. Die in der $Session
Variablen gespeicherten Sitzungsdaten werden verwendet, um Sitzungscookies für die Website bereitzustellen, die während der Anmeldung erstellt wurde. Das Ergebnis wird in der $ProfileResponse
Variablen gespeichert.
Der Aufruf von $ProfileResponse
allein zeigt die BasicHtmlWebResponseObject
in der Variablen an.
Beispiel 3: Abrufen von Links von einer Webseite
In diesem Beispiel werden die Links auf einer Webseite abgerufen. Es verwendet das Invoke-WebRequest
Cmdlet, um den Inhalt der Webseite abzurufen. Anschließend werden die Links-Eigenschaft der BasicHtmlWebResponseObject
Invoke-WebRequest
zurückgegebenen und die Href-Eigenschaft der einzelnen Verknüpfungen verwendet.
(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href
Beispiel 4: Schreibt den Antwortinhalt mithilfe der auf der angeforderten Seite definierten Codierung in eine Datei.
In diesem Beispiel wird das Invoke-WebRequest
Cmdlet verwendet, um den Webseiteninhalt einer PowerShell-Dokumentationsseite abzurufen.
$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
$Stream.Write($Response.Content)
}
finally {
$Stream.Dispose()
}
Der erste Befehl ruft die Seite ab und speichert das Antwortobjekt in der $Response
Variablen.
Der zweite Befehl erstellt einen StreamWriter
, der verwendet wird, um den Antwortinhalt in eine Datei zu schreiben. Die Encoding-Eigenschaft des Antwortobjekts wird verwendet, um die Codierung für die Datei festzulegen.
Die letzten Befehle schreiben die Content-Eigenschaft in die Datei und verwerfen dann den StreamWriter
.
Beachten Sie, dass die Encoding-Eigenschaft NULL ist, wenn die Webanforderung keinen Textinhalt zurückgibt.
Beispiel 5: Übermitteln einer mehrteiligen/Formulardatendatei
In diesem Beispiel wird das Invoke-WebRequest
Cmdlet Upload einer Datei als multipart/form-data
Übermittlung verwendet. Die Datei c:\document.txt
wird als Formularfeld document
mit dem Content-Type
von text/plain
übermittelt.
$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'
$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)
$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)
$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'
Beispiel 6: Vereinfachte mehrteilige/Formulardatenübermittlung
Einige APIs erfordern multipart/form-data
Übermittlungen zum Hochladen von Dateien und gemischten Inhalten. In diesem Beispiel wird das Aktualisieren eines Benutzerprofils veranschaulicht.
$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-WebRequest -Uri $Uri -Method Post -Form $Form
Das Profilformular erfordert die folgenden Felder: firstName
, lastName
, avatar
email
, 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.
Mit auf Get-Item
dem avatar
Schlüssel wird das FileInfo
Objekt als Wert festgelegt. Das Ergebnis ist, dass die Bilddaten für jdoe.png
übermittelt werden.
Durch Die Angabe einer Liste für den hobbies
Schlüssel ist das hobbies
Feld für jedes Listenelement einmal in den Übermittlungen vorhanden.
Beispiel 7: Erfassen von nicht erfolgreichen Nachrichten aus Invoke-WebRequest
Wenn Invoke-WebRequest
eine NICHT erfolgreiche HTTP-Nachricht (404, 500 usw.) auftritt, gibt sie keine Ausgabe zurück und löst einen Abbruchfehler aus. Um den Fehler abzufangen und den StatusCode anzuzeigen, können Sie die Ausführung in einen try/catch
-Block einschließen.
try
{
$Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
# This will only execute if the Invoke-WebRequest is successful.
$StatusCode = $Response.StatusCode
}
catch
{
$StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode
404
Der Abbruchfehler wird vom -Block abgefangen, der catch
den StatusCode aus dem Exception-Objekt abruft.
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 unbeabsichtigt in Nur-Text über unverschlüsselte Verbindungen kommuniziert werden. 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. Sie wird nur aus 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: | None |
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 Format zubase64(user:password)
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 Bereitstellung 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-WebRequest
.
Der Body-Parameter kann verwendet werden, um eine Liste von Abfrageparametern oder den Inhalt der Antwort anzugeben.
Wenn es sich bei der Eingabe um eine GET-Anforderung handelt und der Text eine IDictionary
(in der Regel eine Hashtabelle) ist, wird der Text dem URI als Abfrageparameter hinzugefügt. Bei anderen Anforderungstypen (z. B. POST) wird der Text als Wert des Anforderungstexts im Standardformat name=value
festgelegt.
Der Body-Parameter akzeptiert möglicherweise auch ein System.Net.Http.MultipartFormDataContent
-Objekt. Dies erleichtert multipart/form-data
Anforderungen. Wenn ein MultipartFormDataContent-Objekt für Body bereitgestellt wird, werden alle Content-bezogenen Header, die für die Parameter ContentType, Headers oder WebSession bereitgestellt werden, von den Content-Headern 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 auf dem Laufwerk Zertifikat (Cert:
) oder verwenden Sie es. Wenn das Zertifikat nicht gültig ist oder über keine 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. Sie können nur lokalen Benutzerkonten zugeordnet werden. Sie funktionieren nicht mit Domänenkonten.
Verwenden Sie den Befehl oder Get-ChildItem
auf dem Get-Item
PowerShell-LaufwerkCert:
, um einen Zertifikatfingerabdruck abzurufen.
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 dieser Parameter nicht angegeben wird und die Anforderungsmethode POST ist, Invoke-WebRequest
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 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 eine benutzerdefinierte Methode an, die für die Webanforderung verwendet wird. Dies kann verwendet werden, wenn die vom Endpunkt erforderliche Anforderungsmethode keine verfügbare Option für die Methode ist. Method und CustomMethod können nicht zusammen verwendet werden.
In diesem Beispiel wird eine TEST
HTTP-Anforderung an die API gesendet:
Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
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 Wert KeepAlive im HTTP-Header auf False festlegt. KeepAlive ist standardmäßig True. KeepAlive richtet eine persistente Verbindung mit dem Server ein, um nachfolgende Anforderungen zu erleichtern.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
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 verwendet wird, wird dies 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 dateiname-Eigenschaft übermittelt. Der MIME-Typ ist 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 es sich bei dem Wert um einen Sammlungstyp handelt, z. B. Arrays oder Listen, wird das Feld for 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 angegeben, einmal für jedes 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.
Verwenden Sie zum Festlegen der UserAgent-Header den UserAgent-Parameter. Sie können diesen Parameter nicht verwenden, um Benutzer-Agent- oder Cookie-Header anzugeben.
Inhaltsbezogene Header, z. B Content-Type
. 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 |
-InFile
Ruft den Inhalt der Webanforderung aus einer Datei ab. Geben Sie einen Pfad- und Dateinamen ein. Wenn Sie den Pfad weglassen, wird der aktuelle Speicherort als Standard verwendet.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
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: | 5 |
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. Weitere Informationen zum Angeben der Anzahl von Wiederholungsversuchen finden Sie auch unter RetryIntervalSec-Parameter .
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 CustomMethod-Parameter kann für Anforderungsmethoden verwendet werden, die nicht oben 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 verwenden sollte, um das Ziel zu erreichen. Wenn Sie den in der Umgebung konfigurierten Proxy umgehen müssen, verwenden Sie diesen Switch. Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutFile
Gibt die Ausgabedatei an, für die dieses Cmdlet den Antworttext speichert. 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.
Gibt standardmäßig Invoke-WebRequest
die Ergebnisse an die Pipeline zurück. Verwenden Sie den Passthru-Parameter, um Ergebnisse an eine Datei und an die Pipeline zu senden.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Gibt an, dass das Cmdlet die Ergebnisse nicht nur in eine Datei schreibt. Dieser Parameter ist nur gültig, wenn der OutFile-Parameter ebenfalls im Befehl verwendet wird.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
Gibt einen Proxyserver für die Anforderung an, anstatt eine direkte Verbindung mit der Internetressource herzustellen. Geben Sie den URI des Netzwerk-Proxyservers ein.
Type: | Uri |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
Gibt ein Benutzerkonto an, das über die Berechtigung 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 Objekt.
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: | Current user |
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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Resume
Führt einen Best-Effort-Versuch aus, das Herunterladen einer partiellen Datei fortzusetzen. Resume erfordert OutFile.
Resume arbeitet 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 erneut heruntergeladen. Dieses Verhalten ist identisch mit der Verwendung von OutFile ohne Lebenslauf.
Wenn der Remoteserver die Fortsetzung des Downloads nicht unterstützt, wird die lokale Datei überschrieben, und die gesamte Remotedatei wird erneut heruntergeladen. Dieses Verhalten ist identisch mit der Verwendung von OutFile ohne Lebenslauf.
Wenn die lokale Datei nicht vorhanden ist, wird die lokale Datei erstellt und die gesamte Remotedatei heruntergeladen. Dieses Verhalten ist identisch mit der Verwendung von OutFile ohne Lebenslauf.
Dieses Feature wurde in PowerShell 6.1.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
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. Weitere Informationen zum Angeben der Anzahl von Wiederholungsversuchen finden Sie unter Parameter MaximumRetryCount .
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
Gibt eine Variable an, für die dieses Cmdlet eine Webanforderungssitzung erstellt und im Wert speichert.
Geben Sie einen Variablennamen ohne das Dollarzeichen ($
)-Symbol ein.
Wenn Sie eine Sitzungsvariable angeben, Invoke-WebRequest
erstellen Sie ein Webanforderungssitzungsobjekt und weisen 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.
Im Gegensatz zu einer Remotesitzung besteht bei der Webanforderungssitzung keine persistente Verbindung. Es handelt sich um ein Objekt, das Informationen zur Verbindung und zur Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, dem maximalen 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 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 selben 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üfungsprüfungen. Dies umfasst alle Validierungen wie Ablauf, Widerruf, vertrauenswürdige Stammautorität usw.
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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHeaderValidation
Gibt an, dass das Cmdlet der Anforderung Header ohne Überprüfung 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, sodass der Wert deaktiviert übergeben werden kann. Wenn angegeben, werden alle Header ohne Validierung hinzugefügt.
Dieser Schalter deaktiviert die Überprüfung für Werte, die an die Parameter ContentType, Headers und UserAgent übergeben werden.
Dieses Feature wurde in PowerShell 6.0.0 hinzugefügt.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHttpErrorCheck
Dieser Parameter bewirkt, dass das Cmdlet HTTP-Fehlerstatus ignoriert und weiterhin Antworten 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 Compliancezwecken.
Diese Werte werden als flagbasierte Enumeration definiert. Sie können mehrere Werte miteinander kombinieren, um mehrere Flags mit diesem Parameter 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 binär-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 mehrere Optionen auf allen Plattformen definieren.
Hinweis
Auf Nicht-Windows-Plattformen ist es möglicherweise nicht möglich, oder als Option bereitzustellen Tls
Tls12
. 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 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TimeoutSec
Gibt an, wie lange die Anforderung ausstehen kann, bevor das Zeitlimit fällt. Geben Sie einen Wert in Sekunden ein. Der Standardwert 0 (null) steht für einen unbegrenzten Zeitüberschreitungswert.
Eine DNS-Abfrage (Domain Name System) kann bis zu 15 Sekunden dauern, bis sie zurückgegeben wird oder ein Timeout erfolgt. Wenn Ihre Anforderung einen Hostnamen enthält, für den eine Auflösung erforderlich ist, und Sie TimeoutSec auf einen Wert größer als 00, aber weniger als 15 Sekunden festlegen, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird und die Anforderung ein Timeoutout hat.
Type: | Int32 |
Position: | Named |
Default value: | 0 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Token
Das OAuth- oder Bearertoken, das in die Anforderung aufgenommen werden soll. Token ist für bestimmte Authentifizierungsoptionen erforderlich. Sie kann nicht unabhängig verwendet werden.
Token nimmt ein an SecureString
, das das Token enthält. Verwenden Sie Folgendes, um das Token manuell zur Verfügung zu stellen:
Invoke-WebRequest -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. Geben Sie einen URI ein. Dieser Parameter unterstützt nur HTTP oder HTTPS.
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 hat keine Auswirkungen auf den Vorgang des Cmdlets.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
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: | None |
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 Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0
mit geringfügigen Abweichungen 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.
Der folgende Befehl verwendet beispielsweise die Benutzer-Agent-Zeichenfolge für internet Explorer:Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WebSession
Gibt eine Webanforderungssitzung an. Geben Sie den Variablennamen ein, einschließlich des Dollarzeichens ($
).
Um einen Wert in der Webanforderungssitzung zu überschreiben, verwenden Sie einen Cmdletparameter wie UserAgent oder Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung. Inhaltsbezogene Header, z. B Content-Type
. , 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 zur Verbindung und zur Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, dem maximalen 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 Befehls ein Invoke-WebRequest
. Invoke-WebRequest
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 selben 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 übergeben Invoke-WebRequest
.
Ausgaben
Hinweise
Ab PowerShell 6.0.0 Invoke-WebRequest
unterstützt nur die grundlegende Analyse.
Weitere Informationen finden Sie unter BasicHtmlWebResponseObject.
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 wird von Ihrer Plattform bestimmt:
- Für Windows: Liest die Proxykonfiguration aus Umgebungsvariablen. Wenn diese Variablen nicht definiert sind, wird die Eigenschaft von den Proxyeinstellungen des Benutzers abgeleitet.
- Für macOS: Liest die Proxykonfiguration aus Umgebungsvariablen. Wenn diese Variablen nicht definiert sind, wird die Eigenschaft von den Proxyeinstellungen des Systems abgeleitet.
- Für Linux: Liest die Proxykonfiguration aus Umgebungsvariablen. Wenn diese Variablen nicht definiert sind, initialisiert die -Eigenschaft einen nicht konfigurierten instance, der 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.