Invoke-RestMethod

Syntaxis

StandardMethod (Standaard)

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

StandardMethodNoProxy

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

CustomMethod

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

CustomMethodNoProxy

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

Description

Voorbeelden

Voorbeeld 1: De PowerShell RSS-feed ophalen

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

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

Voorbeeld 2: Een POST-aanvraag uitvoeren

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

Voorbeeld 3: Relationele koppelingen volgen

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

Voorbeeld 4: Vereenvoudigde multipart/Form-Data indiening

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'C:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form

Voorbeeld 5: Meerdere headers doorgeven

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

Voorbeeld 6: Geretourneerde items opsommen in de pijplijn

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1

$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30

$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30

Voorbeeld 7: Headervalidatie overslaan

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

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

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

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

Voorbeeld 8: Een aanvraag verzenden met HTTP 2.0

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

Voorbeeld 9: Een aanvraag verzenden naar een Unix-sockettoepassing

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

Parameters

-AllowInsecureRedirect

Hiermee kunt u omleiden van HTTPS naar HTTP. Standaard leidt elke aanvraag die wordt omgeleid van HTTPS naar HTTP tot een foutmelding, en de aanvraag wordt afgebroken om te voorkomen dat er onbedoeld in platte tekst wordt gecommuniceerd via onbeveiligde verbindingen. Als u dit gedrag op eigen risico wilt overschrijven, gebruikt u de parameter AllowInsecureRedirect.

Deze parameter is toegevoegd in PowerShell 7.4.

Parametereigenschappen

Parametersets

-AllowUnencryptedAuthentication

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

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-Authentication

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

Beschikbare verificatieopties:

• None: Dit is de standaardoptie wanneer verificatie- niet wordt verstrekt. Er wordt geen expliciete verificatie gebruikt.
• Basic: vereist een referentie. De inloggegevens worden gebruikt voor het verzenden van een RFC 7617 Basic Authentication Authorization: Basic-header in het formaat base64(user:password).
• Bearer: vereist de parameter -token. Hiermee verzendt u een RFC 6750 Authorization: Bearer header met het opgegeven token.
• OAuth: vereist de parameter -token. Hiermee verzendt u een RFC 6750 Authorization: Bearer header met het opgegeven token.

Het opgeven van Verificatie overschrijft alle Authorization headers die worden geleverd aan Headers of zijn opgenomen in WebSession.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-Body

Specificeert het onderdeel van het verzoek. De hoofdtekst is de inhoud van de aanvraag die de headers volgt. U kunt ook een body-waarde doorsluizen naar Invoke-RestMethod.

De parameter Hoofdtekst kan worden gebruikt om een lijst met queryparameters op te geven of de inhoud van de aanvraag op te geven. Voor queryparameters gebruikt de cmdlet de System.Net.WebUtility.UrlEncode methode om de sleutel-waardeparen te coderen. Zie voor meer informatie over coderingstekenreeksen voor URL's de verwijzing naar de UrlEncode()-methode.

Wanneer de invoer een POST-aanvraag is en de hoofdtekst een tekenreeks, 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 Body.

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

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.

Wanneer de body een formulier is, of als het de uitvoer van een andere Invoke-WebRequest-aanroep is, stelt PowerShell de aanvraaginhoud in op de formuliervelden.

De parameter Body kan ook een System.Net.Http.MultipartFormDataContent object accepteren, waardoor multipart/form-data aanvragen mogelijk zijn. Wanneer een MultipartFormDataContent-object wordt opgegeven voor Body, worden alle inhoudsgerelateerde headers die worden geleverd aan de ContentType, Headersof WebSession-parameters overschreven door de inhoudskoppen van het MultipartFormDataContent-object. Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-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 u Get-PfxCertificate of de Get-ChildItem-cmdlet in het certificaatstation (Cert:). Als het certificaat niet geldig is of niet over voldoende autoriteit beschikt, mislukt de opdracht.

Parametereigenschappen

Parametersets

-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 opdracht Get-Item of Get-ChildItem om het certificaat in Cert:\CurrentUser\Myte vinden.

Parametereigenschappen

Parametersets

-ConnectionTimeoutSeconds

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 oplossing is vereist en u ConnectionTimeoutSeconds 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.

Deze parameter vervangt de parameter TimeoutSec in PowerShell 7.4. U kunt TimeoutSec- als alias gebruiken voor ConnectionTimeoutSeconds.

Parametereigenschappen

Parametersets

-ContentType

Hiermee geeft u het inhoudstype van de webaanvraag op.

Als de waarde voor ContentType de coderingsindeling (zoals charset) bevat, gebruikt de cmdlet die indeling om de hoofdtekst van de webaanvraag te coderen. Als de 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 Latijns/Cyrillisch alfabet wordt opgegeven.

