Invoke-RestMethod

Modulo:

Microsoft.PowerShell.Utility Module

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

Sintassi

StandardMethod (impostazione predefinita).

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-Method <WebRequestMethod>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

StandardMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-Method <WebRequestMethod>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethod

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<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 sono consentiti nei dati JSON.

Annotazioni

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.

A partire da PowerShell 7.0, Invoke-RestMethod supporta la configurazione proxy definita dalle variabili di ambiente. Consultare la sezione NOTE di questo articolo.

A partire da PowerShell 7.4, la codifica dei caratteri per le richieste per impostazione predefinita è UTF-8 anziché ASCII. Se è necessaria una codifica diversa, è necessario impostare l'attributo charset nell'intestazione Content-Type.

Esempio

Esempio 1: Ottenere il feed RSS di PowerShell

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

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

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

Il cmdlet richiede le credenziali e le archivia in $Cred. $Url contiene l'URL dell'endpoint REST.

La variabile $Body 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 comando Invoke-RestMethod viene eseguito con tutte le variabili sul posto, specificando un percorso e un nome file per il file di output CSV risultante.

Esempio 3: Seguire i collegamenti relazionali

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 2

Esempio 4: Invio semplificato di più parti/Form-Data

Alcune API richiedono invii di multipart/form-data per caricare file e i 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 $Form

Il modulo del profilo richiede i campi seguenti: firstName, lastName, email, avatar, birthdaye hobbies. L'API prevede l'inserimento di un'immagine per l'immagine del profilo utente nel campo avatar. L'API accetta anche più elementi hobbies da inviare nello stesso modulo.

Quando si crea l'$Form HashTable, i nomi delle chiavi vengono usati come nomi di campo modulo. Per impostazione predefinita, i valori di HashTable vengono convertiti in stringhe. Se è presente un valore System.IO.FileInfo, il contenuto del file viene inviato. Se è presente una raccolta, ad esempio una matrice o un elenco, il campo modulo viene inviato più volte.

Utilizzando Get-Item sulla chiave di avatar, l'oggetto FileInfo viene impostato come valore. Il risultato è che vengono inviati i dati dell'immagine per jdoe.png.

Fornendo un elenco alla chiave hobbies, il campo hobbies è 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 diverse intestazioni da un hash-table a una REST API.

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

Esempio 6: 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

Esempio 7: Saltando la convalida dell'intestazione

Per impostazione predefinita, il cmdlet Invoke-RestMethod convalida i valori delle intestazioni note con un formato di valore definito dagli standard. 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 variabile $Uri viene assegnata all'endpoint /headers del servizio, che restituisce le intestazioni di una richiesta come contenuto nella risposta.

L'intestazione della richiesta If-Match è definita nella sezione RFC-7232 3.1 e richiede che il valore per tale intestazione venga definito con virgolette circostanti. Alla variabile $InvalidHeaders viene assegnata una tabella hash in cui il valore di If-Match non è valido perché è definito come 12345 anziché "12345".

La chiamata al Invoke-RestMethod con le intestazioni non valide restituisce un errore che segnala che il valore formattato non è valido. La richiesta non viene inviata all'endpoint.

La chiamata a 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 -SkipCertificateCheck

Esempio 9: Inviare una richiesta a un'applicazione socket Unix

Alcune applicazioni, ad esempio Docker, espongono un socket Unix per la comunicazione. Questo esempio esegue una query per un elenco di immagini Docker usando l'API Docker. Il cmdlet si connette al daemon Docker usando il socket Unix.

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

Parametri

-AllowInsecureRedirect

Consente il reindirizzamento da HTTPS a HTTP. Per impostazione predefinita, qualsiasi richiesta reindirizzata da HTTPS a HTTP genera un errore e la richiesta viene interrotta per impedire la comunicazione involontaria in testo normale su connessioni non crittografate. Per eseguire l'override di questo comportamento a proprio rischio, usare il parametro AllowInsecureRedirect.

