Invoke-RestMethod
Invia una richiesta HTTP o HTTPS a un servizio Web RESTful.
Sintassi
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-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>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-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>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-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>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-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>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Descrizione
Il Invoke-RestMethod cmdlet invia richieste HTTP e HTTPS ai servizi Web REST (Representational State Transfer) che restituiscono dati strutturati.
PowerShell formatta la risposta in base al tipo di dati. Per un feed RSS o ATOM, PowerShell restituisce i nodi ITEM o Entry XML. Per JavaScript Object Notation (JSON) o XML, PowerShell converte o deserializza il contenuto in [PSCustomObject] oggetti.
Nota
Quando l'endpoint REST restituisce più oggetti, gli oggetti vengono ricevuti come matrice. Se si invia tramite pipe l'output da Invoke-RestMethod a un altro comando, viene inviato come singolo [Object[]] oggetto. Il contenuto di tale matrice non viene enumerato per il comando successivo nella pipeline.
Questo cmdlet è stato introdotto in Windows PowerShell 3.0.
A partire da PowerShell 7.0, Invoke-RestMethod supporta la configurazione proxy definita dalle variabili di ambiente. Vedere la sezione Note di questo articolo.
Esempio
Esempio 1: Ottenere il feed RSS di PowerShell
Questo esempio usa il Invoke-RestMethod cmdlet per ottenere informazioni dal feed RSS del blog di PowerShell. Il comando usa il Format-Table cmdlet per visualizzare i valori delle proprietà Title e pubDate di ogni blog in una tabella.
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 +0000Esempio 2: Eseguire una richiesta POST
In questo esempio, un utente esegue Invoke-RestMethod per eseguire una richiesta POST in un sito Web Intranet nell'organizzazione dell'utente.
$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.csvLe credenziali vengono richieste e quindi archiviate in $Cred e l'URL a cui verrà eseguito l'accesso viene definito in $Url.
La $Body variabile descrive i criteri di ricerca, specifica csv come modalità di output e specifica un periodo di tempo per i dati restituiti che iniziano due giorni fa e termina un giorno fa. La variabile corpo specifica i valori per i parametri che si applicano all'API REST specifica con cui Invoke-RestMethod comunica.
Il Invoke-RestMethod comando viene eseguito con tutte le variabili sul posto, specificando un percorso e un nome di file per il file di output CSV risultante.
Esempio 3: Seguire i collegamenti alle relazioni
Alcune API REST supportano l'impaginazione tramite collegamenti di relazione per RFC5988. Invece di analizzare l'intestazione per ottenere l'URL per la pagina successiva, è possibile usare il cmdlet . Questo esempio restituisce le prime due pagine di problemi del repository GitHub di PowerShell.
$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2Esempio 4: Invio semplificato di dati multipart/form-data
Alcune API richiedono multipart/form-data l'invio di file e contenuti misti. Questo esempio illustra come aggiornare il profilo di un utente.
$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 $FormIl modulo del profilo richiede i campi seguenti: firstName, lastNameemail, , avatarbirthday, e hobbies. L'API prevede l'inserimento di un'immagine per l'immagine del profilo utente nel avatar campo. L'API accetterà anche più hobbies voci da inviare nello stesso modulo.
Quando si crea HashTable $Form , i nomi delle chiavi vengono usati come nomi di campo modulo. Per impostazione predefinita, i valori di HashTable verranno convertiti in stringhe. Se è presente un System.IO.FileInfo valore, il contenuto del file verrà inviato. Se sono presenti raccolte come matrici o elenchi, il campo modulo verrà inviato più volte.
Get-Item Usando sulla avatar chiave, l'oggetto FileInfo verrà impostato come valore. Il risultato è che i dati dell'immagine per jdoe.png verranno inviati.
Fornendo un elenco alla hobbies chiave, il hobbies campo sarà presente negli invii una volta per ogni voce di elenco.
Esempio 5: Passare più intestazioni
Le API spesso richiedono intestazioni passate per l'autenticazione o la convalida. Questo esempio illustra come passare più intestazioni da a hash-table un'API REST.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $bodyEsempio 6: Enumerare gli elementi restituiti nella pipeline
GitHub restituisce più oggetti una matrice. Se si invia tramite pipe l'output a un altro comando, viene inviato come singolo [Object[]]oggetto.
Per enumerare gli oggetti nella pipeline, inviare tramite pipe i risultati o Write-Output eseguire il wrapping del cmdlet tra parentesi. L'esempio seguente conta il numero di oggetti restituiti da GitHub. Conta quindi il numero di oggetti enumerati nella pipeline.
$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
30Esempio 7: ignorare la convalida dell'intestazione
Per impostazione predefinita, il Invoke-RestMethod cmdlet convalida i valori delle intestazioni note con un formato di valore definito da standardards. Nell'esempio seguente viene illustrato come questa convalida può generare un errore e come usare il parametro SkipHeaderValidation per evitare la convalida dei valori per gli endpoint che tollerano valori formattati in modo non valido.
$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} httpbin.org è un servizio che restituisce informazioni sulle richieste Web e le risposte per la risoluzione dei problemi. La $Uri variabile viene assegnata all'endpoint /headers del servizio, che restituisce le intestazioni di una richiesta come contenuto nella risposta.
L'intestazione If-Match della richiesta è definita nella sezione RFC-7232 3.1 e richiede che il valore per tale intestazione venga definito con le virgolette circostanti. Alla $InvalidHeaders variabile viene assegnata una tabella hash in cui il valore di If-Match non è valido perché è definito come 12345 anziché "12345".
La chiamata Invoke-RestMethod con le intestazioni non valide restituisce una segnalazione errori che indica che il valore formattato non è valido. La richiesta non viene inviata all'endpoint.
La chiamata Invoke-RestMethod con il parametro SkipHeaderValidation ignora l'errore di convalida e invia la richiesta all'endpoint. Poiché l'endpoint tollera valori di intestazione non conformi, il cmdlet restituisce l'oggetto risposta senza errori.
Esempio 8: Inviare una richiesta con HTTP 2.0
Questo esempio esegue una query per il problema di GitHub usando il protocollo HTTP 2.0.
$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheckParametri
-AllowUnencryptedAuthentication
Consente l'invio di credenziali e segreti su connessioni non crittografate. Per impostazione predefinita, fornire credenziali o qualsiasi opzione di autenticazione con un URI che non inizia con https:// genererà un errore e la richiesta interromperà per impedire la comunicazione involontaria dei segreti in testo normale su connessioni non crittografate. Per eseguire l'override di questo comportamento a proprio rischio, specificare il parametro AllowUnencryptedAuthentication .
Avviso
L'uso di questo parametro non è sicuro e non è consigliato. Viene fornito solo per compatibilità con i sistemi legacy che non possono fornire connessioni crittografate. Usare a proprio rischio.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Authentication
Specifica il tipo di autenticazione esplicito da utilizzare per la richiesta. L'impostazione predefinita è None (Nessuna). Il parametro Authentication non può essere usato con il parametro UseDefaultCredentials .
Opzioni di autenticazione disponibili:
None: questa è l'opzione predefinita quando non viene specificata l'autenticazione . Non verrà usata alcuna autenticazione esplicita.Basic: richiede credenziali. Le credenziali verranno usate per inviare un'intestazione di autenticazioneAuthorization: Basicdi base RFC 7617 nel formato dibase64(user:password).Bearer: richiede il parametro Token . Invia un'intestazione RFC 6750Authorization: Bearercon il token fornito.OAuth: richiede il parametro Token . Invia un'intestazione RFC 6750Authorization: Bearercon il token fornito.
L'opzione Autenticazione esegue l'override di tutte Authorization le intestazioni fornite alle intestazioni o incluse in WebSession.
Questa funzionalità è stata aggiunta 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
Specifica il corpo della richiesta. Il corpo corrisponde al contenuto della richiesta che segue le intestazioni.
È anche possibile inviare tramite pipe un valore del corpo a Invoke-RestMethod.
Il parametro Body può essere usato per specificare un elenco di parametri di query o specificare il contenuto della risposta.
Quando l'input è una richiesta POST e il corpo è string, il valore a sinistra del primo segno di uguale (=) viene impostato come chiave nei dati del modulo e il testo rimanente viene impostato come valore. Per specificare più chiavi, usare un oggetto IDictionary, ad esempio una tabella hash, per Body.
Quando l'input è una richiesta GET e il corpo è un IDictionary (in genere, una tabella hash), il corpo viene aggiunto all'URI come parametri di query. Per altri tipi di richiesta , ad esempio PATCH, il corpo viene impostato come valore del corpo della richiesta nel formato standard name=value con i valori con codifica URL.
Quando l'input è un oggetto System.Xml.XmlNode e la dichiarazione XML specifica una codifica, tale codifica viene utilizzata per i dati nella richiesta, a meno che non venga sottoposto a override dal parametro ContentType .
Quando il corpo è un modulo o è l'output di un'altra Invoke-WebRequest chiamata, PowerShell imposta il contenuto della richiesta sui campi modulo.
Il parametro Body può anche accettare un oggetto System.Net.Http.MultipartFormDataContent . Ciò faciliterà multipart/form-data le richieste. Quando viene fornito un oggetto MultipartFormDataContent per Body, tutte le intestazioni correlate al contenuto fornite ai parametri ContentType, Headers o WebSession verranno sostituite dalle intestazioni di contenuto dell'oggetto MultipartFormDataContent . Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Certificate
Specifica il certificato client usato per una richiesta Web sicura. Immettere una variabile che contiene un certificato oppure un comando o un'espressione che ottiene il certificato.
Per trovare un certificato, usare Get-PfxCertificate o usare il Get-ChildItem cmdlet nell'unità Certificato (Cert:). Se il certificato non è valido o non dispone di un'autorità sufficiente, il comando ha esito negativo.
| Type: | X509Certificate |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CertificateThumbprint
Specifica il certificato di chiave pubblica digitale (X509) di un account utente con autorizzazione per l'invio della richiesta. Immettere l'identificazione personale del certificato.
I certificati vengono usati nell'autenticazione basata sui certificati client. I certificati possono essere mappati solo agli account utente locali, non agli account di dominio.
Per visualizzare l'identificazione personale del certificato, usare il Get-Item comando o Get-ChildItem per trovare il certificato in Cert:\CurrentUser\My.
Nota
Questa funzionalità è attualmente supportata solo nelle piattaforme del sistema operativo Windows.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ContentType
Specifica il tipo di contenuto della richiesta Web.
Se il valore di ContentType contiene il formato di codifica (come charset), il cmdlet usa tale formato per codificare il corpo della richiesta Web. Se ContentType non specifica un formato di codifica, viene invece usato il formato di codifica predefinito. Un esempio di ContentType con un formato di codifica è text/plain; charset=iso-8859-5, che specifica l'alfabeto latino/cirillico.
Se questo parametro viene omesso e il metodo di richiesta è POST, Invoke-RestMethod imposta il tipo di contenuto su application/x-www-form-urlencoded. In caso contrario, il tipo di contenuto non viene specificato nella chiamata.
ContentType verrà sottoposto a override quando viene fornito un MultipartFormDataContent oggetto per Body.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Credential
Specifica un account utente che dispone dell'autorizzazione per l'invio della richiesta. Il valore predefinito è l'utente corrente.
Digitare un nome utente, ad esempio User01 o Domain01\User01, oppure immettere un oggetto PSCredential generato dal Get-Credential cmdlet.
Le credenziali possono essere usate da sole o in combinazione con determinate opzioni di parametro di autenticazione . Se usato da solo, fornirà le credenziali al server remoto solo se il server remoto invia una richiesta di verifica dell'autenticazione. Se usato con le opzioni di autenticazione , le credenziali verranno inviate in modo esplicito.
Le credenziali vengono archiviate in un oggetto PSCredential e la password viene archiviata come SecureString.
Nota
Per altre informazioni sulla protezione dei dati SecureString , vedere How secure is SecureString?.
| Type: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CustomMethod
Specifica il metodo personalizzato utilizzato per la richiesta Web. Questa opzione può essere usata con il metodo di richiesta richiesto dall'endpoint non è un'opzione disponibile nel metodo . Il metodo e CustomMethod non possono essere usati insieme.
Esempio:
Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
In questo modo viene eseguita una TEST richiesta HTTP all'API.
Questa funzionalità è stata aggiunta 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
Indica che il cmdlet imposta il valore KeepAlive nell'intestazione HTTP su False. Per impostazione predefinita, KeepAlive è True. KeepAlive stabilisce una connessione permanente al server per facilitare le richieste successive.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FollowRelLink
Indica che il cmdlet deve seguire i collegamenti di relazione.
Alcune API REST supportano l'impaginazione tramite collegamenti di relazione per RFC5988. Invece di analizzare l'intestazione per ottenere l'URL per la pagina successiva, è possibile usare il cmdlet . Per impostare il numero di volte in cui seguire i collegamenti di relazione, usare il parametro MaximumFollowRelLink .
Quando si usa questa opzione, il cmdlet restituisce una raccolta di pagine di risultati. Ogni pagina di risultati può contenere più elementi di risultato.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | SwitchParameter |
| Aliases: | FL |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Form
Converte un dizionario in un multipart/form-data invio. Il modulo non può essere utilizzato con Body.
Se ContentType verrà ignorato.
Le chiavi del dizionario verranno usate come nomi dei campi del modulo. Per impostazione predefinita, i valori del modulo verranno convertiti in valori stringa.
Se il valore è un oggetto System.IO.FileInfo , verrà inviato il contenuto del file binario.
Il nome del file verrà inviato come filename. MIME verrà impostato su application/octet-stream. Get-Item può essere usato per semplificare la fornitura dell'oggetto System.IO.FileInfo .
$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
Se il valore è un tipo di raccolta, ad esempio matrice o elenco, il campo per verrà inviato più volte. I valori dell'elenco verranno considerati come stringhe per impostazione predefinita. Se il valore è un oggetto System.IO.FileInfo , verrà inviato il contenuto del file binario. Le raccolte annidate non sono supportate.
$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
Nell'esempio precedente, il tags campo verrà fornito tre volte nel modulo, una volta per ognuno di Vacation, Italye 2017. Il pictures campo verrà inviato anche una volta per ogni file nella 2017-Italy cartella . Il contenuto binario dei file in tale cartella verrà inviato come valori.
Questa funzionalità è stata aggiunta in PowerShell 6.1.0.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Headers
Specifica le intestazioni della richiesta Web. Immettere una tabella hash o un dizionario.
Le intestazioni correlate al contenuto, ad esempio Content-Type vengono sottoposte a override quando viene fornito un MultipartFormDataContent oggetto per Body.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-HttpVersion
Specifica la versione HTTP usata per la richiesta. Il valore predefinito è 1.1.
I valori validi sono:
- 1.0
- 1.1
- 2.0
- 3,0
| Type: | Version |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InFile
Ottiene il contenuto della richiesta Web da un file.
Immettere un percorso e un nome file. Se si omette il percorso, l'impostazione predefinita è il percorso corrente.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumFollowRelLink
Specifica quante volte seguire i collegamenti di relazione se viene usato FollowRelLink . Potrebbe essere necessario un valore inferiore se l'API REST limita a causa di troppe richieste. Il valore predefinito è [Int32]::MaxValue. Il valore 0 (zero) impedisce i collegamenti di relazione seguenti.
| Type: | Int32 |
| Aliases: | ML |
| Position: | Named |
| Default value: | Int32.MaxValue |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRedirection
Specifica quante volte PowerShell reindirizza una connessione a un URI (Uniform Resource Identifier) alternativo prima che la connessione non riesca. Il valore predefinito è 5. Il valore 0 (zero) impedisce qualsiasi reindirizzamento.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRetryCount
Specifica quante volte PowerShell ritenta una connessione quando viene ricevuto un codice di errore compreso tra 400 e 599 inclusi o 304. Vedere anche il parametro RetryIntervalSec per specificare il numero di secondi tra i tentativi.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Method
Specifica il metodo usato per la richiesta Web. I valori validi per questo parametro sono:
DefaultDeleteGetHeadMergeOptionsPatchPostPutTrace
Il parametro CustomMethod può essere usato per i metodi di richiesta non elencati in precedenza.
| 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
Indica che il cmdlet non userà un proxy per raggiungere la destinazione.
Quando è necessario ignorare il proxy configurato in Internet Explorer o un proxy specificato nell'ambiente, usare questa opzione.
Questo parametro è stato introdotto in PowerShell 6.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OutFile
Salva il corpo della risposta nel file di output specificato. Immettere un percorso e un nome file. Se si omette il percorso, l'impostazione predefinita è il percorso corrente. Il nome viene considerato come percorso letterale. I nomi contenenti parentesi quadre ([]) devono essere racchiusi tra virgolette singole (').
Per impostazione predefinita, Invoke-RestMethod restituisce i risultati alla pipeline.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PassThru
Questo parametro è valido solo quando il parametro OutFile viene usato anche nel comando . Lo scopo consiste nel fare in modo che i risultati vengano scritti nel file e nella pipeline.
Nota
Quando si usa il parametro PassThru , l'output viene scritto nella pipeline, ma il file non viene creato. Per altre informazioni, vedere Problema di PowerShell n. 15409.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | No output |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Indica che il cmdlet deve mantenere l'intestazione Authorization , se presente, tra reindirizzamenti.
Per impostazione predefinita, il cmdlet rimuove l'intestazione prima del Authorization reindirizzamento. Se si specifica questo parametro, questa logica viene disabilitata per i casi in cui l'intestazione deve essere inviata al percorso di reindirizzamento.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Proxy
Usa un server proxy per la richiesta, anziché connettersi direttamente alla risorsa Internet. Immettere l'URI (Uniform Resource Identifier) di un server proxy di rete.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | Uri |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyCredential
Specifica un account utente autorizzato a usare il server proxy specificato dal parametro Proxy . Il valore predefinito è l'utente corrente.
Digitare un nome utente, ad esempio User01 o Domain01\User01, User@Domain.Como immettere un PSCredential oggetto, ad esempio quello generato dal Get-Credential cmdlet.
Questo parametro è valido solo quando il parametro Proxy viene usato anche nel comando . Non è possibile usare i parametri ProxyCredential e ProxyUseDefaultCredentials nello stesso comando.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
Indica che il cmdlet usa le credenziali dell'utente corrente per accedere al server proxy specificato dal parametro Proxy .
Questo parametro è valido solo quando il parametro Proxy viene usato anche nel comando . Non è possibile usare i parametri ProxyCredential e ProxyUseDefaultCredentials nello stesso comando.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ResponseHeadersVariable
Crea una variabile contenente un dizionario intestazioni di risposta. Immettere un nome di variabile senza il simbolo del dollaro ($). Le chiavi del dizionario contengono i nomi dei campi e i valori dell'intestazione della risposta restituita dal server Web.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | String |
| Aliases: | RHV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Resume
Esegue un tentativo di lavoro ottimale per riprendere il download di un file parziale. Il parametro Resume richiede il parametro OutFile .
Resume opera solo sulle dimensioni del file locale e del file remoto e non esegue altre convalide che il file locale e il file remoto siano uguali.
Se le dimensioni del file locale sono inferiori alle dimensioni del file remoto, il cmdlet tenterà di riprendere il download del file e di accodare i byte rimanenti alla fine del file.
Se le dimensioni del file locale corrispondono alle dimensioni del file remoto, non viene eseguita alcuna azione e il cmdlet presuppone che il download sia già stato completato.
Se le dimensioni del file locale sono maggiori delle dimensioni del file remoto, il file locale verrà sovrascritto e l'intero file remoto verrà scaricato completamente. Questo comportamento equivale all'uso di OutFile senza Resume.
Se il server remoto non supporta la ripresa del download, il file locale verrà sovrascritto e l'intero file remoto verrà scaricato completamente. Questo comportamento equivale all'uso di OutFile senza Resume.
Se il file locale non esiste, il file locale verrà creato e l'intero file remoto verrà scaricato completamente. Questo comportamento equivale all'uso di OutFile senza Resume.
Questa funzionalità è stata aggiunta in PowerShell 6.1.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RetryIntervalSec
Specifica l'intervallo tra i tentativi di connessione quando viene ricevuto un codice di errore compreso tra 400 e 599 inclusi o 304. Il valore deve essere compreso tra 1 e [int]::MaxValue.
Vedere anche il parametro MaximumRetryCount per specificare il numero di tentativi.
| Type: | Int32 |
| Position: | Named |
| Default value: | 5 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SessionVariable
Crea una variabile contenente la sessione di richiesta Web. Immettere un nome di variabile senza il simbolo del dollaro ($).
Quando si specifica una variabile di sessione, Invoke-RestMethod crea un oggetto sessione di richiesta Web e lo assegna a una variabile con il nome specificato nella sessione di PowerShell. È possibile usare la variabile nella sessione appena il comando termina l'esecuzione.
Prima di PowerShell 7.4, la sessione di richiesta Web non è una connessione permanente. Si tratta di un oggetto che contiene informazioni sulla connessione e sulla richiesta, inclusi cookie, credenziali, il valore massimo di reindirizzamento e la stringa dell'agente utente. È possibile usarlo per condividere lo stato e i dati tra le richieste Web.
A partire da PowerShell 7.4, la sessione di richiesta Web è persistente, purché le proprietà della sessione non vengano sottoposte a override in una richiesta successiva. Quando sono, il cmdlet ricrea la sessione con i nuovi valori. Le sessioni persistenti riducono il sovraccarico per le richieste ripetute, rendendole molto più veloci.
Per usare la sessione di richiesta Web nelle richieste Web successive, specificare la variabile di sessione nel valore del parametro WebSession . PowerShell usa i dati nell'oggetto sessione di richiesta Web quando si stabilisce la nuova connessione. Per eseguire l'override di un valore nella sessione di richiesta Web, usare un parametro cmdlet, ad esempio UserAgent o Credential. I valori di parametro hanno la precedenza sui valori nella sessione di richieste Web.
Non è possibile usare i parametri SessionVariable e WebSession nello stesso comando.
| Type: | String |
| Aliases: | SV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipCertificateCheck
Ignora i controlli di convalida dei certificati che includono tutte le convalide, ad esempio scadenza, revoca, autorità radice attendibile e così via.
Avviso
L'uso di questo parametro non è sicuro e non è consigliato. Questa opzione deve essere usata solo per gli host noti usando un certificato autofirmato a scopo di test. Usare a proprio rischio.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHeaderValidation
Indica che il cmdlet deve aggiungere intestazioni alla richiesta senza convalida.
Questa opzione deve essere usata per i siti che richiedono valori di intestazione non conformi agli standard. Se si specifica questa opzione, la convalida viene disabilitata per consentire il passaggio del valore deselezionato. Se specificato, tutte le intestazioni vengono aggiunte senza convalida.
Verrà disabilitata la convalida per i valori passati ai parametri ContentType, Headers e UserAgent .
Questa funzionalità è stata aggiunta in PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHttpErrorCheck
Questo parametro fa sì che il cmdlet ignori gli stati di errore HTTP e continui a elaborare le risposte. Le risposte di errore vengono scritte nella pipeline esattamente come se avessero esito positivo.
Questo parametro è stato introdotto in PowerShell 7.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SslProtocol
Imposta i protocolli SSL/TLS consentiti per la richiesta Web. Per impostazione predefinita, tutti i protocolli SSL/TLS supportati dal sistema sono consentiti. SslProtocol consente di limitare protocolli specifici a scopo di conformità.
Questi valori sono definiti come enumerazione basata su flag. È possibile combinare più valori per impostare più flag usando questo parametro. I valori possono essere passati al parametro SslProtocol come matrice di valori o come stringa delimitata da virgole di tali valori. Il cmdlet combina i valori usando un'operazione binary-OR. Il passaggio di valori come matrice è l'opzione più semplice e consente anche di usare il completamento tramite tabulazione sui valori. Potrebbe non essere possibile specificare più valori in tutte le piattaforme.
Nota
Nelle piattaforme non Windows potrebbe non essere possibile fornire Tls o Tls12 come opzione. Il supporto per Tls13 non è disponibile in tutti i sistemi operativi e deve essere verificato in base al sistema operativo.
Questa funzionalità è stata aggiunta in PowerShell 6.0.0 e il supporto per Tls13 è stato aggiunto in PowerShell 7.1.
| Type: | WebSslProtocol |
| Accepted values: | Default, Tls, Tls11, Tls12, Tls13 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-StatusCodeVariable
Crea una variabile contenente un risultato del codice di stato HTTP della richiesta. Immettere un nome di variabile senza il simbolo del dollaro ($).
Il parametro può identificare i messaggi di esito positivo o i messaggi di errore quando vengono usati con il parametro SkipHttpErrorCheck .
Immettere il nome della variabile del parametro come stringa, -StatusCodeVariable "scv"ad esempio .
Questo parametro è stato introdotto in PowerShell 7.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TimeoutSec
Specifica per quanto tempo la richiesta può essere in sospeso prima del timeout. Immettere un valore in secondi. Il valore predefinito, 0, specifica un timeout indefinito.
La restituzione o il timeout di una query DNS (Domain Name System) può richiedere fino a 15 secondi. Se la richiesta contiene un nome host che richiede la risoluzione e si imposta TimeoutSec su un valore maggiore di zero, ma inferiore a 15 secondi, possono essere necessari 15 secondi o più prima che venga generata un'eccezione WebException e il timeout della richiesta.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Token
Token OAuth o Bearer da includere nella richiesta. Il token è richiesto da determinate opzioni di autenticazione . Non può essere usato in modo indipendente.
Il token accetta un SecureString oggetto che contiene il token. Per fornire il token, usare manualmente quanto segue:
Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
Questo parametro è stato introdotto in PowerShell 6.0.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TransferEncoding
Specifica un valore per l'intestazione della risposta HTTP con codifica di trasferimento. I valori validi per questo parametro sono:
- Chunked
- Compressione
- Sgonfiare
- GZip
- Identità
| 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
Specifica l'URI (Uniform Resource Identifier) della risorsa Internet a cui viene inviata la richiesta Web. Questo parametro supporta i valori HTTP, HTTPS, FTP e FILE.
Questo parametro è obbligatorio. Il nome del parametro (Uri) è facoltativo.
| Type: | Uri |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseBasicParsing
Questo parametro è stato deprecato. A partire da PowerShell 6.0.0, tutte le richieste Web usano solo l'analisi di base. Questo parametro è incluso solo per la compatibilità con le versioni precedenti e qualsiasi uso di esso non avrà alcun effetto sull'operazione del cmdlet.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseDefaultCredentials
Indica che il cmdlet usa le credenziali dell'utente corrente per inviare la richiesta Web. Questo non può essere usato con l'autenticazione o le credenziali e potrebbe non essere supportato in tutte le piattaforme.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserAgent
Specifica una stringa agente utente per la richiesta Web.
L'agente utente predefinito è simile a Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 con lievi variazioni per ogni sistema operativo e piattaforma.
Per testare un sito Web con la stringa dell'agente utente standard usata dalla maggior parte dei browser Internet, usare le proprietà della classe PSUserAgent , ad esempio Chrome, FireFox, InternetExplorer, Opera e Safari.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WebSession
Specifica una sessione di richieste Web. Immettere il nome della variabile, incluso il segno di dollaro ($).
Per eseguire l'override di un valore nella sessione di richiesta Web, usare un parametro cmdlet, ad esempio UserAgent o Credential. I valori di parametro hanno la precedenza sui valori nella sessione di richieste Web. Anche le intestazioni correlate al contenuto, ad esempio Content-Type, verranno sottoposte a override quando viene fornito un oggetto MultipartFormDataContent per Body.
A differenza di una sessione remota, la sessione di richiesta Web non è una connessione permanente. Si tratta di un oggetto che contiene informazioni sulla connessione e sulla richiesta, inclusi cookie, credenziali, il valore massimo di reindirizzamento e la stringa dell'agente utente. È possibile usarlo per condividere lo stato e i dati tra le richieste Web.
Per creare una sessione di richiesta Web, immettere un nome di variabile, senza un segno di dollaro, nel valore del parametro SessionVariable di un Invoke-RestMethod comando. Invoke-RestMethod crea la sessione e la salva nella variabile . Nei comandi successivi usare la variabile come valore del parametro WebSession .
Non è possibile usare i parametri SessionVariable e WebSession nello stesso comando.
| Type: | WebRequestSession |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Input
È possibile inviare tramite pipe il corpo di una richiesta Web a questo cmdlet.
Output
Quando la richiesta restituisce un numero intero, questo cmdlet restituisce l'intero.
Quando la richiesta restituisce una stringa, questo cmdlet restituisce tale stringa.
Quando la richiesta restituisce codice XML valido, questo cmdlet lo restituisce come XmlDocument.
PSObject
Quando la richiesta restituisce stringhe JSON, questo cmdlet restituisce un PSObject che rappresenta i dati.
Note
PowerShell include gli alias seguenti per Invoke-RestMethod:
- Tutte le piattaforme:
irm
Alcune funzionalità potrebbero non essere disponibili in tutte le piattaforme.
A causa delle modifiche apportate a .NET Core 3.1, PowerShell 7.0 e versioni successive usano la proprietà HttpClient.DefaultProxy per determinare la configurazione del proxy.
Il valore di questa proprietà è regole diverse a seconda della piattaforma:
- Per Windows: legge la configurazione del proxy dalle variabili di ambiente o, se non sono definite, dalle impostazioni proxy dell'utente.
- Per macOS: legge la configurazione del proxy dalle variabili di ambiente o, se non sono definite, dalle impostazioni proxy del sistema.
- Per Linux: legge la configurazione del proxy dalle variabili di ambiente o, nel caso in cui non siano definite, questa proprietà inizializza un'istanza non configurata che ignora tutti gli indirizzi.
Le variabili di ambiente usate per DefaultProxy l'inizializzazione nelle piattaforme basate su Windows e Unix sono:
HTTP_PROXY: nome host o indirizzo IP del server proxy usato nelle richieste HTTP.HTTPS_PROXY: nome host o indirizzo IP del server proxy usato nelle richieste HTTPS.ALL_PROXY: il nome host o l'indirizzo IP del server proxy usato nelle richieste HTTP e HTTPS nel casoHTTP_PROXYoHTTPS_PROXYnon siano definiti.NO_PROXY: elenco delimitato da virgole di nomi host che devono essere esclusi dal proxy.
Collegamenti correlati
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per