Als u de parameter weglaat, kan het inhoudstype afwijken op basis van de HTTP-methode die u gebruikt:

• Voor een POST-methode wordt het inhoudstype application/x-www-form-urlencoded
• Voor een PUT-methode wordt het inhoudstype application/json
• Voor andere methoden wordt het inhoudstype niet opgegeven in de aanvraag

Als u de parameter InFile gebruikt om een bestand te uploaden, moet u het inhoudstype instellen. Meestal moet het type worden application/octet-stream. U moet echter het inhoudstype instellen op basis van de vereisten van het eindpunt.

ContentType- wordt overschreven wanneer de Body een MultipartFormDataContent object is.

Als u vanaf PowerShell 7.4 deze parameter en de parameter Headers gebruikt om de Content-Type header te definiëren, wordt de waarde gebruikt die is opgegeven in de parameter ContentType.

Parametereigenschappen

Parametersets

-Credential

Hiermee geeft u een gebruikersaccount op dat gemachtigd is om de aanvraag te verzenden. De standaardwaarde is 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.

U kunt aanmeldgegevens alleen gebruiken of in combinatie met bepaalde authenticatieparameters. Als het alleen wordt gebruikt, levert het alleen inloggegevens aan de externe server indien de externe server een authenticatie-uitdaging verzendt. Wanneer de inloggegevens worden gebruikt met authenticatie-opties, worden de inloggegevens expliciet verzonden.

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

Parametereigenschappen

Parametersets

-CustomMethod

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

Voorbeeld:

Invoke-RestMethod -Uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Hiermee wordt een TEST HTTP-aanvraag naar de API verzonden.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-DisableKeepAlive

Hiermee stelt u de KeepAlive--waarde in de HTTP-header in op False. Standaard is KeepAlive- Waar. KeepAlive- brengt een permanente verbinding tot stand met de server om volgende aanvragen te vergemakkelijken.

Parametereigenschappen

Parametersets

-FollowRelLink

Geeft aan dat de cmdlet relationele koppelingen moet volgen.

Sommige REST API's ondersteunen paginering via relationele koppelingen per RFC5988. In plaats van de header te parseren om de URL voor de volgende pagina op te halen, kunt u de cmdlet dit laten doen. Als u wilt instellen hoe vaak relationele koppelingen moeten worden gevolgd, gebruikt u de parameter MaximumFollowRelLink.

Wanneer u deze schakeloptie gebruikt, retourneert de cmdlet een verzameling pagina's met resultaten. Elke pagina met resultaten kan meerdere resultaatitems bevatten.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-Form

Converteert een woordenlijst naar een multipart/form-data inzending. Formulier mag niet worden gebruikt met Body. De ContentType- wordt 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 ingediend als filename. Het MIME-type wordt ingesteld als application/octet-stream. Get-Item kan worden gebruikt om het leveren van het System.IO.FileInfo--object te vereenvoudigen.

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

Als de waarde een verzamelingstype is, zoals een matrix of lijst, wordt het formulierveld 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 collecties 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, één keer voor elk van de waarden: Vacation, Italyen 2017. Het pictures veld wordt eenmaal verzonden voor elk bestand in de map 2017-Italy. De binaire inhoud van de bestanden in die map worden verzonden als de waarden.

Deze functie is toegevoegd in PowerShell 6.1.0.

Parametereigenschappen

Parametersets

-Headers

Hiermee specificeert u de headers van het webverzoek. Voer een hash-tabel of woordenlijst in.

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

Als u deze parameter in PowerShell 7.4 gebruikt om de Content-Type header te definiëren en parameter ContentType te gebruiken, wordt de waarde die is opgegeven in de parameter ContentType gebruikt.

Parametereigenschappen

Parametersets

-HttpVersion

Hiermee geeft u de HTTP-versie die voor de aanvraag wordt gebruikt. De standaardwaarde is 1.1.

Geldige waarden zijn:

• 1.0
• 1.1
• 2.0
• 3.0

Parametereigenschappen

Parametersets

-InFile

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

U moet ook het inhoudstype van de aanvraag instellen. Als u bijvoorbeeld een bestand wilt uploaden, moet u het inhoudstype instellen. Meestal moet het type worden application/octet-stream. U moet echter het inhoudstype instellen op basis van de vereisten van het eindpunt.

Parametereigenschappen

Parametersets

-MaximumFollowRelLink

Hiermee geeft u op hoe vaak relationele koppelingen moeten worden gevolgd als FollowRelLink- wordt gebruikt. Er kan een kleinere waarde nodig zijn als de REST API wordt vertraagd vanwege te veel verzoeken. De standaardwaarde is [int32]::MaxValue. Een waarde van 0 (nul) voorkomt het volgen van relatiekoppelingen.

Parametereigenschappen

Parametersets

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

Parametereigenschappen

Parametersets

