Invoke-RestMethod
Verzendt een HTTP- of HTTPS-aanvraag naar een RESTful-webservice.
Syntax
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.
PowerShell formatteert het antwoord op basis van het gegevenstype. Voor een RSS- of ATOM-feed retourneert PowerShell de XML-knooppunten Item of Entry. Voor JavaScript Object Notation (JSON) of XML converteert PowerShell de inhoud naar [PSCustomObject]
objecten of deserialisaties.
Notitie
Wanneer het REST-eindpunt meerdere objecten retourneert, worden de objecten ontvangen als een matrix. Als u de uitvoer naar Invoke-RestMethod
een andere opdracht doorgeeft, wordt deze verzonden als één [Object[]]
object. De inhoud van die matrix wordt niet geïnventariseerd voor de volgende opdracht in de pijplijn.
Deze cmdlet wordt geïntroduceerd in Windows PowerShell 3.0.
Notitie
Standaard kan scriptcode op de webpagina worden uitgevoerd wanneer de pagina wordt geparseerd om de ParsedHtml
eigenschap te vullen. Gebruik de schakeloptie UseBasicParsing om dit te onderdrukken.
Voorbeelden
Voorbeeld 1: De PowerShell RSS-feed ophalen
Invoke-RestMethod -Uri https://devblogs.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
Met deze opdracht wordt de Invoke-RestMethod
cmdlet gebruikt om informatie op te halen uit de RSS-feed van de PowerShell-blog. De opdracht gebruikt de Format-Table
cmdlet om de waarden van de eigenschappen Title en pubDate van elke blog in een tabel weer te geven.
Voorbeeld 2
In het volgende voorbeeld voert Invoke-RestMethod
een gebruiker een POST-aanvraag uit op een intranetwebsite in de organisatie van de gebruiker.
$Cred = Get-Credential
# Next, allow the use of self-signed SSL certificates.
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }
# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.
$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as
# the output mode, and specifies a time period for returned data that starts two days ago and ends
# one day ago. The body variable specifies values for parameters that apply to the particular REST
# API with which Invoke-RestMethod is communicating.
$Body = @{
search = $Search
output_mode = "csv"
earliest_time = "-2d@d"
latest_time = "-1d@d"
}
# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file
# name for the resulting CSV output file.
Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv
{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}
{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}
{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}
{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}
Voorbeeld 3: Meerdere headers doorgeven
In dit voorbeeld ziet u hoe u meerdere headers van een hash-table
naar een REST API doorgeeft.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
API's vereisen vaak doorgegeven headers voor verificatie, validatie, enzovoort.
Voorbeeld 3: Formuliergegevens verzenden
Wanneer de hoofdtekst een formulier is of als uitvoer van een andere Invoke-WebRequest
aanroep, stelt 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]
Voorbeeld 4: Geretourneerde items opsommen in de pijplijn
GitHub retourneert meerdere objecten een matrix. Als u de uitvoer doorgeeft aan een andere opdracht, wordt deze verzonden als één [Object[]]
object.
Als u de objecten in de pijplijn wilt inventariseren, sluist u de resultaten door naar Write-Output
of verpakt u de cmdlet tussen haakjes. In het volgende voorbeeld wordt het aantal objecten geteld dat door GitHub wordt geretourneerd. Vervolgens wordt het aantal objecten geteld dat is geïnventariseerd aan 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
Parameters
-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-RestMethod
.
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 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 ingesteld als de waarde van de aanvraagbody 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.
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 onvoldoende autoriteit heeft, 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\My
te zoeken.
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 deze parameter wordt weggelaten en de aanvraagmethode POST is, Invoke-RestMethod
stelt u het inhoudstype in op 'application/x-www-form-urlencoded'. Anders wordt het inhoudstype niet opgegeven in de aanroep.
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 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 |
-DisableKeepAlive
Hiermee stelt u de waarde KeepAlive in de HTTP-header in 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: | KeepAlive |
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.
Als u UserAgent-headers wilt instellen, gebruikt u de parameter UserAgent . U kunt deze parameter niet gebruiken om UserAgent- of cookieheaders op te geven.
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
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 dat alle omleidingen worden omgeleid.
Type: | Int32 |
Position: | Named |
Default value: | 5 |
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
Type: | WebRequestMethod |
Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Default value: | Default |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Invoke-RestMethod
Retourneert standaard de resultaten naar de pijplijn.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Deze parameter is alleen geldig wanneer de outfile-parameter ook wordt gebruikt in de opdracht. De bedoeling is dat de resultaten naar het bestand en naar de pijplijn worden geschreven.
Notitie
Wanneer u de PassThru-parameter gebruikt, wordt de uitvoer naar de pijplijn geschreven, maar is het bestand leeg. Zie PowerShell-probleem 15409 voor meer informatie.
Type: | SwitchParameter |
Position: | Named |
Default value: | No output |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
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 voor het gebruik van de proxyserver 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
Gebruikt de referenties van de huidige gebruiker 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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-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
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.
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 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 |
-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 |
-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. Deze parameter ondersteunt HTTP-, HTTPS-, FTP- en FILE-waarden.
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
Geeft aan dat de cmdlet basisparsering gebruikt. De cmdlet retourneert de onbewerkte HTML in een tekenreeksobject .
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseDefaultCredentials
Gebruikt de referenties van de huidige gebruiker om de webaanvraag te verzenden.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
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 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 klasse PSUserAgent , zoals Chrome, FireFox, Internet Explorer, Opera en Safari.
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.
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 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
U kunt de hoofdtekst van een webaanvraag doorsluisen naar deze cmdlet.
Uitvoerwaarden
Wanneer de aanvraag een geheel getal retourneert, retourneert deze cmdlet dat gehele getal.
Wanneer de aanvraag een tekenreeks retourneert, retourneert deze cmdlet die tekenreeks.
Wanneer de aanvraag geldige XML retourneert, retourneert deze cmdlet deze als xmldocument.
PSObject
Wanneer de aanvraag JSON-tekenreeksen retourneert, retourneert deze cmdlet een PSObject dat de gegevens vertegenwoordigt.
Notities
Windows PowerShell bevat de volgende aliassen voor Invoke-RestMethod
:
irm
Verwante koppelingen
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor