Invoke-RestMethod

  • Référence
Module:
Microsoft.PowerShell.Utility

Envoie une demande HTTP ou HTTPS à un service web RESTful.

Syntax

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

Description

L’applet Invoke-RestMethod de commande envoie des requêtes HTTP et HTTPS aux services web REST (Representational State Transfer) qui retournent des données richement structurées.

PowerShell met en forme la réponse en fonction du type de données. Pour un flux RSS ou ATOM, PowerShell retourne les nœuds XML Item ou Entry. Pour javaScript Object Notation (JSON) ou XML, PowerShell convertit ou désérialise le contenu en [PSCustomObject] objets.

Notes

Lorsque le point de terminaison REST retourne plusieurs objets, les objets sont reçus sous forme de tableau. Si vous dirigez la sortie à partir d’une Invoke-RestMethod autre commande, elle est envoyée en tant qu’objet unique [Object[]] . Le contenu de ce tableau n’est pas énuméré pour la commande suivante sur le pipeline.

Cette applet de commande est introduite dans Windows PowerShell 3.0.

À partir de PowerShell 7.0, prend en charge la Invoke-RestMethod configuration du proxy définie par les variables d’environnement. Consultez la section Notes de cet article.

Exemples

Exemple 1 : Obtenir le flux RSS PowerShell

Cet exemple utilise l’applet Invoke-RestMethod de commande pour obtenir des informations à partir du flux RSS du blog PowerShell. La commande utilise l’applet Format-Table de commande pour afficher les valeurs des propriétés Title et pubDate de chaque blog dans une table.

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

Exemple 2 : Exécuter une requête POST

Dans cet exemple, un utilisateur exécute Invoke-RestMethod une requête POST sur un site web intranet de l’organisation de l’utilisateur.

$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

Les informations d’identification sont activées, puis stockées dans $Cred et l’URL qui sera accessible est définie dans $Url.

La $Body variable décrit les critères de recherche, spécifie CSV comme mode de sortie et spécifie une période de temps pour les données retournées qui commence il y a deux jours et se termine il y a un jour. La variable de corps spécifie des valeurs pour les paramètres qui s’appliquent à l’API REST particulière avec laquelle Invoke-RestMethod communique.

La Invoke-RestMethod commande est exécutée avec toutes les variables en place, en spécifiant un chemin d’accès et un nom de fichier pour le fichier de sortie CSV résultant.

Exemple 3 : Suivre les liens relationnels

Certaines API REST prennent en charge la pagination via des liens relationnels selon RFC5988. Au lieu d’analyser l’en-tête pour obtenir l’URL de la page suivante, vous pouvez demander à l’applet de commande de le faire pour vous. Cet exemple retourne les deux premières pages de problèmes à partir du référentiel GitHub PowerShell.

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Exemple 4 : Envoi simplifié de plusieurs parties/de données de formulaire

Certaines API nécessitent multipart/form-data des soumissions pour charger des fichiers et du contenu mixte. Cet exemple montre comment mettre à jour le profil d’un utilisateur.

$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

Le formulaire de profil nécessite les champs suivants : firstName, lastName, email, avatar, birthdayet hobbies. L’API s’attend à ce qu’une image pour la photo de profil utilisateur soit fournie dans le avatar champ. L’API accepte également plusieurs hobbies entrées à soumettre dans le même formulaire.

Lors de la création de $Form HashTable, les noms de clés sont utilisés comme noms de champs de formulaire. Par défaut, les valeurs de HashTable sont converties en chaînes. Si une System.IO.FileInfo valeur est présente, le contenu du fichier est envoyé. Si une collection telle que des tableaux ou des listes est présente, le champ de formulaire est envoyé plusieurs fois.

En utilisant Get-Item sur la avatar clé, l’objet FileInfo est défini comme valeur. Le résultat est que les données d’image pour jdoe.png seront envoyées.

En fournissant une liste à la hobbies clé, le hobbies champ sera présent dans les soumissions une fois pour chaque élément de liste.

Exemple 5 : Passer plusieurs en-têtes

Les API nécessitent souvent des en-têtes passés pour l’authentification ou la validation. Cet exemple montre comment passer plusieurs en-têtes d’un hash-table à une API REST.

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