Questo parametro è stato aggiunto in PowerShell 7.4.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-AllowUnencryptedAuthentication

Consente l'invio di credenziali e segreti su connessioni non crittografate. Per impostazione predefinita, specificare credenziali o qualsiasi opzione di autenticazione con un URI che non inizia con https:// genera un errore e la richiesta viene interrotta per evitare di comunicare involontariamente segreti in testo normale su connessioni non crittografate. Per ignorare questo comportamento a proprio rischio, specificare il parametro AllowUnencryptedAuthentication.

Avvertimento

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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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 fornita l'autenticazione . Non viene usata alcuna autenticazione esplicita.
• Basic: richiede la credenziale . Le credenziali vengono usate per inviare un'intestazione di autenticazione di base RFC 7617 Authorization: Basic nel formato di base64(user:password).
• Bearer: richiede il parametro token di. Invia un'intestazione RFC 6750 Authorization: Bearer con il token fornito.
• OAuth: richiede il parametro token di. Invia un'intestazione RFC 6750 Authorization: Bearer con il token fornito.

L'inserimento di autenticazione esegue l'override di qualsiasi intestazione Authorization fornita alle intestazioni di o inclusa in WebSession.

Questa funzionalità è stata aggiunta in PowerShell 6.0.0.

Proprietà dei parametri

Tipo:	WebAuthenticationType
Valore predefinito:	None
Valori accettati:	None, Basic, Bearer, OAuth
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-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 Body può essere usato per specificare un elenco di parametri di query o specificare il contenuto della richiesta. Per i parametri di query, il cmdlet usa il metodo System.Net.WebUtility.UrlEncode per codificare le coppie chiave-valore. Per altre informazioni sulle stringhe di codifica per gli URL, vedere riferimento al metodo UrlEncode().

Quando l'input è una richiesta POST e il corpo è un 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, utilizzare un oggetto IDictionary, ad esempio una tabella hash, per l'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 chiamata Invoke-WebRequest, PowerShell imposta il contenuto della richiesta sui campi del modulo.

Il parametro body può accettare anche un oggetto System.Net.Http.MultipartFormDataContent, che facilita le richieste di multipart/form-data. Quando viene fornito un oggetto MultipartFormDataContent per il parametro Body, tutte le intestazioni correlate al contenuto fornite ai parametri ContentType, Headerso WebSession vengono sostituite dalle intestazioni di contenuto dell'oggetto MultipartFormDataContent. Questa funzionalità è stata aggiunta in PowerShell 6.0.0.

Proprietà dei parametri

Tipo:	Object
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	True
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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, utilizzare Get-PfxCertificate oppure 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.

Proprietà dei parametri

Tipo:	X509Certificate
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Annotazioni

Questa funzionalità è attualmente supportata solo nelle piattaforme del sistema operativo Windows.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-ConnectionTimeoutSeconds

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 ConnectionTimeoutSeconds su un valore maggiore di zero, ma inferiore a 15 secondi, possono essere necessari 15 secondi o più prima che venga generata una WebException e il timeout della richiesta.

Questo parametro ha sostituito il parametro TimeoutSec in PowerShell 7.4. È possibile usare TimeoutSec come alias per ConnectionTimeoutSeconds.

Proprietà dei parametri

Tipo:	Int32
Valore predefinito:	0
Supporta i caratteri jolly:	False
DontShow:	False
Alias:	TimeoutSec

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

ContentType viene sottoposto a override quando il Body è un oggetto MultipartFormDataContent.

A partire da PowerShell 7.4, se si usa questo parametro e il parametro Headers per definire l'intestazione Content-Type, viene usato il valore specificato nel parametro ContentType.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

È possibile usare le credenziali da sole o insieme a certe opzioni di parametro d'autenticazione . Se usato da solo, fornisce le credenziali al server remoto solo se il server remoto invia una richiesta di verifica di autenticazione. Se usato con le opzioni di autenticazione , la credenziale viene inviata in modo esplicito.

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

