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 ricchi di struttura.

Windows PowerShell formatta la risposta in base al tipo di dati. Per un feed RSS o ATOM, Windows PowerShell restituisce i nodi XML Item o Entry. Per JavaScript Object Notation (JSON) o XML, Windows PowerShell converte o deserializza il contenuto in oggetti.

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 per eliminare questa -UseBasicParsing operazione.

Esempio

Esempio 1: Ottenere il feed RSS di PowerShell

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 +0000

Questo comando usa il Invoke-RestMethod cmdlet per ottenere informazioni dal feed RSS di 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 viene eseguito Invoke-RestMethod un utente 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

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

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

In questo esempio viene illustrato come passare più intestazioni da a un'API hash-table REST.

Parametri

-Body

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

Il -Body parametro 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 termina con with -1-byte payload, anche se le dimensioni del corpo sono note e inviate nell'intestazione Content-Length HTTP.

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

Ad esempio:

$R = Invoke-WebRequest $R.Forms https://website.com/login.aspx [0]. Name = "MyName" $R.Forms[0]. Password = "MyPassword" Invoke-RestMethod -Body $R.Forms https://website.com/service.aspx [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 o usare Get-PfxCertificate il cmdlet nell'unità Get-ChildItem Certificato (Cert:). Se il certificato non è valido o non ha autorizzazioni sufficienti, il comando non riesce.

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. Possono essere mappati solo ad account utente locali. Non funzionano con gli account di dominio.

Per ottenere un'identificazione personale del certificato, usare il comando o nell'unità Get-Item Windows PowerShell (Cert:).Get-ChildItem

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 questo parametro viene omesso e il metodo request è 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.

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 , ad esempio uno generato dal Get-Credential cmdlet.

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableKeepAlive

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

Type:	SwitchParameter
Position:	Named
Default value:	KeepAlive
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Headers

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

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

Type:	IDictionary
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

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

Type:	Int32
Position:	Named
Default value:	5
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:

Default
Delete
Recupero
Head
Unione
Opzioni
Patch
Pubblica
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

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 della pipeline. Per inviare i risultati a un file e alla pipeline, usare il -Passthru parametro .

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

Restituisce i risultati e li scrive in un file. Questo parametro è valido solo quando nel comando viene usato anche il parametro -OutFile.

Type:	SwitchParameter
Position:	Named
Default value:	No output
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	Uri
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyCredential

Specifica un account utente che dispone dell'autorizzazione per l'uso del -Proxy server proxy specificato dal parametro . Il valore predefinito è l'utente corrente.

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

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

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyUseDefaultCredentials

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

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionVariable

Crea una sessione di richieste Web e la salva nel valore della variabile specificata. 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 Windows PowerShell. È possibile usare la variabile nella sessione appena il comando termina l'esecuzione.

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 usare la sessione di richiesta Web nelle richieste Web successive, specificare la variabile di sessione nel valore del -WebSession parametro . Windows PowerShell usa i dati nell'oggetto sessione di richieste Web quando 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 -SessionVariable parametri e -WebSession nello stesso comando.

Type:	String
Aliases:	SV
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 meno di 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:	0
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
Comprimi
Deflate
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 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.

Type:	Uri
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UseBasicParsing

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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, usare le proprietà della classe PSUserAgent , ad esempio Chrome, FireFox, Internet Explorer, Opera e Safari.

Ad esempio, il comando seguente usa la stringa agente utente per Internet.

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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.

Per creare una sessione di richiesta Web, immettere un nome di variabile (senza un segno di dollaro) nel valore del -SessionVariable parametro di un Invoke-RestMethod comando. Invoke-RestMethod crea la sessione e la salva nella variabile . Nei comandi successivi usare la variabile come valore del -WebSession parametro .

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

Type:	WebRequestSession
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Input

Object

È possibile inviare il corpo di una richiesta Web a Invoke-RestMethod.

Output

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

L'output del cmdlet dipende dal formato del contenuto recuperato.

PSObject

Se la richiesta restituisce stringhe JSON, Invoke-RestMethod restituisce un PSObject che rappresenta le stringhe.

Condividi tramite

Invoke-RestMethod

Sintassi

Descrizione

Esempio

Esempio 1: Ottenere il feed RSS di PowerShell

Esempio 2

Esempio 3: Passare più intestazioni

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

Risorse aggiuntive

Condividi tramite

Invoke-RestMethod

Sintassi

Descrizione

Esempio

Esempio 1: Ottenere il feed RSS di PowerShell

Esempio 2

Esempio 3: Passare più intestazioni

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

Collegamenti correlati

Risorse aggiuntive