Invoke-WebRequest

Hiermee haalt u inhoud op van een webpagina op internet.

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

Description

De Invoke-WebRequest cmdlet verzendt HTTP- en HTTPS-aanvragen naar een webpagina of webservice. Het parseert het antwoord en retourneert verzamelingen van koppelingen, afbeeldingen en andere belangrijke HTML-elementen.

Deze cmdlet is geïntroduceerd in PowerShell 3.0.

Vanaf PowerShell 7.0 ondersteunt proxyconfiguratie die Invoke-WebRequest is gedefinieerd door omgevingsvariabelen. Zie de sectie Notities van dit artikel.

Belangrijk

De voorbeelden in dit artikel verwijzen naar hosts in het contoso.com domein. Dit is een fictief domein dat door Microsoft wordt gebruikt voor voorbeelden. De voorbeelden zijn ontworpen om te laten zien hoe u de cmdlets gebruikt. Omdat de contoso.com sites echter niet bestaan, werken de voorbeelden niet. Pas de voorbeelden aan hosts in uw omgeving aan.

Voorbeelden

Voorbeeld 1: Een webaanvraag verzenden

In dit voorbeeld wordt de Invoke-WebRequest cmdlet gebruikt om een webaanvraag naar de Bing.com-site te verzenden.

$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

De eerste opdracht geeft de aanvraag uit en slaat het antwoord op in de $Response variabele.

Met de tweede opdracht krijgt u een InputField waar de eigenschap Name als "* Value"volgt uitziet. De gefilterde resultaten worden doorgesluisd om de eigenschappen Naam en Waarde te Select-Object selecteren.

Voorbeeld 2: Een stateful webservice gebruiken

In dit voorbeeld ziet u hoe u de Invoke-WebRequest cmdlet gebruikt met een stateful webservice.

$LoginParameters = @{
    Uri             = 'https://www.contoso.com/login/'
    SessionVariable = 'Session'
    Method          = 'POST'
    Body            = @{
        User     = 'jdoe'
        Password = 'P@S$w0rd!'
    }
}
$LoginResponse = Invoke-WebRequest @LoginParameters
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

De eerste aanroep om een aanmeldingsaanvraag te Invoke-WebRequest verzenden. Met de opdracht wordt een waarde opgegeven voor Session de waarde van de parameter SessionVariable . Wanneer de opdracht is voltooid, bevat de $LoginResponse variabele een BasicHtmlWebResponseObject en bevat de $Session variabele een WebRequestSession object. Hiermee wordt de gebruiker aangemeld bij de site.

De tweede aanroep voor Invoke-WebRequest het ophalen van het gebruikersprofiel, waarvoor de gebruiker moet worden aangemeld bij de site. De sessiegegevens die in de $Session variabele zijn opgeslagen, bieden sessiecookies aan de site die tijdens de aanmelding is gemaakt.

Voorbeeld 3: Koppelingen ophalen van een webpagina

In dit voorbeeld worden de koppelingen op een webpagina weergegeven. Hierbij wordt de Invoke-WebRequest cmdlet gebruikt om de inhoud van de webpagina op te halen. Vervolgens wordt de eigenschap Koppelingen van het BasicHtmlWebResponseObject gebruikt dat Invoke-WebRequest wordt geretourneerd en de eigenschap Href van elke koppeling.

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

Voorbeeld 4: Antwoordinhoud naar een bestand schrijven met behulp van de codering die is gedefinieerd op de aangevraagde pagina

In dit voorbeeld wordt de Invoke-WebRequest cmdlet gebruikt om de webpagina-inhoud van een PowerShell-documentatiepagina op te halen.

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

Met de eerste opdracht wordt de pagina opgehaald en wordt het antwoordobject opgeslagen in de $Response variabele.

Met de tweede opdracht maakt u een StreamWriter om de antwoordinhoud naar een bestand te schrijven. De eigenschap Encoding van het antwoordobject wordt gebruikt om de codering voor het bestand in te stellen.

Met de laatste paar opdrachten wordt de eigenschap Inhoud naar het bestand geschreven en wordt de StreamWriter verwijderd.

Houd er rekening mee dat de eigenschap Codering null is als de webaanvraag geen tekstinhoud retourneert.

Voorbeeld 5: Een bestand met meerdere onderdelen/formuliergegevens verzenden

In dit voorbeeld wordt de cmdlet gebruikt voor het Invoke-WebRequest uploaden van een bestand als een multipart/form-data inzending. Het bestand c:\document.txt wordt verzonden als het formulierveld document met de Content-Type naam text/plain.

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

Voorbeeld 6: Vereenvoudigde verzending van meerdere onderdelen/formuliergegevens

Voor sommige API's moeten multipart/form-data inzendingen worden verzonden om bestanden en gemengde inhoud te uploaden. In dit voorbeeld ziet u hoe u een gebruikersprofiel bijwerkt.

$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

Voor het profielformulier zijn de volgende velden vereist: , , email, en birthdayhobbies. avatarlastNamefirstName De API verwacht dat een afbeelding voor de afbeelding van het gebruikersprofiel wordt opgegeven in het avatar veld. De API accepteert ook meerdere hobbies vermeldingen die in hetzelfde formulier moeten worden ingediend.

Bij het maken van de $Form HashTable worden de sleutelnamen gebruikt als formulierveldnamen. Standaard worden de waarden van de HashTable geconverteerd naar tekenreeksen. Als er een system.IO.FileInfo-waarde aanwezig is, wordt de bestandsinhoud verzonden. Als een verzameling zoals matrices of lijsten aanwezig is, wordt het formulierveld meerdere keren verzonden.

Met behulp van Get-Item de avatar sleutel wordt het FileInfo object ingesteld als de waarde. Het resultaat is dat de afbeeldingsgegevens voor jdoe.png worden verzonden.

Door een lijst op te geven aan de hobbies sleutel, is het hobbies veld eenmaal aanwezig in de inzendingen voor elk lijstitem.

Voorbeeld 7: Niet-geslaagde berichten van Invoke-WebRequest ondervangen

Wanneer Invoke-WebRequest er een HTTP-bericht zonder succes wordt weergegeven (404, 500, enzovoort), wordt er geen uitvoer geretourneerd en wordt een afsluitfout gegenereerd. Als u de fout wilt ondervangen en de StatusCode wilt bekijken, kunt u de uitvoering in een try/catch blok insluiten.

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

De afsluitfout wordt onderschept door het catch blok, waarmee de StatusCode wordt opgehaald uit het uitzonderingsobject .

Voorbeeld 8: Meerdere bestanden tegelijk downloaden

De Invoke-WebRequest cmdlet kan slechts één bestand tegelijk downloaden. In het volgende voorbeeld worden Start-ThreadJob meerdere threadtaken gemaakt om meerdere bestanden tegelijk te downloaden.

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

Voorbeeld 9: Headervalidatie overslaan

De cmdlet valideert standaard Invoke-WebRequest de waarden van bekende headers met een door standaarden gedefinieerde waardeindeling. In het volgende voorbeeld ziet u hoe deze validatie een fout kan veroorzaken en hoe u de parameter SkipHeaderValidation kunt gebruiken om te voorkomen dat waarden worden gevalideerd voor eindpunten die ongeldig opgemaakte waarden tolereren.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation

Invoke-WebRequest: The format of value '12345' is invalid.

StatusCode        : 200
StatusDescription : OK
Content           : {
                      "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": �
RawContent        : HTTP/1.1 200 OK
                    Date: Mon, 08 Aug 2022 16:24:24 GMT
                    Connection: keep-alive
                    Server: gunicorn/19.9.0
                    Access-Control-Allow-Origin: *
                    Access-Control-Allow-Credentials: true
                    Content-Type: application�
Headers           : {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Access-Control-Allow-Origin, System.String[]]�}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 249
RelationLink      : {}

httpbin.org is een service die informatie retourneert over webaanvragen en antwoorden voor probleemoplossing. De $Uri variabele wordt toegewezen aan het /headers eindpunt van de service, waarmee de headers van een aanvraag als de inhoud in het antwoord worden geretourneerd.

De If-Match aanvraagheader is gedefinieerd in RFC-7232 sectie 3.1 en vereist dat de waarde voor die header wordt gedefinieerd met omringende aanhalingstekens. Aan de $InvalidHeaders variabele wordt een hash-tabel toegewezen waarvan de waarde If-Match ongeldig is omdat deze is gedefinieerd als 12345 in plaats van "12345".

Aanroepen Invoke-WebRequest met de ongeldige headers retourneert een foutrapportage dat de opgemaakte waarde ongeldig is. De aanvraag wordt niet naar het eindpunt verzonden.

