Invoke-RestMethod

Riferimento

Modulo:: Microsoft.PowerShell.Utility

Invia una richiesta HTTP o HTTPS a un servizio Web RESTful.

Sintassi

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

Descrizione

Il cmdlet Invoke-RestMethod 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 oggetti [pscustomobject]. I commenti non sono consentiti nei dati JSON.

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 oggetto [Object[]]. Il contenuto di tale matrice non viene enumerato per il comando successivo nella pipeline.

Questo cmdlet è stato introdotto in Windows PowerShell 3.0.

Nota

Per impostazione predefinita, il codice script nella pagina Web può essere eseguito quando la pagina viene analizzata per popolare la proprietà ParsedHtml. Utilizzare l'opzione UseBasicParsing per sopprimere questo.

Esempio

Esempio 1: Ottenere il feed RSS di PowerShell

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

Questo comando usa il cmdlet Invoke-RestMethod per ottenere informazioni dal feed RSS del blog di PowerShell. Il comando usa il cmdlet Format-Table per visualizzare i valori dell'Title e pubDate proprietà di ogni blog in una tabella.

Esempio 2

Nell'esempio seguente un utente esegue Invoke-RestMethod per eseguire una richiesta POST in un sito Web Intranet nell'organizzazione dell'utente.

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

Esempio 3: Passare più intestazioni

Questo esempio illustra come passare più intestazioni da un hash-table a un'API REST.

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

Le API spesso richiedono intestazioni da passare per l'autenticazione, la convalida, ecc.

Esempio 3: Invio dei dati del modulo

Quando il corpo è un modulo o è l'output di un'altra chiamata Invoke-WebRequest, PowerShell imposta il contenuto della richiesta sui campi modulo.

Per esempio:

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

Esempio 4: Enumerare gli elementi restituiti nella pipeline

GitHub restituisce più oggetti in un array. Se si invia tramite pipe l'output a un altro comando, viene inviato come singolo oggetto [Object[]].

Per enumerare gli oggetti nella pipeline, inviare tramite pipe i risultati a Write-Output o racchiudere il 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
30

Parametri

-Body

Specifica il corpo della richiesta. Il corpo è il contenuto della richiesta che segue le intestazioni. È anche possibile inviare tramite pipe un valore del corpo a Invoke-RestMethod.

Il parametro corpo può essere usato per specificare un elenco di parametri di query o specificare il contenuto della risposta.

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 POST, il corpo viene impostato come valore del corpo della richiesta nel formato nome=valore standard.

Avvertimento

L'output dettagliato di un corpo POST terminerà con with -1-byte payload, anche se la dimensione del corpo è conosciuta e inviata nell'intestazione HTTP Content-Length.

Tipo:	Object
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	True
Accettare caratteri jolly:	False

-Certificate

Specifica il certificato client usato per una richiesta Web sicura. Immettere una variabile contenente un certificato o un comando o un'espressione che ottiene il certificato.

Per trovare un certificato, usare Get-PfxCertificate o usare il cmdlet Get-ChildItem nell'unità Certificate (Cert:). Se il certificato non è valido o non dispone di un'autorità sufficiente, il comando ha esito negativo.

Tipo:	X509Certificate
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-CertificateThumbprint

Specifica il certificato di chiave pubblica digitale (X509) di un account utente autorizzato a inviare la richiesta. Immettere l'impronta digitale del certificato.

I certificati vengono usati nell'autenticazione basata su certificati client. I certificati possono essere mappati solo agli account utente locali, non agli account di dominio.

Per visualizzare l'impronta digitale del certificato, usare il comando Get-Item o Get-ChildItem per trovare il certificato in Cert:\CurrentUser\My.

Tipo:	String
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-ContentType

Specifica il tipo di contenuto della richiesta Web.

Se il valore per ContentType contiene il formato di codifica (come charset), il cmdlet usa tale formato per codificare il corpo della richiesta Web. Se il 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 si omette il parametro , il tipo di contenuto può essere diverso in base al metodo HTTP usato:

Per un metodo POST, il tipo di contenuto è application/x-www-form-urlencoded
Per un metodo PUT, il tipo di contenuto è application/json
Per altri metodi, il tipo di contenuto non viene specificato nella richiesta

Se si usa il parametro InFile per caricare un file, è necessario impostare il tipo di contenuto. In genere, il tipo deve essere application/octet-stream. È tuttavia necessario impostare il tipo di contenuto in base ai requisiti dell'endpoint.

Tipo:	String
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-Credential

Specifica un account utente che dispone dell'autorizzazione per inviare la richiesta. Il valore predefinito è l'utente corrente.

Digitare un nome utente, ad esempio User01 o Domain01\User01oppure immettere un oggetto PSCredential generato dal cmdlet Get-Credential.

Le credenziali vengono archiviate in un oggetto PSCredential e la password viene archiviata come SecureString.

Nota

Per altre informazioni sulla protezione dei dati di SecureString, vedere Quanto è sicuro SecureString?.

Tipo:	PSCredential
Posizione:	Named
Valore predefinito:	Current user
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-DisableKeepAlive

Imposta il valore KeepAlive nell'intestazione HTTP su False. Per impostazione predefinita, KeepAlive è vero. KeepAlive stabilisce una connessione permanente al server per facilitare le richieste successive.

Tipo:	SwitchParameter
Posizione:	Named
Valore predefinito:	False
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-Headers

Specifica le intestazioni della richiesta web. Immettere una tabella hash o un dizionario.

Per impostare le intestazioni UserAgent, utilizzare il parametro UserAgent. Non è possibile utilizzare questo parametro per specificare intestazioni UserAgent o cookie.

Tipo:	IDictionary
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-InFile

Ottiene il contenuto del corpo della richiesta Web da un file. Immettere un percorso e un nome file. Se si omette il percorso, il valore predefinito è il percorso corrente.

È anche necessario impostare il tipo di contenuto della richiesta. Ad esempio, per caricare un file è necessario impostare il tipo di contenuto. In genere, il tipo deve essere application/octet-stream. È tuttavia necessario impostare il tipo di contenuto in base ai requisiti dell'endpoint.

Tipo:	String
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-MaximumRedirection

Determina quante volte Windows 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 tutto il reindirizzamento.

Tipo:	Int32
Posizione:	Named
Valore predefinito:	5
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-Method

Specifica il metodo utilizzato per la richiesta Web. I valori accettabili per questo parametro sono:

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Tipo:	WebRequestMethod
Valori accettati:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Posizione:	Named
Valore predefinito:	Default
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-OutFile

Salva il corpo della risposta nel file di output specificato. Immettere un percorso e un nome file. Se si omette il percorso, il valore predefinito è il percorso corrente.

Per impostazione predefinita, Invoke-RestMethod restituisce i risultati alla pipeline.

Tipo:	String
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-PassThru

Questo parametro è valido solo quando nel comando viene usato anche il parametro outfile. 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 è vuoto. Per altre informazioni, vedere problema di PowerShell #15409.

Tipo:	SwitchParameter
Posizione:	Named
Valore predefinito:	No output
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-Proxy

Usa un server proxy per la richiesta, anziché connettersi direttamente alla risorsa Internet. Immettere l'URI di un server proxy di rete.

Tipo:	Uri
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	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" oppure immettere un oggetto PSCredential, ad esempio quello generato dal cmdlet Get-Credential.

Questo parametro è valido solo quando nel comando viene usato anche il parametro proxy. Non è possibile usare i parametri ProxyCredential e ProxyUseDefaultCredentials nello stesso comando.

Tipo:	PSCredential
Posizione:	Named
Valore predefinito:	Current user
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-ProxyUseDefaultCredentials

Usa le credenziali dell'utente corrente per accedere al server proxy specificato dal parametro proxy.

Tipo:	SwitchParameter
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	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 non appena il comando viene completato.

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 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 Credenziali. I valori dei parametri hanno la precedenza sui valori nella sessione di richiesta Web.

Non è possibile usare i parametri SessionVariable e WebSession nello stesso comando.

Tipo:	String
Alias:	SV
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	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.

Tipo:	Int32
Posizione:	Named
Valore predefinito:	0
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-TransferEncoding

Specifica un valore per l'intestazione della risposta HTTP di codifica di trasferimento. I valori accettabili per questo parametro sono:

Chunked
Compress
Deflate
GZip
Identity

Tipo:	String
Valori accettati:	chunked, compress, deflate, gzip, identity
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-Uri

Specifica l'URI (Uniform Resource Identifier) della risorsa Internet a cui viene inviata la richiesta Web. Questo parametro supporta valori HTTP, HTTPS, FTP e FILE.

Questo parametro è obbligatorio. Il nome del parametro (Uri) è facoltativo.

Tipo:	Uri
Posizione:	0
Valore predefinito:	None
Necessario:	True
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-UseBasicParsing

Indica che il cmdlet usa l'analisi di base. Il cmdlet restituisce il codice HTML non elaborato in un oggetto string .

Tipo:	SwitchParameter
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-UseDefaultCredentials

Usa le credenziali dell'utente corrente per inviare la richiesta Web.

Tipo:	SwitchParameter
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-UserAgent

Specifica una stringa dell'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, utilizzare le proprietà della classe PSUserAgent, ad esempio Chrome, Firefox, InternetExplorer, Opera e Safari.

Tipo:	String
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

-WebSession

Specifica una sessione di richiesta 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 Credenziali. I valori dei parametri hanno la precedenza sui valori nella sessione di richiesta 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 comando Invoke-RestMethod. 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.

Tipo:	WebRequestSession
Posizione:	Named
Valore predefinito:	None
Necessario:	False
Accettare l'input della pipeline:	False
Accettare caratteri jolly:	False

Input

Object

È possibile inviare tramite pipe il corpo di una richiesta Web a questo cmdlet.

Output

Int64

Quando la richiesta restituisce un numero intero, questo cmdlet restituisce l'intero.

String

Quando la richiesta restituisce una stringa, questo cmdlet restituisce tale stringa.

XmlDocument

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

Windows PowerShell include gli alias seguenti per Invoke-RestMethod:

irm

Condividi tramite

Invoke-RestMethod

Sintassi

Descrizione

Esempio

Esempio 1: Ottenere il feed RSS di PowerShell

Esempio 2

Esempio 3: Passare più intestazioni

Esempio 3: Invio dei dati del modulo

Esempio 4: Enumerare gli elementi restituiti nella pipeline

Parametri

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Input

Output

Note

Collegamenti correlati