Annotazioni

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

Proprietà dei parametri

Tipo:	PSCredential
Valore predefinito:	Current user
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-CustomMethod

Specifica il metodo personalizzato utilizzato per la richiesta Web. Questa opzione può essere utilizzata quando il metodo di richiesta richiesto dall'endpoint non è un'opzione disponibile nel metodo . Il metodo e il metodo personalizzato non possono essere usati insieme.

Esempio:

Invoke-RestMethod -Uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

In questo modo viene eseguita una richiesta HTTP TEST all'API.

Questa funzionalità è stata aggiunta in PowerShell 6.0.0.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False
Alias:	cm

Set di parametri

CustomMethod

Posizione:	Named
Obbligatorio:	True
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

CustomMethodNoProxy

Posizione:	Named
Obbligatorio:	True
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False
Alias:	FL

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-Form

Converte un dizionario in una sottomissione multipart/form-data. Modulo non può essere utilizzato con Corpo. Il ContentType viene ignorato.

Le chiavi del dizionario vengono utilizzate come nomi di campo del modulo. Per impostazione predefinita, i valori del modulo vengono convertiti in valori stringa.

Se il valore è un oggetto System.IO.FileInfo, viene inviato il contenuto del file binario. Il nome del file viene inviato come filename. Il tipo MIME viene impostato come 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 modulo viene inviato più volte. I valori dell'elenco vengono considerati come stringhe per impostazione predefinita. Se il valore è un oggetto System.IO.FileInfo, il contenuto del file binario viene inviato. Le raccolte annidate non sono supportate.

$Form = @{
    tags     = 'Vacation', 'Italy', '2017'
    pictures = Get-ChildItem 'C:\Users\jdoe\Pictures\2017-Italy\'
}

Nell'esempio precedente il campo tags viene fornito tre volte nel modulo, una volta per ognuno dei valori: Vacation, Italye 2017. Il campo pictures viene inviato una volta per ogni file nella cartella 2017-Italy. Il contenuto binario dei file in tale cartella viene inviato come valori.

Questa funzionalità è stata aggiunta in PowerShell 6.1.0.

Proprietà dei parametri

Tipo:	IDictionary
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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 oggetto MultipartFormDataContent per Body.

A partire da PowerShell 7.4, se si utilizza questo parametro per definire l'intestazione Content-Type e il parametro ContentType, viene usato il valore specificato nel parametro ContentType.

Proprietà dei parametri

Tipo:	IDictionary
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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

Proprietà dei parametri

Tipo:	Version
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-MaximumFollowRelLink

Specifica il numero di volte in cui seguire i collegamenti di relazione se viene utilizzato FollowRelLink. Potrebbe essere necessario un valore inferiore se l'API REST si attiva a causa di troppe richieste. Il valore predefinito è [int32]::MaxValue. Il valore 0 (zero) impedisce i collegamenti di relazione seguenti.

Proprietà dei parametri

Tipo:	Int32
Valore predefinito:	Int32.MaxValue
Supporta i caratteri jolly:	False
DontShow:	False
Alias:	ML

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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 tutto il reindirizzamento.

Proprietà dei parametri

Tipo:	Int32
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-MaximumRetryCount

Specifica quante volte PowerShell ritenta una connessione quando viene ricevuto un codice di errore compreso tra 400 e 599 inclusi o 304. Si veda anche il parametro RetryIntervalSec per specificare l'intervallo tra i tentativi.

Proprietà dei parametri

Tipo:	Int32
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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

Il parametro CustomMethod può essere usato per i metodi di richiesta non elencati in precedenza.

Proprietà dei parametri

Tipo:	WebRequestMethod
Valore predefinito:	None
Valori accettati:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

StandardMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

StandardMethodNoProxy

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-NoProxy