Als u aanroept Invoke-WebRequest met de parameter SkipHeaderValidation , wordt de validatiefout genegeerd en wordt de aanvraag naar het eindpunt verzonden. Omdat het eindpunt niet-compatibele headerwaarden tolereert, retourneert de cmdlet het antwoordobject zonder fouten.

Parameters

-AllowUnencryptedAuthentication

Hiermee kunt u referenties en geheimen verzenden via niet-versleutelde verbindingen. Het opgeven van referenties of verificatieoptiesmet een URI die niet begint met https:// een fout en de aanvraag wordt afgebroken om te voorkomen dat geheimen in tekst zonder opmaak via niet-versleutelde verbindingen worden gecommuniceerd. Als u dit gedrag op eigen risico wilt overschrijven, geeft u de parameter AllowUnencryptedAuthentication op.

Waarschuwing

Het gebruik van deze parameter is niet veilig en wordt niet aanbevolen. Het is alleen beschikbaar voor compatibiliteit met verouderde systemen die geen versleutelde verbindingen kunnen bieden. Gebruik op eigen risico.

Deze functie is toegevoegd in PowerShell 6.0.0.

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

-Authentication

Hiermee geeft u het expliciete verificatietype op dat moet worden gebruikt voor de aanvraag. De standaardwaarde is None. De verificatieparameter kan niet worden gebruikt met de parameter UseDefaultCredentials .

Beschikbare verificatieopties:

  • None: Dit is de standaardoptie wanneer verificatie niet wordt opgegeven. Er wordt geen expliciete verificatie gebruikt.
  • Basic: Vereist referentie. De referenties worden verzonden als een RFC 7617 Basic Authentication-header Authorization: Basic in de indeling van base64(user:password).
  • Bearer: Vereist de tokenparameter . Verzendt een RFC 6750-header Authorization: Bearer met het opgegeven token.
  • OAuth: Vereist de tokenparameter . Verzendt een RFC 6750-header Authorization: Bearer met het opgegeven token.

Als u verificatie opgeeft, worden eventuele Authorization headers die worden geleverd aan headers of opgenomen in WebSession, overschreven.

Deze functie is toegevoegd in PowerShell 6.0.0.

Type:WebAuthenticationType
Accepted values:None, Basic, Bearer, OAuth
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Body

Hiermee geeft u de hoofdtekst van de aanvraag. De hoofdtekst is de inhoud van de aanvraag die de headers volgt. U kunt ook een lichaamswaarde doorsluisen naar Invoke-WebRequest.

De parameter Hoofdtekst kan worden gebruikt om een lijst met queryparameters op te geven of de inhoud van het antwoord op te geven.

Wanneer de invoer een POST-aanvraag is en de hoofdtekst een tekenreeks is, wordt de waarde links van het eerste gelijkteken (=) ingesteld als een sleutel in de formuliergegevens en wordt de resterende tekst ingesteld als de waarde. Als u meerdere sleutels wilt opgeven, gebruikt u een IDictionary-object , zoals een hash-tabel, voor de hoofdtekst.

Wanneer de invoer een GET-aanvraag is en de hoofdtekst een IDictionary is (meestal een hash-tabel), wordt de hoofdtekst als queryparameters aan de URI toegevoegd. Voor andere aanvraagtypen (zoals PATCH) wordt de hoofdtekst ingesteld als de waarde van de aanvraagbody in de standaardindeling name=value met de waarden die door de URL zijn gecodeerd.

Wanneer de invoer een System.Xml.XmlNode-object is en de XML-declaratie een codering opgeeft, wordt die codering gebruikt voor de gegevens in de aanvraag, tenzij deze worden overschreven door de parameter ContentType .

De parameter Body accepteert ook een System.Net.Http.MultipartFormDataContent object. Dit vereenvoudigt multipart/form-data aanvragen. Wanneer een MultipartFormDataContent-object wordt opgegeven voor Body, worden alle inhoudsgerelateerde headers die worden geleverd aan de parameters ContentType, Headers of WebSession overschreven door de Inhoudsheaders van het object MultipartFormDataContent . Deze functie is toegevoegd in PowerShell 6.0.0.

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

-Certificate

Hiermee geeft u het clientcertificaat op dat wordt gebruikt voor een beveiligde webaanvraag. Voer een variabele in die een certificaat of een opdracht of expressie bevat die het certificaat ophaalt.

Als u een certificaat wilt zoeken, gebruikt Get-PfxCertificate of gebruikt u de Get-ChildItem cmdlet in het certificaatstation (Cert:). Als het certificaat niet geldig is of niet over voldoende autoriteit beschikt, mislukt de opdracht.

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