-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 parameter RetryIntervalSec voor het opgeven van het interval tussen nieuwe pogingen.

Parametereigenschappen

Parametersets

-Method

Hiermee geeft u de methode op die wordt gebruikt voor de webaanvraag. De acceptabele 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.

Parametereigenschappen

Parametersets

-NoProxy

Geeft aan dat de cmdlet geen proxy gebruikt om de bestemming te bereiken. Gebruik deze optie om de proxy te omzeilen die is geconfigureerd in uw internetinstellingen of die zijn opgegeven in de omgeving.

Deze parameter is geïntroduceerd in PowerShell 6.0.

Parametereigenschappen

Parametersets

-OperationTimeoutSeconds

Deze time-out is van toepassing op gegevens die in een stream worden gelezen, niet op de stroomtijd als geheel. De standaardwaarde, 0, geeft een onbepaalde time-out op.

Als u de waarde instelt op 30 seconden, betekent dit dat elke vertraging van meer dan 30 seconden tussen gegevens in de stream de aanvraag beëindigt. Een groot bestand dat enkele minuten duurt om te downloaden, wordt pas beëindigd als de stream langer dan 30 seconden vastlopen.

Parametereigenschappen

Parametersets

-OutFile

Standaard retourneert Invoke-RestMethod de resultaten naar de pijplijn. Wanneer u de parameter OutFile gebruikt, worden de resultaten opgeslagen in het opgegeven bestand en niet geretourneerd naar de pijplijn. Voer een pad en bestandsnaam in. Als u de resultaten naar een bestand en naar de pijplijn wilt verzenden, voegt u de parameter PassThru toe.

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.

Vanaf PowerShell 7.4 kunt u een mappad opgeven zonder de bestandsnaam. Wanneer u dit doet, gebruikt de opdracht bestandsnaam uit het laatste segment van de opgeloste URI na omleidingen. Wanneer u een mappad opgeeft voor OutFile-, kunt u de parameter Hervatten niet gebruiken.

Parametereigenschappen

Parametersets

-PassThru

Deze parameter is alleen geldig wanneer de parameter OutFile ook wordt gebruikt in de opdracht. De bedoeling is dat de resultaten naar het bestand en naar de pijplijn worden geschreven.

Parametereigenschappen

Parametersets

-PreserveAuthorizationOnRedirect

Geeft aan dat de cmdlet de Authorization header moet behouden, wanneer deze aanwezig is, tussen omleidingen.

De cmdlet verwijdert standaard de Authorization-koptekst 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.

Parametereigenschappen

Parametersets

-PreserveHttpMethodOnRedirect

Geeft aan dat de cmdlet de methode van de aanvraag bij omleidingen moet behouden.

De cmdlet wijzigt standaard de methode in GET wanneer deze wordt omgeleid. Als u deze parameter opgeeft, wordt deze logica uitgeschakeld om ervoor te zorgen dat de beoogde methode kan worden gebruikt met omleiding.

Deze functie is toegevoegd in PowerShell 7.4.

Parametereigenschappen

Parametersets

-Proxy

Maakt gebruik van een proxyserver voor de aanvraag, in plaats van rechtstreeks verbinding te maken met de internetresource. Voer de URI (Uniform Resource Identifier) van een netwerkproxyserver in.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-ProxyCredential

Hiermee geeft u een gebruikersaccount op dat gemachtigd is om de proxyserver te gebruiken die is opgegeven door de parameter Proxy. De standaardwaarde is 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 parameter Proxy ook wordt gebruikt in de opdracht. U kunt de parameters ProxyCredential en ProxyUseDefaultCredentials niet in dezelfde opdracht gebruiken.

Parametereigenschappen

Parametersets

-ProxyUseDefaultCredentials

Gebruikt de referenties van de huidige gebruiker voor toegang tot de proxyserver die is opgegeven door de parameter Proxy.

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

Parametereigenschappen

Parametersets

-ResponseHeadersVariable

Hiermee maakt u een variabele die een woordenlijst met antwoordheaders bevat. Voer een variabelenaam in zonder het dollarteken ($) symbool. De sleutels van de woordenlijst bevatten de veldnamen en waarden van de antwoordheader die door de webserver worden geretourneerd.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-Resume

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

Hervatten werkt alleen op de grootte van het lokale bestand en het externe bestand en voert geen andere validatie uit om te verifiëren 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 alsof je OutFile gebruikt zonder Hervatten.

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 alsof je OutFile gebruikt zonder Hervatten.

Als het lokale bestand niet bestaat, wordt het lokale bestand gemaakt en wordt het hele externe bestand gedownload. Dit gedrag is hetzelfde alsof je OutFile gebruikt zonder Hervatten.

Deze functie is toegevoegd in PowerShell 6.1.0.

Parametereigenschappen

Parametersets