Indica che il cmdlet non userà un proxy per raggiungere la destinazione. Usare questa opzione per ignorare il proxy configurato nelle impostazioni Internet o specificato nell'ambiente.

Questo parametro è stato introdotto in PowerShell 6.0.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

StandardMethodNoProxy

Posizione:	Named
Obbligatorio:	True
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

CustomMethodNoProxy

Posizione:	Named
Obbligatorio:	True
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-OperationTimeoutSeconds

Questo timeout si applica ai dati letti all'interno di un flusso, non al tempo di flusso nel suo complesso. Il valore predefinito, 0, specifica un timeout indefinito.

L'impostazione del valore su 30 secondi indica che qualsiasi ritardo di più di 30 secondi tra i dati nel flusso termina la richiesta. Un file di grandi dimensioni che richiede diversi minuti per il download non terminerà a meno che il flusso non si blocchi per più di 30 secondi.

Proprietà dei parametri

Tipo:	Int32
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-OutFile

Per impostazione predefinita, Invoke-RestMethod restituisce i risultati alla pipeline. Quando si usa il parametro OutFile, i risultati vengono salvati nel file specificato e non restituiti alla pipeline. Immettere un percorso e un nome file. Per inviare i risultati a un file e alla pipeline, aggiungere il parametro PassThru.