-CertificateThumbprint

Hiermee geeft u het certificaat voor de digitale openbare sleutel (X509) van een gebruikersaccount op dat gemachtigd is om de aanvraag te verzenden. Voer de vingerafdruk van het certificaat in.

Certificaten worden gebruikt in verificatie op basis van clientcertificaten. Certificaten kunnen alleen worden toegewezen aan lokale gebruikersaccounts, niet aan domeinaccounts.

Als u de vingerafdruk van het certificaat wilt zien, gebruikt u de Get-Item of Get-ChildItem opdracht om het certificaat in Cert:\CurrentUser\Myte zoeken.

Notitie

Deze functie wordt alleen ondersteund op Windows-besturingssysteemplatforms.

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

-ContentType

Hiermee geeft u het inhoudstype van de webaanvraag op.

Als de waarde voor ContentType de coderingsindeling (als charset) bevat, gebruikt de cmdlet die indeling om de hoofdtekst van de webaanvraag te coderen. Als het ContentType geen coderingsindeling opgeeft, wordt in plaats daarvan de standaardcoderingsindeling gebruikt. Een voorbeeld van een ContentType met een coderingsindeling is text/plain; charset=iso-8859-5, waarmee het Latijnse/Cyrillische alfabet wordt opgegeven.

Als deze parameter wordt weggelaten en de aanvraagmethode POST is, Invoke-WebRequest stelt u het inhoudstype in op application/x-www-form-urlencoded. Anders wordt het inhoudstype niet opgegeven in de aanroep.

ContentType wordt overschreven wanneer een MultipartFormDataContent-object wordt opgegeven voor body.

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

-Credential

Hiermee geeft u een gebruikersaccount op dat gemachtigd is om de aanvraag te verzenden. Standaard is dit de huidige gebruiker.

Typ een gebruikersnaam, zoals User01 of Domain01\User01, of voer een PSCredential-object in dat is gegenereerd door de Get-Credential cmdlet.

Referenties kunnen alleen worden gebruikt of in combinatie met bepaalde opties voor verificatieparameters . Als deze alleen wordt gebruikt, levert deze alleen referenties aan de externe server als de externe server een aanvraag voor verificatievraag verzendt. Wanneer de referenties worden gebruikt met verificatieopties , worden de referenties expliciet verzonden.

Referenties worden opgeslagen in een PSCredential-object en het wachtwoord wordt opgeslagen als SecureString.

Notitie

Zie Hoe veilig is SecureString SecureString?voor meer informatie over SecureString-gegevensbeveiliging.

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

-CustomMethod

Hiermee geeft u een aangepaste methode op die wordt gebruikt voor de webaanvraag. Dit kan worden gebruikt als de aanvraagmethode die is vereist voor het eindpunt, geen beschikbare optie is voor de methode. Methode en CustomMethod kunnen niet samen worden gebruikt.

In dit voorbeeld wordt een TEST HTTP-aanvraag naar de API verzonden:

Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Deze functie is toegevoegd in PowerShell 6.0.0.

Type:String
Aliases:CM
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-DisableKeepAlive

Geeft aan dat de cmdlet de KeepAlive-waarde in de HTTP-header instelt op False. KeepAlive is standaard Waar. KeepAlive brengt een permanente verbinding tot stand met de server om volgende aanvragen te vergemakkelijken.

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

-Form

Converteert een woordenlijst naar een multipart/form-data inzending. Het formulier kan niet worden gebruikt met hoofdtekst. Als ContentType wordt gebruikt, wordt dit genegeerd.

De sleutels van de woordenlijst worden gebruikt als de veldnamen van het formulier. Formulierwaarden worden standaard geconverteerd naar tekenreekswaarden.

Als de waarde een System.IO.FileInfo-object is, wordt de inhoud van het binaire bestand verzonden. De naam van het bestand wordt verzonden als de bestandsnaameigenschap . Het MIME-type is ingesteld als application/octet-stream. Get-Item kan worden gebruikt om het leveren van het object System.IO.FileInfo te vereenvoudigen.

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

Als de waarde een verzamelingstype is, zoals matrices of lijsten, wordt het for-veld meerdere keren verzonden. De waarden van de lijst worden standaard behandeld als tekenreeksen. Als de waarde een System.IO.FileInfo-object is, wordt de inhoud van het binaire bestand verzonden. Geneste verzamelingen worden niet ondersteund.

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

In het bovenstaande voorbeeld wordt het tags veld drie keer in de vorm opgegeven, eenmaal voor elk van Vacation, Italyen 2017. Het pictures veld wordt ook eenmaal verzonden voor elk bestand in de 2017-Italy map. De binaire inhoud van de bestanden in die map worden verzonden als de waarden.

Deze functie is toegevoegd in PowerShell 6.1.0.

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

-Headers

Hiermee geeft u de headers van de webaanvraag. Voer een hash-tabel of -woordenlijst in.

Inhoudsgerelateerde headers, zoals Content-Type worden overschreven wanneer een MultipartFormDataContent-object wordt opgegeven voor body.

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

-InFile

Hiermee haalt u de inhoud van de webaanvraag op uit een bestand. Voer een pad en bestandsnaam in. Als u het pad weglaat, is de standaardlocatie de huidige locatie.

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

-MaximumRedirection

Hiermee geeft u op hoe vaak PowerShell een verbinding omleidt naar een alternatieve URI (Uniform Resource Identifier) voordat de verbinding mislukt. De standaardwaarde is 5. Een waarde van 0 (nul) voorkomt dat alle omleidingen worden omgeleid.

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRetryCount

Hiermee geeft u op hoe vaak PowerShell een verbinding opnieuw probeert uit te proberen wanneer een foutcode tussen 400 en 599, inclusief of 304 wordt ontvangen. Zie ook de parameter RetryIntervalSec voor het opgeven van het aantal nieuwe pogingen.

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

-Method

Hiermee geeft u de methode op die wordt gebruikt voor de webaanvraag. De aanvaardbare waarden voor deze parameter zijn:

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

De parameter CustomMethod kan worden gebruikt voor aanvraagmethoden die hierboven niet worden vermeld.

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

Geeft aan dat de cmdlet geen proxy mag gebruiken om de bestemming te bereiken. Wanneer u de proxy die in de omgeving is geconfigureerd, moet omzeilen, gebruikt u deze switch. Deze functie is toegevoegd in PowerShell 6.0.0.

Type:SwitchParameter
Position:Named
Default value:False
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-OutFile

Hiermee geeft u het uitvoerbestand waarvoor deze cmdlet de hoofdtekst van het antwoord opslaat. Voer een pad en bestandsnaam in. Als u het pad weglaat, is de standaardlocatie de huidige locatie. De naam wordt behandeld als een letterlijk pad. Namen die haakjes ([]) bevatten, moeten tussen enkele aanhalingstekens (') worden geplaatst.

Invoke-WebRequest Retourneert standaard de resultaten naar de pijplijn. Gebruik de parameter Passthru om de resultaten naar een bestand en naar de pijplijn te verzenden.

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

-PassThru

Geeft aan dat de cmdlet de resultaten retourneert, naast het schrijven ervan naar een bestand. Deze parameter is alleen geldig wanneer de outfile-parameter ook wordt gebruikt in de opdracht.

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

-PreserveAuthorizationOnRedirect

Geeft aan dat de cmdlet de Authorization header moet behouden, indien aanwezig, tussen omleidingen.

Standaard wordt de header door de Authorization cmdlet verwijderd voordat deze wordt omgeleid. Als u deze parameter opgeeft, wordt deze logica uitgeschakeld voor gevallen waarin de header naar de omleidingslocatie moet worden verzonden.

Deze functie is toegevoegd in PowerShell 6.0.0.

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

-Proxy

Hiermee geeft u een proxyserver voor de aanvraag op, in plaats van rechtstreeks verbinding te maken met de internetresource. Voer de URI van een netwerkproxyserver in.

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

-ProxyCredential

Hiermee geeft u een gebruikersaccount op dat gemachtigd is om de proxyserver te gebruiken die is opgegeven door de proxyparameter . Standaard is dit de huidige gebruiker.

Typ een gebruikersnaam, zoals User01 of Domain01\User01, of voer een PSCredential-object in, zoals een object dat is gegenereerd door de Get-Credential cmdlet.

Deze parameter is alleen geldig wanneer de proxyparameter ook wordt gebruikt in de opdracht. U kunt de parameters ProxyCredential en ProxyUseDefaultCredentials niet gebruiken in dezelfde opdracht.

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

-ProxyUseDefaultCredentials

Geeft aan dat de cmdlet de referenties van de huidige gebruiker gebruikt voor toegang tot de proxyserver die is opgegeven door de proxyparameter .

Deze parameter is alleen geldig wanneer de proxyparameter ook wordt gebruikt in de opdracht. U kunt de parameters ProxyCredential en ProxyUseDefaultCredentials niet gebruiken in dezelfde opdracht.

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

-Resume

Voert een beste poging uit om het downloaden van een gedeeltelijk bestand te hervatten. Voor hervatten is OutFile vereist.

Cv werkt alleen op de grootte van het lokale bestand en extern bestand en voert geen andere validatie uit dat het lokale bestand en het externe bestand hetzelfde zijn.

Als de lokale bestandsgrootte kleiner is dan de externe bestandsgrootte, probeert de cmdlet het downloaden van het bestand te hervatten en de resterende bytes toe te voegen aan het einde van het bestand.

Als de lokale bestandsgrootte hetzelfde is als de externe bestandsgrootte, wordt er geen actie ondernomen en wordt ervan uitgegaan dat de download al is voltooid door de cmdlet.

Als de lokale bestandsgrootte groter is dan de externe bestandsgrootte, wordt het lokale bestand overschreven en wordt het hele externe bestand opnieuw gedownload. Dit gedrag is hetzelfde als het gebruik van OutFile zonder Cv.

Als de externe server geen ondersteuning biedt voor het hervatten van downloaden, wordt het lokale bestand overschreven en wordt het hele externe bestand opnieuw gedownload. Dit gedrag is hetzelfde als het gebruik van OutFile zonder Cv.

Als het lokale bestand niet bestaat, wordt het lokale bestand gemaakt en wordt het hele externe bestand gedownload. Dit gedrag is hetzelfde als het gebruik van OutFile zonder Cv.

Deze functie is toegevoegd in PowerShell 6.1.0.

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

-RetryIntervalSec

Hiermee geeft u het interval op tussen nieuwe pogingen voor de verbinding wanneer een foutcode tussen 400 en 599, inclusief of 304 wordt ontvangen. Zie ook de parameter MaximumRetryCount voor het opgeven van het aantal nieuwe pogingen. De waarde moet tussen 1 en [int]::MaxValue.

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SessionVariable

Hiermee geeft u een variabele op waarvoor deze cmdlet een webaanvraagsessie maakt en opslaat in de waarde. Voer een variabelenaam in zonder het dollarteken ($) symbool.

Wanneer u een sessievariabele opgeeft, Invoke-WebRequest maakt u een sessieobject voor webaanvragen en wijst u deze toe aan een variabele met de opgegeven naam in uw PowerShell-sessie. U kunt de variabele in uw sessie gebruiken zodra de opdracht is voltooid.

Vóór PowerShell 7.4 is de sessie met webaanvragen geen permanente verbinding. Het is een object dat informatie bevat over de verbinding en de aanvraag, waaronder cookies, referenties, de maximale omleidingswaarde en de tekenreeks van de gebruikersagent. U kunt deze gebruiken om status en gegevens te delen tussen webaanvragen.

Vanaf PowerShell 7.4 blijft de webaanvraagsessie persistent zolang de eigenschappen van de sessie niet worden overschreven in een volgende aanvraag. Wanneer dat het is, maakt de cmdlet de sessie opnieuw met de nieuwe waarden. De permanente sessies verminderen de overhead voor herhaalde aanvragen, waardoor ze veel sneller worden.

Als u de webaanvraagsessie in volgende webaanvragen wilt gebruiken, geeft u de sessievariabele op in de waarde van de parameter WebSession . PowerShell gebruikt de gegevens in het sessieobject voor webaanvragen bij het tot stand brengen van de nieuwe verbinding. Als u een waarde in de webaanvraagsessie wilt overschrijven, gebruikt u een cmdlet-parameter, zoals UserAgent of Credential. Parameterwaarden hebben voorrang op waarden in de webaanvraagsessie.

U kunt de parameters SessionVariable en WebSession niet gebruiken in dezelfde opdracht.

Type:String
Aliases:SV
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipCertificateCheck

Slaat certificaatvalidatiecontroles over. Dit omvat alle validaties, zoals vervaldatum, intrekking, vertrouwde basisinstantie, enzovoort.

Waarschuwing

Het gebruik van deze parameter is niet veilig en wordt niet aanbevolen. Deze switch is alleen bedoeld om te worden gebruikt voor bekende hosts met behulp van een zelfondertekend certificaat voor testdoeleinden. Gebruik op eigen risico.

Deze functie is toegevoegd in PowerShell 6.0.0.

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

-SkipHeaderValidation

Geeft aan dat de cmdlet zonder validatie headers aan de aanvraag moet toevoegen.

Deze schakeloptie moet worden gebruikt voor sites waarvoor headerwaarden zijn vereist die niet voldoen aan standaarden. Als u deze schakeloptie opgeeft, wordt validatie uitgeschakeld zodat de waarde niet kan worden doorgegeven. Wanneer dit is opgegeven, worden alle headers zonder validatie toegevoegd.

Met deze schakeloptie wordt validatie uitgeschakeld voor waarden die zijn doorgegeven aan de parameters ContentType, Headers en UserAgent .

Deze functie is toegevoegd in PowerShell 6.0.0.

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

-SkipHttpErrorCheck

Deze parameter zorgt ervoor dat de cmdlet http-foutstatussen negeert en reacties blijft verwerken. De foutreacties worden naar de pijplijn geschreven alsof ze zijn geslaagd.

Deze parameter is geïntroduceerd in PowerShell 7.

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

-SslProtocol

Hiermee stelt u de SSL/TLS-protocollen in die zijn toegestaan voor de webaanvraag. Standaard zijn alle SSL/TLS-protocollen die door het systeem worden ondersteund, toegestaan. SslProtocol maakt het mogelijk om te beperken tot specifieke protocollen voor nalevingsdoeleinden.

Deze waarden worden gedefinieerd als een opsomming op basis van vlaggen. U kunt meerdere waarden combineren om meerdere vlaggen in te stellen met behulp van deze parameter. De waarden kunnen worden doorgegeven aan de parameter SslProtocol als een matrix met waarden of als een door komma's gescheiden tekenreeks van deze waarden. De cmdlet combineert de waarden met behulp van een binaire OF-bewerking. Het doorgeven van waarden als een matrix is de eenvoudigste optie en u kunt ook tabvoltooiing gebruiken voor de waarden. U kunt mogelijk niet meerdere opties definiëren op alle platforms.

Notitie

Op niet-Windows-platforms is het mogelijk niet mogelijk om te leveren Tls of Tls12 als optie. Ondersteuning voor Tls13 is niet beschikbaar op alle besturingssystemen en moet per besturingssysteem worden geverifieerd.

Deze functie is toegevoegd in PowerShell 6.0.0 en ondersteuning voor Tls13 deze functie is toegevoegd in PowerShell 7.1.

Type:WebSslProtocol
Accepted values:Default, Tls, Tls11, Tls12
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSec

Hiermee geeft u op hoe lang de aanvraag in behandeling kan zijn voordat er een time-out optreedt. Voer een waarde in seconden in. De standaardwaarde, 0, geeft een onbepaalde time-out op.

Het kan tot 15 seconden duren voordat een DNS-query (Domain Name System) retourneert of een time-out optreedt. Als uw aanvraag een hostnaam bevat waarvoor een oplossing is vereist en u TimeoutSec instelt op een waarde die groter is dan nul, maar minder dan 15 seconden, kan het 15 seconden of langer duren voordat een WebException wordt gegenereerd en er een time-out optreedt voor uw aanvraag.

Type:Int32
Position:Named
Default value:0
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Token

Het OAuth- of Bearer-token dat in de aanvraag moet worden opgenomen. Token is vereist voor bepaalde verificatieopties . Het kan niet onafhankelijk worden gebruikt.

Token gebruikt een SecureString token dat het token bevat. Als u het token handmatig wilt opgeven, gebruikt u het volgende:

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

Deze parameter is geïntroduceerd in PowerShell 6.0.

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

-TransferEncoding

Hiermee geeft u een waarde op voor de http-antwoordheader voor overdrachtscodering. De aanvaardbare waarden voor deze parameter zijn:

  • 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

Hiermee geeft u de URI (Uniform Resource Identifier) van de internetresource waarnaar de webaanvraag wordt verzonden. Voer een URI in. Deze parameter ondersteunt alleen HTTP of HTTPS.

Deze parameter is vereist. De parameternaam-URI is optioneel.

Type:Uri
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-UseBasicParsing

Deze parameter is afgeschaft. Vanaf PowerShell 6.0.0.0 gebruiken alle webaanvragen alleen basisparsering. Deze parameter is alleen opgenomen voor compatibiliteit met eerdere versies en elk gebruik ervan heeft geen effect op de werking van de cmdlet.

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

-UseDefaultCredentials

Geeft aan dat de cmdlet de referenties van de huidige gebruiker gebruikt om de webaanvraag te verzenden. Dit kan niet worden gebruikt met verificatie of referenties en wordt mogelijk niet ondersteund op alle platforms.

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

-UserAgent

Hiermee geeft u een tekenreeks voor de gebruikersagent voor de webaanvraag op.

De standaardgebruikersagent is vergelijkbaar Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 met kleine variaties voor elk besturingssysteem en platform.

Als u een website wilt testen met de standaardtekenreeks voor gebruikersagenten die door de meeste internetbrowsers wordt gebruikt, gebruikt u de eigenschappen van de klasse PSUserAgent , zoals Chrome, FireFox, InternetExplorer, Opera en Safari.

De volgende opdracht maakt bijvoorbeeld gebruik van de tekenreeks van de gebruikersagent voor 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

Hiermee geeft u een webaanvraagsessie. Voer de naam van de variabele in, inclusief het dollarteken ($).

Als u een waarde in de webaanvraagsessie wilt overschrijven, gebruikt u een cmdlet-parameter, zoals UserAgent of Credential. Parameterwaarden hebben voorrang op waarden in de webaanvraagsessie. Inhoudsgerelateerde headers, zoals Content-Type, worden ook overschreven wanneer een MultipartFormDataContent-object wordt opgegeven voor Body.

In tegenstelling tot een externe sessie is de webaanvraagsessie geen permanente verbinding. Het is een object dat informatie bevat over de verbinding en de aanvraag, waaronder cookies, referenties, de maximale omleidingswaarde en de tekenreeks van de gebruikersagent. U kunt deze gebruiken om status en gegevens te delen tussen webaanvragen.

Als u een webaanvraagsessie wilt maken, voert u een variabelenaam in, zonder dollarteken, in de waarde van de parameter SessionVariable van een Invoke-WebRequest opdracht. Invoke-WebRequest maakt de sessie en slaat deze op in de variabele. In volgende opdrachten gebruikt u de variabele als de waarde van de parameter WebSession .

U kunt de parameters SessionVariable en WebSession niet gebruiken in dezelfde opdracht.

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

Invoerwaarden

Object

U kunt de hoofdtekst van een webaanvraag doorsluisen naar deze cmdlet.

Uitvoerwaarden

BasicHtmlWebResponseObject

Deze cmdlet retourneert het antwoordobject dat het resultaat van de webaanvraag vertegenwoordigt.

Notities

PowerShell bevat de volgende aliassen voor Invoke-WebRequest:

  • Alle platforms:
    • iwr

Vanaf PowerShell 6.0.0.0 Invoke-WebRequest ondersteunt alleen eenvoudige parsering.

Zie BasicHtmlWebResponseObject voor meer informatie.

Vanwege wijzigingen in .NET Core 3.1 gebruikt PowerShell 7.0 en hoger de eigenschap HttpClient.DefaultProxy om de proxyconfiguratie te bepalen.

De waarde van deze eigenschap wordt bepaald door uw platform:

  • Voor Windows: leest proxyconfiguratie uit omgevingsvariabelen. Als deze variabelen niet zijn gedefinieerd, wordt de eigenschap afgeleid van de proxy-instellingen van de gebruiker.
  • Voor macOS: leest proxyconfiguratie uit omgevingsvariabelen. Als deze variabelen niet zijn gedefinieerd, wordt de eigenschap afgeleid van de proxy-instellingen van het systeem.
  • Voor Linux: leest proxyconfiguratie uit omgevingsvariabelen. Als deze variabelen niet zijn gedefinieerd, initialiseert de eigenschap een niet-geconfigureerd exemplaar dat alle adressen omzeilt.

De omgevingsvariabelen die worden gebruikt voor DefaultProxy initialisatie op Windows- en Unix-platforms zijn:

  • HTTP_PROXY: de hostnaam of het IP-adres van de proxyserver die wordt gebruikt voor HTTP-aanvragen.
  • HTTPS_PROXY: de hostnaam of het IP-adres van de proxyserver die wordt gebruikt voor HTTPS-aanvragen.
  • ALL_PROXY: de hostnaam of het IP-adres van de proxyserver die wordt gebruikt voor HTTP- en HTTPS-aanvragen in het geval HTTP_PROXY dat deze HTTPS_PROXY niet zijn gedefinieerd.
  • NO_PROXY: een door komma's gescheiden lijst met hostnamen die moeten worden uitgesloten van proxying.