Exemple 6 : Énumérer les éléments retournés sur le pipeline

GitHub retourne plusieurs objets par tableau. Si vous dirigez la sortie vers une autre commande, elle est envoyée en tant qu’objet unique [Object[]].

Pour énumérer les objets dans le pipeline, dirigez les résultats vers Write-Output ou encapsulez l’applet de commande entre parenthèses. L’exemple suivant compte le nombre d’objets retournés par GitHub. Compte ensuite le nombre d’objets énumérés dans le 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

Exemple 7 : Ignorer la validation de l’en-tête

Par défaut, l’applet Invoke-RestMethod de commande valide les valeurs des en-têtes connus qui ont un format de valeur défini par standardards. L’exemple suivant montre comment cette validation peut déclencher une erreur et comment vous pouvez utiliser le paramètre SkipHeaderValidation pour éviter de valider des valeurs pour les points de terminaison qui tolèrent des valeurs au format non valide.

$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 est un service qui retourne des informations sur les demandes web et les réponses à des fins de résolution des problèmes. La $Uri variable est affectée au /headers point de terminaison du service, qui retourne les en-têtes d’une requête en tant que contenu dans sa réponse.

L’en-tête If-Match de requête est défini dans la section 3.1 de la RFC-7232 et nécessite que la valeur de cet en-tête soit définie avec des guillemets environnants. Une $InvalidHeaders table de hachage est affectée à la variable où la valeur de If-Match n’est pas valide, car elle est définie comme 12345 au lieu de "12345".

L’appel Invoke-RestMethod avec les en-têtes non valides retourne une erreur indiquant que la valeur mise en forme n’est pas valide. La demande n’est pas envoyée au point de terminaison.

L’appel Invoke-RestMethod avec le paramètre SkipHeaderValidation ignore l’échec de validation et envoie la demande au point de terminaison. Étant donné que le point de terminaison tolère des valeurs d’en-tête non conformes, l’applet de commande retourne l’objet de réponse sans erreur.

Exemple 8 : Envoyer une requête à l’aide de HTTP 2.0

Cet exemple interroge le problème GitHub à l’aide du protocole HTTP 2.0.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

Paramètres

-AllowUnencryptedAuthentication

Permet l’envoi d’informations d’identification et de secrets sur des connexions non chiffrées. Par défaut, la fourniture d’informations d’identification ou d’une option d’authentification avec un URI qui ne commence https:// pas par entraînera une erreur et la demande sera abandonnée pour empêcher la communication involontaire de secrets en texte brut sur des connexions non chiffrées. Pour remplacer ce comportement à vos propres risques, fournissez le paramètre AllowUnencryptedAuthentication .

Avertissement

L’utilisation de ce paramètre n’est pas sécurisée et n’est pas recommandée. Il est fourni uniquement pour la compatibilité avec les systèmes hérités qui ne peuvent pas fournir de connexions chiffrées. Utilisez à vos risques et périls.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-Authentication

Spécifie le type d’authentification explicite à utiliser pour la demande. La valeur par défaut est None (Aucun). Le paramètre Authentication ne peut pas être utilisé avec le paramètre UseDefaultCredentials .

Options d’authentification disponibles :

  • None: il s’agit de l’option par défaut lorsque l’authentification n’est pas fournie. Aucune authentification explicite n’est utilisée.
  • Basic: nécessite des informations d’identification. Les informations d’identification seront utilisées pour envoyer un en-tête RFC 7617 Basic Authentication Authorization: Basic au format base64(user:password).
  • Bearer: nécessite le paramètre Token . Envoie un en-tête RFC 6750 Authorization: Bearer avec le jeton fourni.
  • OAuth: nécessite le paramètre Token . Envoie un en-tête RFC 6750 Authorization: Bearer avec le jeton fourni.

La fourniture de l’authentification remplace tous Authorization les en-têtes fournis aux en-têtes ou inclus dans WebSession.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

Type:WebAuthenticationType
Accepted values:None, Basic, Bearer, OAuth
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Body

Spécifie le corps de la demande. Le corps est le contenu de la demande qui suit les en-têtes. Vous pouvez également diriger une valeur de corps vers Invoke-RestMethod.