Se si omette il percorso, il valore predefinito è il percorso corrente. Il nome viene trattato come un percorso letterale. I nomi contenenti parentesi quadre ([]) devono essere racchiusi tra virgolette singole (').

A partire da PowerShell 7.4, è possibile specificare un percorso di cartella senza il nome file. Quando si esegue questa operazione, il comando usa il nome del file dall'ultimo segmento dell'URI risolto dopo eventuali reindirizzamenti. Quando si specifica un percorso di cartella per OutFile, non è possibile usare il parametro Resume.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	No output
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-PreserveAuthorizationOnRedirect

Indica che il cmdlet deve mantenere l'intestazione Authorization, se presente, tra reindirizzamenti.

Per impostazione predefinita, il cmdlet rimuove l'intestazione Authorization prima del 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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-PreserveHttpMethodOnRedirect

Indica che il cmdlet deve mantenere il metodo della richiesta tra reindirizzamenti.

Per impostazione predefinita, il cmdlet modifica il metodo in GET quando viene reindirizzato. Se si specifica questo parametro, questa logica viene disabilitata per assicurarsi che il metodo previsto possa essere usato con il reindirizzamento.

Questa funzionalità è stata aggiunta in PowerShell 7.4.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	Uri
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

StandardMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

CustomMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	PSCredential
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

StandardMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

CustomMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-ProxyUseDefaultCredentials

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

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

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

StandardMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

CustomMethod

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-ResponseHeadersVariable

Crea una variabile contenente un dizionario di 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.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False
Alias:	RHV

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-Resume

Esegue un tentativo con il massimo impegno per continuare 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 tenta 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 viene sovrascritto e l'intero file remoto viene scaricato nuovamente. Questo comportamento equivale all'uso di OutFile senza Resume.

Se il server remoto non supporta la ripresa del download, il file locale viene sovrascritto e l'intero file remoto viene scaricato nuovamente. Questo comportamento equivale all'uso di OutFile senza Resume.

Se il file locale non esiste, viene creato il file locale e viene scaricato l'intero file remoto. Questo comportamento equivale all'uso di OutFile senza Resume.

Questa funzionalità è stata aggiunta in PowerShell 6.1.0.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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. Quando il codice di errore è 429 e la risposta include la proprietà Retry-After nelle relative intestazioni, il cmdlet usa tale valore per l'intervallo di ripetizione dei tentativi, anche se questo parametro è specificato.

Vedere anche il parametro MaximumRetryCount per specificare il numero di tentativi.

Proprietà dei parametri

Tipo:	Int32
Valore predefinito:	5
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

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 le condizioni sono soddisfatte, 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 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.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False
Alias:	SV

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-SkipCertificateCheck

Ignora i controlli di convalida dei certificati che includono tutte le convalide, ad esempio scadenza, revoca, autorità radice attendibile e così via.

Avvertimento

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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-SkipHeaderValidation

Indica che il cmdlet deve aggiungere intestazioni alla richiesta senza alcuna convalida.

Questa opzione deve essere usata per i siti che richiedono valori di intestazione non conformi agli standard. Specificando questa opzione, la convalida viene disabilitata per consentire il passaggio del valore non controllato. Quando specificato, tutte le intestazioni vengono aggiunte senza convalida.

Questa opzione disabilita la convalida dei valori passati ai parametri ContentType, Headerse UserAgent.

Questa funzionalità è stata aggiunta in PowerShell 6.0.0.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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 un'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 array è l'opzione più semplice e consente anche di usare il completamento automatico con il tasto tab sui valori. Potrebbe non essere possibile specificare più valori in tutte le piattaforme.

Questa funzionalità è stata aggiunta in PowerShell 6.0.0. Il supporto per Tls13 è stato aggiunto in PowerShell 7.1.

Proprietà dei parametri

Tipo:	WebSslProtocol
Valore predefinito:	None
Valori accettati:	Default, Tls, Tls11, Tls12, Tls13
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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, ad esempio -StatusCodeVariable "scv".

Questo parametro è stato introdotto in PowerShell 7.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-Token

Il token OAuth o Bearer da includere nella richiesta. Token è richiesto da alcune opzioni di Autenticazione. Non può essere usato in modo indipendente.

Token accetta un SecureString 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.

Proprietà dei parametri

Tipo:	SecureString
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-TransferEncoding

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

• Suddiviso a blocchi
• Comprimere
• Sgonfiare
• GZip
• Identità

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Valori accettati:	chunked, compress, deflate, gzip, identity
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-UnixSocket

Specifica il nome del socket Unix a cui connettersi. Questo parametro è supportato nei sistemi basati su Unix e Windows versione 1803 e successive. Per ulteriori informazioni sul supporto di Windows per i socket Unix, vedere l'articolo del blog Interoperabilità Windows/WSL con AF_UNIX.

Questo parametro è stato aggiunto in PowerShell 7.4.

Proprietà dei parametri

Tipo:	UnixDomainSocketEndPoint
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	Uri
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	0
Obbligatorio:	True
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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. Se usato, non ha alcun effetto sull'operazione del cmdlet.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

-UseDefaultCredentials

Indica che il cmdlet usa le credenziali dell'utente corrente per inviare la richiesta Web. Non può essere usato con Authentication o Credential e potrebbe non essere supportato in tutte le piattaforme.

Proprietà dei parametri

Tipo:	SwitchParameter
Valore predefinito:	False
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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.

Proprietà dei parametri

Tipo:	String
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	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. Le intestazioni correlate al contenuto, come Content-Type, vengono sovrascritte 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 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.

Proprietà dei parametri

Tipo:	WebRequestSession
Valore predefinito:	None
Supporta i caratteri jolly:	False
DontShow:	False

Set di parametri

(All)

Posizione:	Named
Obbligatorio:	False
Valore dalla pipeline:	False
Valore dalla pipeline in base al nome della proprietà:	False
Valore dagli argomenti rimanenti:	False

CommonParameters

Questo cmdlet supporta i parametri comuni: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Per altre informazioni, vedi about_CommonParameters.

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

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à varia a seconda della piattaforma:

• Per Windows: legge la configurazione del proxy dalle variabili di ambiente o, se non 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 utilizzate per l'inizializzazione di DefaultProxy sulle 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 caso in cui HTTP_PROXY o HTTPS_PROXY non siano definiti.
• NO_PROXY: elenco delimitato da virgole di nomi host che devono essere esclusi dal proxy.

PowerShell 7.4 ha aggiunto il supporto per l'algoritmo di compressione Brotli.

Collegamenti correlati

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest