Share via


Invoke-WebRequest

Ruft Inhalte von einer Webseite im Internet ab.

Syntax

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [<CommonParameters>]

Beschreibung

Das Invoke-WebRequest Cmdlet sendet HTTP-, HTTPS-, FTP- und FILE-Anforderungen an eine Webseite oder einen Webdienst. Das Cmdlet analysiert die Antwort und gibt Auflistungen von Formularen, Links, Bildern und anderen wichtigen HTML-Elementen zurück.

Dieses Cmdlet wurde in Windows PowerShell 3.0 eingeführt.

Hinweis

Standardmäßig kann Skriptcode auf der Webseite ausgeführt werden, wenn die Seite analysiert wird, um die ParsedHtml Eigenschaft aufzufüllen. Verwenden Sie die -UseBasicParsing Option, um dies zu unterdrücken.

Wichtig

Die Beispiele in diesem Artikel verweisen auf Hosts in der contoso.com Do Standard. Dies ist eine fiktive Do Standard die von Microsoft für Beispiele verwendet wird. Die Beispiele sollen zeigen, wie die Cmdlets verwendet werden. 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 -UseBasicParsing -URI https://www.bing.com?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

Die zurückgegebenen Invoke-WebRequest Daten werden in der $Response Variablen gespeichert. Die InputFields-Eigenschaft der Antwort enthält die Formularfelder. Where-Object wird verwendet, um die Formularfelder auf diejenigen zu filtern, in denen die Namenseigenschaft wie "* Wert" ist. Die gefilterten Ergebnisse werden weitergeleitet, um Select-Object die Namen - und Werteigenschaften auszuwählen.

Beispiel 2: Verwenden eines zustandsbehafteten Webdiensts

In diesem Beispiel wird gezeigt, wie Sie das Invoke-WebRequest Cmdlet mit einem zustandsbehafteten Webdienst wie Facebook verwenden.

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the Form.
$Form.fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective Form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method POST -Body $Form.Fields
$R.StatusDescription

Der erste Befehl verwendet das Invoke-WebRequest Cmdlet, um eine Anmeldeanforderung zu senden. Der Befehl gibt einen Wert von "FB" für den Wert des SessionVariable-Parameters an und speichert das Ergebnis in der $R Variablen. Wenn der Befehl abgeschlossen ist, enthält die $R Variable ein HtmlWebResponseObject , und die $FB Variable enthält ein WebRequestSession -Objekt.

Nachdem sich das Invoke-WebRequest Cmdlet bei Facebook angemeldet hat, gibt die StatusDescription-Eigenschaft des Webantwortobjekts in der $R Variablen an, dass der Benutzer erfolgreich angemeldet ist.

Dieser Befehl ruft die Links auf einer Webseite ab.

(Invoke-WebRequest -Uri "https://devblogs.microsoft.com/powershell/").Links.Href

Das Invoke-WebRequest Cmdlet ruft den Inhalt der Webseite ab. Anschließend wird die Links-Eigenschaft des zurückgegebenen HtmlWebResponseObject verwendet, um die Href-Eigenschaft der einzelnen Verknüpfungen anzuzeigen.

Beispiel 4: Erfassen von nicht erfolgreichen Nachrichten von Invoke-WebRequest

Wenn Invoke-WebRequest eine nicht erfolgreiche HTTP-Nachricht (404, 500 usw.) auftritt, gibt sie keine Ausgabe zurück und löst einen Beendigungsfehler aus. Um den Fehler zu erfassen 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 Beendigungsfehler wird vom catch Block erfasst, der den StatusCode aus dem Exception-Objekt abruft.

Beispiel 8: Gleichzeitiges Herunterladen mehrerer Dateien

Das Invoke-WebRequest Cmdlet kann jeweils nur eine Datei herunterladen. Im folgenden Beispiel werden Start-ThreadJob mehrere Threadaufträge erstellt, um mehrere Dateien gleichzeitig herunterzuladen.

$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
        OutFile = 'PowerShell-7.2.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
        OutFile = 'PowerShell-7.2.5-win-x64.zip'
    }
)

$jobs = @()

foreach ($file in $files) {
    $jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
        $params = $using:file
        Invoke-WebRequest @params
    }
}

Write-Host "Downloads started..."
Wait-Job -Job $jobs

foreach ($job in $jobs) {
    Receive-Job -Job $job
}

Hinweis

Um das Start-ThreadJob Cmdlet zu verwenden, müssen Sie das ThreadJob-Modul aus dem PowerShell-Katalog installieren.

Parameter

-Body

Gibt den Anforderungstext an. Der Text entspricht dem Inhalt der Anforderung, der auf die Header folgt. Sie können auch einen Textkörperwert an Invoke-WebRequest.

Der Parameter "Body" kann verwendet werden, um eine Liste von Abfrageparametern anzugeben oder den Inhalt der Antwort anzugeben.

Wenn es sich bei der Eingabe um eine GET-Anforderung handelt und der Textkörper ein IDictionary (in der Regel eine Hashtabelle) ist, wird der Textkörper als Abfrageparameter dem URI hinzugefügt. Bei anderen Anforderungstypen (z. B. POST) wird der Textkörper als Wert des Anforderungstexts im Standardformat name=value festgelegt.