Le paramètre Body peut être utilisé pour spécifier une liste de paramètres de demande ou le contenu de la réponse.

Lorsque l’entrée est une requête POST et que le corps est une chaîne, la valeur à gauche du premier signe égal (=) est définie en tant que clé dans les données de formulaire et le texte restant est défini comme valeur. Pour spécifier plusieurs clés, utilisez un objet IDictionary, tel qu’une table de hachage, pour body.

Lorsque l’entrée est une requête GET et que le corps est un IDictionary (généralement, une table de hachage), le corps est ajouté à l’URI en tant que paramètres de requête. Pour d’autres types de requête (par exemple, PATCH), le corps est défini comme valeur du corps de la requête au format standard name=value avec les valeurs encodées dans l’URL.

Lorsque l’entrée est une System.Xml. L’objet XmlNode et la déclaration XML spécifient un encodage, qui est utilisé pour les données de la requête, sauf si le paramètre ContentType est remplacé.

Lorsque le corps est un formulaire ou qu’il s’agit de la sortie d’un autre Invoke-WebRequest appel, PowerShell définit le contenu de la demande sur les champs de formulaire.

Le paramètre Body peut également accepter un objet System.Net.Http.MultipartFormDataContent . Cela facilitera les multipart/form-data demandes. Lorsqu’un objet MultipartFormDataContent est fourni pour Body, les en-têtes de contenu fournis aux paramètres ContentType, Headers ou WebSession sont remplacés par les en-têtes de contenu de l’objet MultipartFormDataContent . Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

Type:Object
Position:Named
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

-Certificate

Spécifie le certificat client utilisé pour une demande web sécurisée. Entrez une variable qui contient un certificat, ou bien une commande ou une expression qui obtient le certificat.

Pour rechercher un certificat, utilisez Get-PfxCertificate ou utilisez l’applet de Get-ChildItem commande dans le lecteur Certificat (Cert:). Si le certificat n’est pas valide ou n’a pas suffisamment d’autorité, la commande échoue.

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

-CertificateThumbprint

Spécifie le certificat de clé publique numérique (X509) d'un compte d'utilisateur qui a l'autorisation d'envoyer la demande. Entrez l’empreinte numérique du certificat.

Les certificats sont utilisés dans l'authentification par certificat client. Ils peuvent être mappés uniquement aux comptes d'utilisateur locaux ; ils ne fonctionnent pas avec les comptes de domaine.

Pour obtenir une empreinte de certificat, utilisez la Get-Item commande ou Get-ChildItem dans le lecteur PowerShell Cert: .

Notes

Cette fonctionnalité est actuellement prise en charge uniquement sur les plateformes de système d’exploitation Windows.

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

-ContentType

Spécifie le type de contenu de la demande web.

Si la valeur de ContentType contient le format d’encodage (en tant que charset), l’applet de commande utilise ce format pour encoder le corps de la requête web. Si contentType ne spécifie pas de format d’encodage, le format d’encodage par défaut est utilisé à la place. Un exemple de ContentType avec un format d’encodage est text/plain; charset=iso-8859-5, qui spécifie l’alphabet latin/cyrillique .

Si ce paramètre est omis et que la méthode de requête est POST, Invoke-RestMethod définit le type de contenu sur application/x-www-form-urlencoded. Sinon, le type de contenu n’est pas spécifié dans l’appel.

ContentType est remplacé lorsqu’un MultipartFormDataContent objet est fourni pour Body.

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

-Credential

Spécifie un compte d'utilisateur qui a l'autorisation d'envoyer la demande. La valeur par défaut est l’utilisateur actuel.

Tapez un nom d’utilisateur, tel que User01 ou Domain01\User01, ou entrez un objet PSCredential généré par l’applet de Get-Credential commande.

Les informations d’identification peuvent être utilisées seules ou conjointement avec certaines options de paramètre d’authentification . Lorsqu’il est utilisé seul, il ne fournit des informations d’identification au serveur distant que si le serveur distant envoie une demande de défi d’authentification. Lorsqu’elles sont utilisées avec les options d’authentification , les informations d’identification sont envoyées explicitement.

