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

Nota

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

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

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 a hash-table un'API REST.

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

Le API spesso richiedono intestazioni passate per l'autenticazione, la convalida e così via.

Esempio 3: Invio dei dati del modulo

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

Ad 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 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
30

Parametri

-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 GET e il corpo è un oggetto 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 è impostato come valore del corpo della richiesta nel formato nome=valore.

Avviso

L'output dettagliato di un corpo POST terminerà con with -1-byte payload, anche se le dimensioni del corpo sono note e inviate nell'intestazione Content-Length HTTP.

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 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 ha autorizzazioni sufficienti, il comando non riesce.

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

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

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

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 è True. KeepAlive stabilisce una connessione permanente al server per facilitare le richieste successive.

Tipo:	SwitchParameter
Posizione:	Named
Valore predefinito:	KeepAlive
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, usare il parametro UserAgent . Non è possibile usare questo parametro per specificare le 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 della richiesta Web da un file.

Immettere un percorso e un nome file. Se si omette il percorso, l'impostazione predefinita è il percorso corrente.

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

-MaximumRedirection

Determina il numero di reindirizzamenti di una connessione a un URI (Uniform Resource Identifier) alternativo in Windows PowerShell prima che la connessione non riesca. Il valore predefinito è 5. Il valore 0 (zero) impedisce qualsiasi reindirizzamento.

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

-Method

Specifica il metodo usato per la richiesta Web. I valori validi 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, l'impostazione predefinita è 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 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 è vuoto. Per altre informazioni, vedere Problema di PowerShell n. 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 invece di 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" o immettere un oggetto PSCredential , 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.

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 appena il comando termina l'esecuzione.

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

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 con codifica di trasferimento. I valori validi 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 alla quale viene inviata la richiesta Web. Questo parametro supporta i 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 agente utente per la richiesta Web.

La stringa agente utente predefinita è simile a "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0", con piccole differenze relative ai singoli sistemi operativi e piattaforme.

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, Internet Explorer, 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 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.

A differenza di una sessione remota, la sessione di richieste Web non è una connessione permanente. Si tratta di un oggetto che contiene le informazioni sulla connessione e sulla richiesta, inclusi cookie, credenziali, il valore massimo di reindirizzamento e la stringa 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 utilizzare 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

Risorse aggiuntive

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

Risorse aggiuntive