Wenn der Textkörper ein Formular ist oder die Ausgabe eines Invoke-WebRequest Aufrufs ist, legt PowerShell den Anforderungsinhalt auf die Formularfelder fest. Zum Beispiel:

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms\[0\].Name = "MyName" $r.Forms\[0\].Password = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $r

  •  oder -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[0\]

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 suchen, verwenden oder verwenden Sie Get-PfxCertificate das Get-ChildItem Cmdlet auf dem Zertifikatlaufwerk (Cert:Zertifikat). Wenn das Zertifikat ungültig ist oder nicht über ausreichende Autorität verfügt, schlägt der Befehl fehl.

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 zugeordnet werden, nicht aber konten Standard.

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

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 ausgelassen wird und die Anforderungsmethode POST ist, Invoke-WebRequest wird der Inhaltstyp auf application/x-www-form-urlencoded. Andernfalls wird der Inhaltstyp nicht im Aufruf angegeben.

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 "Do Standard 01\User01", oder geben Sie ein vom Cmdlet generiertes Get-Credential PSCredential-Objekt ein.

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

Hinweis

Weitere Informationen zum Schutz von SecureString finden Sie unter "Wie sicher ist SecureString?".

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DisableKeepAlive

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

Type:SwitchParameter
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 von UserAgent-Headern den Parameter "UserAgent ". Sie können diesen Parameter nicht verwenden, um UserAgent- oder Cookie-Header anzugeben.

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 zu einem alternativen URI (Uniform Resource Identifier) umleitet, bevor die Verbindung fehlschlägt. Der Standardwert ist 5. Der Wert 0 (null) unterbindet sämtliche Umleitungen.

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

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

Gibt standardmäßig Invoke-WebRequest die Ergebnisse an die Pipeline zurück. Verwenden Sie den Passthru-Parameter , um die 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 zusätzlich zum Schreiben in eine Datei zurückgibt. Dieser Parameter ist nur gültig, wenn der OutFile-Parameter auch im Befehl verwendet wird.

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 zum Verwenden des durch den Proxyparameter angegebenen Proxyservers verfügt. Der Standardwert ist der aktuelle Benutzer.

Geben Sie einen Benutzernamen ein, zUser01. B. oder Domain01\User01geben Sie ein PSCredential-Objekt ein, z. B. einen vom Get-Credential Cmdlet generierten.

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

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 selben Befehl verwenden.

Type:SwitchParameter
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 ($) ein.

Wenn Sie eine Sitzungsvariable angeben, Invoke-WebRequest wird ein Webanforderungssitzungsobjekt erstellt und einer Variablen mit dem angegebenen Namen in Ihrer PowerShell-Sitzung zugewiesen. Sie können die Variable in der Sitzung verwenden, sobald der Befehl abgeschlossen wurde.

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

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

Sie können die Parameter "SessionVariable " und "WebSession " nicht im selben Befehl verwenden.

Type:String
Aliases:SV
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 Zeitüberschreitung erfolgt. Geben Sie einen Wert in Sekunden ein. Der Standardwert 0 (null) steht für einen unbegrenzten Zeitüberschreitungswert.

Eine Do Standard Name System (DNS)-Abfrage kann bis zu 15 Sekunden dauern, um zurückzugeben oder zu timeout. Wenn Ihre Anforderung einen Hostnamen enthält, der eine Auflösung erfordert, und Sie TimeoutSec auf einen Wert größer als Null festlegen, aber weniger als 15 Sekunden, kann es 15 Sekunden oder mehr dauern, bis eine WebException ausgelöst wird, und Die Anforderung timeoutout.

Type:Int32
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:

  • Chunked
  • Compress
  • Deflate
  • GZip
  • Identity
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 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

Gibt an, dass das Cmdlet das Antwortobjekt für HTML-Inhalte ohne DOM-Analyse (Document Object Model) verwendet. Dieser Parameter ist erforderlich, wenn Internet Explorer nicht auf den Computern installiert ist, wie z. B. im Falle einer Server Core-Installation eines Windows Server-Betriebssystems.

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.

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; Windows NT 6.1; en-US) WindowsPowerShell/3.0 geringfügigen Abweichungen für jedes Betriebssystem und jede Plattform.

Um eine Website mit der standardmäßigen Benutzer-Agent-Zeichenfolge zu testen, die von den meisten Internetbrowsern verwendet wird, verwenden Sie die Eigenschaften der PSUserAgent-Klasse , z. B. Chrome, FireFox, InternetExplorer, Opera und Safari. 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 außer Kraft zu setzen, verwenden Sie einen Cmdlet-Parameter, z . B. UserAgent oder Credential. Parameterwerte haben Vorrang vor Werten in der Webanforderungssitzung.

Im Gegensatz zu einer Remotesitzung besteht bei der Webanforderungssitzung keine persistente Verbindung. Es handelt sich um ein Objekt, das Informationen über die Verbindung und die Anforderung enthält, einschließlich Cookies, Anmeldeinformationen, dem Maximalwert für Umleitungen 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 Invoke-WebRequest Befehls ein. Invoke-WebRequest 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.

Type:WebRequestSession
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Eingaben

Object

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

Ausgaben

HtmlWebResponseObject

Dieses Cmdlet gibt das Antwortobjekt zurück, das das Ergebnis der Webanforderung darstellt.

Hinweise

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

  • iwr