Les informations d’identification sont stockées dans un objet PSCredential et le mot de passe est stocké en tant que SecureString.

Notes

Pour plus d’informations sur la protection des données SecureString , consultez Comment SecureString est-il sécurisé ?.

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

-CustomMethod

Spécifie la méthode personnalisée utilisée pour la requête web. Cela peut être utilisé avec la méthode request requise par le point de terminaison n’est pas une option disponible sur la méthode. Method et CustomMethod ne peuvent pas être utilisés ensemble.

Exemple :

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

TEST Une requête HTTP est alors envoyée à l’API.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-DisableKeepAlive

Indique que l’applet de commande définit la valeur KeepAlive dans l’en-tête HTTP sur False. Par défaut, KeepAlive a la valeur True. KeepAliveétablit une connexion permanente au serveur pour faciliter les demandes suivantes.

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

-FollowRelLink

Indique que l’applet de commande doit suivre les liens de relation.

Certaines API REST prennent en charge la pagination via des liens relationnels selon RFC5988. Au lieu d’analyser l’en-tête pour obtenir l’URL de la page suivante, vous pouvez demander à l’applet de commande de le faire pour vous. Pour définir le nombre de fois où suivre les liens relationnels, utilisez le paramètre MaximumFollowRelLink .

Lorsque vous utilisez ce commutateur, l’applet de commande retourne une collection de pages de résultats. Chaque page de résultats peut contenir plusieurs éléments de résultats.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

Type:SwitchParameter
Aliases:FL
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Form

Convertit un dictionnaire en soumission multipart/form-data . Le formulaire ne peut pas être utilisé avec Body. Si ContentType est ignoré.

Les clés du dictionnaire seront utilisées comme noms de champ de formulaire. Par défaut, les valeurs de formulaire sont converties en valeurs de chaîne.

Si la valeur est un objet System.IO.FileInfo , le contenu du fichier binaire est envoyé. Le nom du fichier est envoyé en tant que filename. Le MIME est défini sur application/octet-stream. Get-Item peut être utilisé pour simplifier la fourniture de l’objet System.IO.FileInfo .

$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

Si la valeur est un type de collection, tel qu’un tableau ou une liste, le champ for est envoyé plusieurs fois. Les valeurs de la liste seront traitées comme des chaînes par défaut. Si la valeur est un objet System.IO.FileInfo , le contenu du fichier binaire est envoyé. Les collections imbriquées ne sont pas prises en charge.

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

Dans l’exemple ci-dessus, le tags champ est fourni trois fois sous la forme, une fois pour chacun de Vacation, Italyet 2017. Le pictures champ sera également envoyé une fois pour chaque fichier dans le 2017-Italy dossier. Le contenu binaire des fichiers de ce dossier sera envoyé en tant que valeurs.

Cette fonctionnalité a été ajoutée dans PowerShell 6.1.0.

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

-Headers

Spécifie les en-têtes de la demande web. Entrez une table de hachage ou un dictionnaire.

Les en-têtes liés au contenu, tels que Content-Type sont remplacés lorsqu’un MultipartFormDataContent objet est fourni pour Body.

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

-HttpVersion

Spécifie la version HTTP utilisée pour la requête. Par défaut, il s’agit de 1.1.

Les valeurs autorisées sont :

  • 1.0
  • 1.1
  • 2.0
  • 3.0
Type:Version
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-InFile

Obtient le contenu de la demande web à partir d'un fichier.

Entrez un chemin d'accès et un nom de fichier. Si vous omettez le chemin d'accès, la valeur par défaut est l'emplacement actuel.

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

-MaximumFollowRelLink

Spécifie le nombre de fois où suivre les liens relationnels si FollowRelLink est utilisé. Une valeur plus petite peut être nécessaire si l’API REST limite en raison d’un trop grand nombre de demandes. La valeur par défaut est [Int32]::MaxValue. La valeur 0 (zéro) empêche les liens relationnels suivants.

Type:Int32
Aliases:ML
Position:Named
Default value:Int32.MaxValue
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

Spécifie le nombre de fois où PowerShell redirige une connexion vers un autre URI (Uniform Resource Identifier) avant l’échec de la connexion. La valeur par défaut est 5. La valeur 0 (zéro) empêche toute redirection.

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

-MaximumRetryCount

Spécifie le nombre de tentatives de connexion par PowerShell lorsqu’un code d’échec compris entre 400 et 599, inclus ou 304 est reçu. Consultez également paramètre RetryIntervalSec pour spécifier le nombre de nouvelles tentatives.

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

-Method

Spécifie la méthode utilisée pour la demande web. Les valeurs valides pour ce paramètre sont :

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace

Le paramètre CustomMethod peut être utilisé pour les méthodes de requête non répertoriées ci-dessus.

Type:WebRequestMethod
Accepted values:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NoProxy

Indique que l’applet de commande n’utilisera pas de proxy pour atteindre la destination.

Lorsque vous devez contourner le proxy configuré dans Internet Explorer ou un proxy spécifié dans l’environnement, utilisez ce commutateur.

Ce paramètre a été introduit dans PowerShell 6.0.

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

-OutFile

Enregistre le corps de la réponse dans le fichier de sortie spécifié. Entrez un chemin d'accès et un nom de fichier. Si vous omettez le chemin d'accès, la valeur par défaut est l'emplacement actuel. Le nom est traité comme un chemin littéral. Les noms qui contiennent des crochets ([]) doivent être placés entre guillemets simples (').

Par défaut, Invoke-RestMethod retourne les résultats dans le pipeline.

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

-PassThru

Ce paramètre n'est valide que quand le paramètre OutFile est également utilisé dans la commande. L’objectif est d’écrire les résultats dans le fichier et dans le pipeline.

Notes

Lorsque vous utilisez le paramètre PassThru , la sortie est écrite dans le pipeline, mais le fichier n’est pas créé. Pour plus d’informations, consultez Problème PowerShell #15409.

Type:SwitchParameter
Position:Named
Default value:No output
Accept pipeline input:False
Accept wildcard characters:False

-PreserveAuthorizationOnRedirect

Indique que l’applet de commande doit conserver l’en-tête Authorization , le cas échéant, entre les redirections.

Par défaut, l’applet de commande supprime l’en-tête Authorization avant la redirection. La spécification de ce paramètre désactive cette logique pour les cas où l’en-tête doit être envoyé à l’emplacement de redirection.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-Proxy

Utilise un serveur proxy pour la demande, plutôt que de se connecter directement à la ressource Internet. Entrez l’URI (Uniform Resource Identifier) d’un serveur proxy réseau.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-ProxyCredential

Spécifie un compte d'utilisateur qui a l'autorisation d'utiliser le serveur proxy spécifié par le paramètre Proxy. La valeur par défaut est l’utilisateur actuel.

Tapez un nom d’utilisateur, tel que User01 ou Domain01\User01, User@Domain.Comou entrez un PSCredential objet, tel que celui généré par l’applet Get-Credential de commande .

Ce paramètre est valide uniquement lorsque le paramètre Proxy est également utilisé dans la commande . Vous ne pouvez pas utiliser les paramètres ProxyCredential et ProxyUseDefaultCredentials dans la même commande.

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

-ProxyUseDefaultCredentials

Indique que l’applet de commande utilise les informations d’identification de l’utilisateur actuel pour accéder au serveur proxy spécifié par le paramètre Proxy .

Ce paramètre est valide uniquement lorsque le paramètre Proxy est également utilisé dans la commande . Vous ne pouvez pas utiliser les paramètres ProxyCredential et ProxyUseDefaultCredentials dans la même commande.

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

-ResponseHeadersVariable

Crée une variable contenant un dictionnaire d’en-têtes de réponse. Entrez un nom de variable sans le symbole dollar ($). Les clés du dictionnaire contiennent les noms de champs et les valeurs de l’en-tête de réponse retourné par le serveur web.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-Resume

Effectue le meilleur effort pour reprendre le téléchargement d’un fichier partiel. Le paramètre Resume nécessite le paramètre OutFile .

Resume fonctionne uniquement sur la taille du fichier local et du fichier distant et n’effectue aucune autre validation indiquant que le fichier local et le fichier distant sont identiques.

