Invoke-RestMethod
Verzendt een HTTP- of HTTPS-aanvraag naar een RESTful-webservice.
Syntax
Default (Standaard)
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[<CommonParameters>]
Description
De Invoke-RestMethod cmdlet verzendt HTTP- en HTTPS-aanvragen naar REST-webservices (Representational State Transfer) die uitgebreide gestructureerde gegevens retourneren.
Windows PowerShell formatteert het antwoord op basis van het gegevenstype. Voor een RSS- of ATOM-feed retourneert Windows PowerShell de XML-knooppunten Item of Entry. Voor JavaScript Object Notation (JSON) of XML converteert Windows PowerShell de inhoud naar objecten (of deserialisatie).
Deze cmdlet wordt geïntroduceerd in Windows PowerShell 3.0.
Opmerking
Standaard kan scriptcode op de webpagina worden uitgevoerd wanneer de pagina wordt geparseerd om de eigenschap ParsedHtml te vullen.
Gebruik de -UseBasicParsing schakeloptie om dit te onderdrukken.
Parameters
-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 -Body kan worden gebruikt om een lijst met queryparameters op te geven of de inhoud van het antwoord op te geven.
Wanneer de invoer een GET-aanvraag is en de hoofdtekst een IDictionary is (meestal een hash-tabel), wordt de hoofdtekst als queryparameters toegevoegd aan de URI. Voor andere aanvraagtypen (zoals POST) wordt de hoofdtekst gebruikt als waarde voor de aanvraagtekst in de standaardnaam=waardenotatie.
Waarschuwing: De uitgebreide uitvoer van een POST-hoofdtekst eindigt met with -1-byte payload, ook al is de grootte van de hoofdtekst zowel bekend als verzonden in de Content-Length HTTP-header.
Wanneer de hoofdtekst een formulier is of als uitvoer van een andere Invoke-WebRequest aanroep, stelt Windows PowerShell de aanvraaginhoud in op de formuliervelden.
Voorbeeld:
$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.Forms[0]
Parametereigenschappen
| Type: | Object |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | True |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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 u Get-PfxCertificate of de Get-ChildItem-cmdlet in het certificaatstation (Cert:).
Als het certificaat niet geldig is of onvoldoende autoriteit heeft, mislukt de opdracht.
Parametereigenschappen
| Type: | X509Certificate |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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. Ze kunnen alleen worden toegewezen aan lokale gebruikersaccounts; ze werken niet met domeinaccounts.
Als u een vingerafdruk van een certificaat wilt ophalen, gebruikt u de opdracht Get-Item of Get-ChildItem in het Windows PowerShell-station (Cert:).
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-ContentType
Hiermee geeft u het inhoudstype van de webaanvraag op.
Als deze parameter wordt weggelaten en de aanvraagmethode POST is, Invoke-RestMethod stelt het inhoudstype in op 'application/x-www-form-urlencoded'.
Anders wordt het inhoudstype niet opgegeven in de aanroep.
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-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, zoals een object dat is gegenereerd door de Get-Credential-cmdlet.
Parametereigenschappen
| Type: | PSCredential |
| Default value: | Current user |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-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
| Type: | SwitchParameter |
| Default value: | KeepAlive |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-Headers
Hiermee specificeert u de headers van het webverzoek. Voer een hash-tabel of woordenlijst in.
Als u UserAgent-headers wilt instellen, gebruikt u de parameter -UserAgent.
U kunt deze parameter niet gebruiken om UserAgent- of cookieheaders op te geven.
Parametereigenschappen
| Type: | IDictionary |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-MaximumRedirection
Bepaalt hoe vaak Windows 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
| Type: | Int32 |
| Default value: | 5 |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-Method
Hiermee geeft u de methode op die wordt gebruikt voor de webaanvraag. De acceptabele waarden voor deze parameter zijn:
- Verstek
- Verwijderen
- Ontvang
- Hoofd
- Samenvoeging
- Opties
- Pleister
- Verzenden
- Put
- Trace
Parametereigenschappen
| Type: | WebRequestMethod |
| Default value: | Default |
| Geaccepteerde waarden: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-OutFile
Slaat de hoofdtekst van het antwoord op in het opgegeven uitvoerbestand. Voer een pad en bestandsnaam in. Als u het pad weglaat, is de standaardlocatie de huidige locatie.
Standaard retourneert Invoke-RestMethod de resultaten naar de pijplijn.
Als u de resultaten naar een bestand en naar de pijplijn wilt verzenden, gebruikt u de parameter -Passthru.
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-PassThru
Retourneert de resultaten, naast het schrijven ervan naar een bestand.
Deze parameter is alleen geldig wanneer de -OutFile parameter ook wordt gebruikt in de opdracht.
Parametereigenschappen
| Type: | SwitchParameter |
| Default value: | No output |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-Proxy
Maakt gebruik van een proxyserver voor de aanvraag, in plaats van rechtstreeks verbinding te maken met de internetresource. Voer de URI van een netwerkproxyserver in.
Parametereigenschappen
| Type: | Uri |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-ProxyCredential
Hiermee geeft u een gebruikersaccount op dat is gemachtigd voor het gebruik van de proxyserver 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 -Proxy parameter ook wordt gebruikt in de opdracht.
U kunt de parameters -ProxyCredential en -ProxyUseDefaultCredentials niet gebruiken in dezelfde opdracht.
Parametereigenschappen
| Type: | PSCredential |
| Default value: | Current user |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-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 -Proxy parameter ook wordt gebruikt in de opdracht.
U kunt de parameters -ProxyCredential en -ProxyUseDefaultCredentials niet gebruiken in dezelfde opdracht.
Parametereigenschappen
| Type: | SwitchParameter |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-SessionVariable
Hiermee maakt u een webaanvraagsessie en slaat u deze op in de waarde van de opgegeven variabele.
Voer een variabelenaam in zonder het dollarteken ($) symbool.
Wanneer u een sessievariabele opgeeft, maakt Invoke-RestMethod een sessieobject voor webaanvragen en wijst deze toe aan een variabele met de opgegeven naam in uw Windows PowerShell-sessie.
U kunt de variabele in uw sessie gebruiken zodra de opdracht is voltooid.
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 de sessie met webaanvragen wilt gebruiken in volgende webaanvragen, geeft u de sessievariabele op in de waarde van de parameter -WebSession.
Windows 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.
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
| Aliassen: | SV |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | Int32 |
| Default value: | 0 |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-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
| Type: | String |
| Default value: | None |
| Geaccepteerde waarden: | chunked, compress, deflate, gzip, identity |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-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
| Type: | Uri |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | 0 |
| Verplicht: | True |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-UseBasicParsing
Geeft aan dat de cmdlet basisparsering gebruikt. De cmdlet geeft de onbewerkte HTML terug in een Tekenreeks-object.
Parametereigenschappen
| Type: | SwitchParameter |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-UseDefaultCredentials
Gebruikt de referenties van de huidige gebruiker om de webaanvraag te verzenden.
Parametereigenschappen
| Type: | SwitchParameter |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-UserAgent
Hiermee stelt u een gebruikersagent-tekenreeks voor de webaanvraag in.
De standaardgebruikersagent is vergelijkbaar met Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" met lichte 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 PSUserAgent-klasse, zoals Chrome, FireFox, Internet Explorer, Opera en Safari.
De volgende opdracht maakt bijvoorbeeld gebruik van de tekenreeks van de gebruikersagent voor internet
Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-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.
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 (zonder dollarteken) in de waarde van de parameter -SessionVariable van een Invoke-RestMethod opdracht in.
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 parameters -SessionVariable en -WebSession niet gebruiken in dezelfde opdracht.
Parametereigenschappen
| Type: | WebRequestSession |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
CommonParameters
Deze cmdlet ondersteunt de algemene parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction en -WarningVariable. Zie about_CommonParametersvoor meer informatie.
Invoerwaarden
Object
U kunt de hoofdtekst van een webaanvraag doorsluisen naar Invoke-RestMethod.
Uitvoerwaarden
System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String
De uitvoer van de cmdlet is afhankelijk van de indeling van de inhoud die wordt opgehaald.
PSObject
Als de aanvraag JSON-tekenreeksen retourneert, retourneert Invoke-RestMethod een PSObject dat de tekenreeksen vertegenwoordigt.