-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. De waarde moet tussen 1 en [int]::MaxValuezijn. Wanneer de foutcode 429 is en het antwoord de eigenschap Opnieuw proberen na in de headers bevat, gebruikt de cmdlet die waarde voor het interval voor opnieuw proberen, zelfs als deze parameter is opgegeven.

Zie ook de parameter MaximumRetryCount voor het opgeven van het aantal nieuwe pogingen.

Parametereigenschappen

Parametersets

-SessionVariable

Hiermee maakt u een variabele die de webaanvraagsessie bevat. Voer een variabelenaam in zonder het dollarteken ($) symbool.

Wanneer u een sessievariabele opgeeft, Invoke-RestMethod een sessieobject voor webaanvragen maakt en dit toewijst 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 dit het geval is, maakt de cmdlet de sessie opnieuw aan met de nieuwe waarden. De permanente sessies verminderen de overhead voor herhaalde aanvragen, waardoor ze veel sneller worden.

Als u de sessie met webaanvragen wilt gebruiken in volgende webaanvragen, geeft u de sessievariabele op in de waarde van de WebSession parameter. 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 SessionVariable en WebSession parameters niet gebruiken in dezelfde opdracht.

Parametereigenschappen

Parametersets

-SkipCertificateCheck

Slaat certificaatvalidatiecontroles over die alle validaties bevatten, zoals vervaldatum, intrekking, vertrouwde basisinstantie, enzovoort.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

-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. Door deze schakeloptie op te geven, wordt validatie uitgeschakeld, zodat de waarde ongecontroleerd 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, Headersen UserAgent- parameters.

Deze functie is toegevoegd in PowerShell 6.0.0.

Parametereigenschappen

Parametersets

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

Parametereigenschappen

Parametersets

-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- kunt u 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 waarden opgeven op alle platforms.

Deze functie is toegevoegd in PowerShell 6.0.0. Ondersteuning voor Tls13 is toegevoegd in PowerShell 7.1.

Parametereigenschappen

Parametersets

-StatusCodeVariable

Hiermee maakt u een variabele met een HTTP-statuscoderesultaat van de aanvraag. Voer een variabelenaam in zonder het dollarteken ($) symbool.

De parameter kan geslaagde berichten of foutberichten identificeren wanneer deze worden gebruikt met de parameter SkipHttpErrorCheck.

Voer de naam van de variabele van de parameter in als een tekenreeks, zoals -StatusCodeVariable "scv".

Deze parameter is geïntroduceerd in PowerShell 7.

Parametereigenschappen

Parametersets

-Token

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

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

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

Deze parameter is geïntroduceerd in PowerShell 6.0.

Parametereigenschappen

Parametersets

-TransferEncoding

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

• In stukken verdeeld
• Comprimeren
• Deflate
• GZip
• Identiteit

Parametereigenschappen

Parametersets

-UnixSocket

Hiermee geeft u de naam van de Unix-socket waarmee u verbinding wilt maken. Deze parameter wordt ondersteund op Unix-systemen en Windows-versie 1803 en hoger. Zie de blogpost Windows/WSL Interop met AF_UNIX voor meer informatie over Windows-ondersteuning voor Unix-sockets.

Deze parameter is toegevoegd in PowerShell 7.4.

Parametereigenschappen

Parametersets

-Uri

Hiermee geeft u de URI (Uniform Resource Identifier) van de internetresource waarnaar de webaanvraag wordt verzonden. Deze parameter ondersteunt HTTP-, HTTPS-, FTP- en FILE-waarden.

Deze parameter is vereist. De parameternaam (URI) is optioneel.

Parametereigenschappen

Parametersets

-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. Wanneer deze wordt gebruikt, heeft dit geen effect op de werking van de cmdlet.

Parametereigenschappen

Parametersets

-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 referentie- en wordt mogelijk niet ondersteund op alle platforms.

Parametereigenschappen

Parametersets

-UserAgent

Hiermee stelt u een gebruikersagent-tekenreeks voor de webaanvraag in.

De standaardgebruikersagent is vergelijkbaar met 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 van de gebruikersagent die door de meeste internetbrowsers wordt gebruikt, gebruikt u de eigenschappen van de klasse PSUserAgent, zoals Chrome, Firefox, InternetExplorer, Opera en Safari.

Parametereigenschappen

Parametersets

-WebSession

Specificeert een webverzoeksessie. 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 overschreven wanneer een MultipartFormDataContent-object wordt geleverd 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-RestMethod-opdracht. Invoke-RestMethod 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 SessionVariable en WebSession parameters niet gebruiken in dezelfde opdracht.

Parametereigenschappen

Parametersets

CommonParameters

Invoerwaarden

Object

Uitvoerwaarden

Int64

String

XmlDocument

PSObject

Notities

Verwante koppelingen

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