Si la taille du fichier local est inférieure à la taille du fichier distant, l’applet de commande tente de reprendre le téléchargement du fichier et ajoute les octets restants à la fin du fichier.

Si la taille du fichier local est identique à la taille du fichier distant, aucune action n’est effectuée et l’applet de commande suppose que le téléchargement est déjà terminé.

Si la taille du fichier local est supérieure à la taille du fichier distant, le fichier local est remplacé et l’intégralité du fichier distant est entièrement téléchargée. Ce comportement est identique à l’utilisation de OutFile sans Resume.

Si le serveur distant ne prend pas en charge la reprise du téléchargement, le fichier local est remplacé et l’intégralité du fichier distant est entièrement téléchargée. Ce comportement est identique à l’utilisation de OutFile sans Resume.

Si le fichier local n’existe pas, le fichier local est créé et l’intégralité du fichier distant est entièrement téléchargé. Ce comportement est identique à l’utilisation de OutFile sans Resume.

Cette fonctionnalité a été ajoutée dans PowerShell 6.1.0.

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

-RetryIntervalSec

Spécifie l’intervalle entre les nouvelles tentatives de connexion lorsqu’un code d’échec compris entre 400 et 599, inclus ou 304 est reçu. Consultez également le paramètre MaximumRetryCount pour spécifier le nombre de nouvelles tentatives. La valeur doit être comprise entre 1 et [int]::MaxValue.

Type:Int32
Position:Named
Default value:5
Accept pipeline input:False
Accept wildcard characters:False

-SessionVariable

Crée une variable contenant la session de requête web. Entrez un nom de variable sans le symbole dollar ($).

Lorsque vous spécifiez une variable de session, Invoke-RestMethod crée un objet de session de requête web et l’affecte à une variable portant le nom spécifié dans votre session PowerShell. Vous pouvez utiliser la variable dans votre session dès que la commande est terminée.

Avant PowerShell 7.4, la session de requête web n’est pas une connexion persistante. Il s’agit d’un objet qui contient des informations sur la connexion et la demande, notamment les cookies, les informations d’identification, la valeur de redirection maximale et la chaîne de l’agent utilisateur. Vous pouvez l'utiliser pour partager l'état et les données entre les demandes web.

À compter de PowerShell 7.4, la session de requête web est persistante tant que les propriétés de la session ne sont pas remplacées dans une requête suivante. Lorsqu’elles le sont, l’applet de commande recrée la session avec les nouvelles valeurs. Les sessions persistantes réduisent la surcharge liée aux requêtes répétées, ce qui les rend beaucoup plus rapides.

Pour utiliser la session de demande web dans les demandes web suivantes, spécifiez la variable de session dans la valeur du paramètre WebSession. PowerShell utilise les données de l’objet de session de requête web lors de l’établissement de la nouvelle connexion. Pour remplacer une valeur dans la session de demande web, utilisez un paramètre d'applet de commande, comme UserAgent ou Credential. Les valeurs de paramètre sont prioritaires sur les valeurs de la session de demande web.

Vous ne pouvez pas utiliser les paramètres SessionVariable et WebSession dans la même commande.

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

-SkipCertificateCheck

Ignore les vérifications de validation de certificat qui incluent toutes les validations telles que l’expiration, la révocation, l’autorité racine approuvée, etc.

Avertissement

L’utilisation de ce paramètre n’est pas sécurisée et n’est pas recommandée. Ce commutateur est uniquement destiné à être utilisé sur des hôtes connus à l’aide d’un certificat auto-signé à des fins de test. Utilisez à vos propres risques.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-SkipHeaderValidation

Indique que l’applet de commande doit ajouter des en-têtes à la demande sans validation.

Ce commutateur doit être utilisé pour les sites qui nécessitent des valeurs d’en-tête qui ne sont pas conformes aux normes. La spécification de ce commutateur désactive la validation pour autoriser la transmission de la valeur non cochée. Quand il est spécifié, tous les en-têtes sont ajoutés sans validation.

Cela désactive la validation des valeurs passées aux paramètres ContentType, Headers et UserAgent.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0.

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

-SkipHttpErrorCheck

Ce paramètre oblige l’applet de commande à ignorer les états d’erreur HTTP et à continuer à traiter les réponses. Les réponses d’erreur sont écrites dans le pipeline comme si elles réussissaient.

Ce paramètre a été introduit dans PowerShell 7.

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

-SslProtocol

Définit les protocoles SSL/TLS autorisés pour la requête web. Par défaut, tous les protocoles SSL/TLS pris en charge par le système sont autorisés. SslProtocol permet de se limiter à des protocoles spécifiques à des fins de conformité.

Ces valeurs sont définies comme une énumération basée sur un indicateur. Vous pouvez combiner plusieurs valeurs pour définir plusieurs indicateurs à l’aide de ce paramètre. Les valeurs peuvent être passées au paramètre SslProtocol sous la forme d’un tableau de valeurs ou d’une chaîne séparée par des virgules de ces valeurs. L’applet de commande combine les valeurs à l’aide d’une opération binary-OR. La transmission de valeurs en tant que tableau est l’option la plus simple et vous permet également d’utiliser la saisie semi-automatique par tabulation sur les valeurs. Vous ne pourrez peut-être pas fournir plusieurs valeurs sur toutes les plateformes.

Notes

Sur les plateformes non-Windows, il est possible qu’il ne soit pas possible de fournir Tls ou Tls12 en tant qu’option. La prise en charge de Tls13 n’est pas disponible sur tous les systèmes d’exploitation et doit être vérifiée par système d’exploitation.

Cette fonctionnalité a été ajoutée dans PowerShell 6.0.0 et la prise en charge Tls13 a été ajoutée dans PowerShell 7.1.

Type:WebSslProtocol
Accepted values:Default, Tls, Tls11, Tls12, Tls13
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-StatusCodeVariable

Crée une variable contenant un résultat de code d’état HTTP de la requête. Entrez un nom de variable sans le symbole dollar ($).

Le paramètre peut identifier les messages de réussite ou d’échec lorsqu’il est utilisé avec le paramètre SkipHttpErrorCheck .

Entrez le nom de la variable du paramètre sous la forme d’une chaîne telle que -StatusCodeVariable "scv".

Ce paramètre a été introduit dans PowerShell 7.

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

-TimeoutSec

Spécifie la durée pendant laquelle la demande peut être en attente avant son expiration. Entrez une valeur en secondes. La valeur par défaut, 0, spécifie un délai d'attente indéfini.

Le retour ou l’expiration d’une requête DNS (Domain Name System) peut prendre jusqu’à 15 secondes. Si votre requête contient un nom d’hôte qui nécessite une résolution et que vous définissez TimeoutSec sur une valeur supérieure à zéro, mais inférieure à 15 secondes, cela peut prendre 15 secondes ou plus avant qu’une exception WebException soit levée et que votre demande expire.

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

-Token

Jeton OAuth ou porteur à inclure dans la demande. Le jeton est requis par certaines options d’authentification . Il ne peut pas être utilisé indépendamment.

Le jeton prend un SecureString qui contient le jeton. Pour fournir le jeton, utilisez manuellement les éléments suivants :

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Ce paramètre a été introduit dans PowerShell 6.0.

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

-TransferEncoding

Spécifie une valeur pour l'en-tête de réponse HTTP de codage de transfert. Les valeurs valides pour ce paramètre sont :

  • Segmenté
  • Compresser
  • Deflate
  • GZip
  • Identité
Type:String
Accepted values:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Uri

Spécifie l’URI (Uniform Resource Identifier) de la ressource Internet à laquelle la demande web est envoyée. Ce paramètre prend en charge les valeurs HTTP, HTTPS, FTP et FILE.

Ce paramètre est obligatoire. Le nom du paramètre (URI) est facultatif.

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

-UseBasicParsing

Ce paramètre a été déprécié. À compter de PowerShell 6.0.0, toutes les requêtes Web utilisent l’analyse de base uniquement. Ce paramètre est inclus pour la compatibilité descendante uniquement et toute utilisation de celui-ci n’aura aucun effet sur le fonctionnement de l’applet de commande.

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

-UseDefaultCredentials

Indique que l’applet de commande utilise les informations d’identification de l’utilisateur actuel pour envoyer la requête web. Cela ne peut pas être utilisé avec l’authentification ou les informations d’identification et peut ne pas être pris en charge sur toutes les plateformes.

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

-UserAgent

Spécifie une chaîne d'agent utilisateur pour la demande web.

L’agent utilisateur par défaut est similaire à Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 avec de légères variations pour chaque système d’exploitation et plateforme.

Pour tester un site web avec la chaîne d’agent utilisateur standard utilisée par la plupart des navigateurs Internet, utilisez les propriétés de la classe PSUserAgent , telles que Chrome, FireFox, InternetExplorer, Opera et Safari.

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

-WebSession

Spécifie une session de demande web. Entrez le nom de la variable, y compris le signe dollar ($).

Pour remplacer une valeur dans la session de demande web, utilisez un paramètre d'applet de commande, comme UserAgent ou Credential. Les valeurs de paramètre sont prioritaires sur les valeurs de la session de demande web. Les en-têtes liés au contenu, tels que Content-Type, sont également remplacés lorsqu’un objet MultipartFormDataContent est fourni pour Body.

Contrairement à une session à distance, la session de requête web n’est pas une connexion persistante. Il s’agit d’un objet qui contient des informations sur la connexion et la demande, notamment les cookies, les informations d’identification, la valeur de redirection maximale et la chaîne de l’agent utilisateur. Vous pouvez l'utiliser pour partager l'état et les données entre les demandes web.

Pour créer une session de requête web, entrez un nom de variable, sans signe dollar, dans la valeur du paramètre SessionVariable d’une Invoke-RestMethod commande. Invoke-RestMethod crée la session et l’enregistre dans la variable . Dans les commandes suivantes, utilisez la variable comme valeur du paramètre WebSession.

Vous ne pouvez pas utiliser les paramètres SessionVariable et WebSession dans la même commande.

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

Entrées

Object

Vous pouvez diriger le corps d’une requête web vers cette applet de commande.

Sorties

Int64

Lorsque la requête retourne un entier, cette applet de commande retourne cet entier.

String

Lorsque la requête retourne une chaîne, cette applet de commande retourne cette chaîne.

XmlDocument

Lorsque la requête retourne du code XML valide, cette applet de commande le retourne sous la forme d’un XmlDocument.

PSObject

Lorsque la requête retourne des chaînes JSON, cette applet de commande retourne un OBJET PSObject représentant les données.

Notes

PowerShell inclut les alias suivants pour Invoke-RestMethod:

  • Toutes les plateformes :
    • irm

Certaines fonctionnalités peuvent ne pas être disponibles sur toutes les plateformes.

En raison des modifications apportées à .NET Core 3.1, PowerShell 7.0 et versions ultérieures utilisent la propriété HttpClient.DefaultProxy pour déterminer la configuration du proxy.

La valeur de cette propriété est différente en fonction de votre plateforme :

  • Pour Windows : lit la configuration du proxy à partir de variables d’environnement ou, si celles-ci ne sont pas définies, à partir des paramètres de proxy de l’utilisateur.
  • Pour macOS : lit la configuration du proxy à partir de variables d’environnement ou, si celles-ci ne sont pas définies, à partir des paramètres de proxy du système.
  • Pour Linux : lit la configuration du proxy à partir de variables d’environnement ou, si celles-ci ne sont pas définies, cette propriété initialise une instance non configurée qui contourne toutes les adresses.

Les variables d’environnement utilisées pour l’initialisation de DefaultProxy sur les plateformes Windows et Unix sont les suivantes :

  • HTTP_PROXY: nom d’hôte ou adresse IP du serveur proxy utilisé sur les requêtes HTTP.
  • HTTPS_PROXY: nom d’hôte ou adresse IP du serveur proxy utilisé sur les requêtes HTTPS.
  • ALL_PROXY: le nom d’hôte ou l’adresse IP du serveur proxy utilisé sur les requêtes HTTP et HTTPS au cas où HTTP_PROXY ou HTTPS_PROXY ne sont pas définis.
  • NO_PROXY : liste de noms d’hôte séparés par des virgules à exclure comme proxy.