Invoke-RestMethod

Syntaxe

Default (Par défaut)

Invoke-RestMethod
    [-Method <WebRequestMethod>]
    [-UseBasicParsing]
    [-Uri] <Uri>
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [<CommonParameters>]

Description

Paramètres

-Body

Spécifie le corps de la requête. Le corps est le contenu de la requête qui suit les en-têtes HTTP. Vous pouvez également transmettre une valeur de corps à Invoke-RestMethod.

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

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êtes (tels que POST), le corps est défini comme valeur du corps de la requête au format nom=valeur standard.

Avertissement: La sortie détaillée d’un corps POST se termine par with -1-byte payload, même si la taille du corps est connue et envoyée dans l’en-tête HTTP Content-Length.

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

Par exemple:

$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

Propriétés du paramètre

Jeux de paramètres

-Certificate

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

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

Propriétés du paramètre

Jeux de paramètres

-CertificateThumbprint

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

Les certificats sont utilisés dans l’authentification basée sur les certificats client. Ils ne peuvent être mappés qu’à des comptes d’utilisateur locaux ; ils ne fonctionnent pas avec les comptes de domaine.

Pour obtenir une empreinte numérique de certificat, utilisez la commande Get-Item ou Get-ChildItem dans le lecteur Windows PowerShell (Cert:).

Propriétés du paramètre

Jeux de paramètres

-ContentType

Spécifie le type de contenu de la requête web.

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.

Propriétés du paramètre

Jeux de paramètres

-Credential

Spécifie un compte d’utilisateur autorisé à 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, tel qu’un objet généré par l’applet de commande Get-Credential.

Propriétés du paramètre

Jeux de paramètres

-DisableKeepAlive

Définit la valeur KeepAlive dans l’en-tête HTTP sur Faux. Par défaut, KeepAlive a la valeur True. KeepAlive établit une connexion persistante au serveur pour faciliter les requêtes suivantes.

Propriétés du paramètre

Jeux de paramètres

-Headers

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

Pour définir les en-têtes UserAgent, utilisez le paramètre -UserAgent. Vous ne pouvez pas utiliser ce paramètre pour spécifier les en-têtes UserAgent ou cookie.

Propriétés du paramètre

Jeux de paramètres

-InFile

Obtient le contenu de la requête 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.

Propriétés du paramètre

Jeux de paramètres

-MaximumRedirection

Détermine le nombre de fois où Windows 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.

Propriétés du paramètre

Jeux de paramètres

-Method

Spécifie la méthode utilisée pour la requête web. Les valeurs acceptables pour ce paramètre sont les suivantes :

• Par défaut
• Supprimer
• Obtenir
• Head
• Fusionner
• Paramètres
• Patch
• Publier
• Put
• Trace

Propriétés du paramètre

Jeux de paramètres

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

Par défaut, Invoke-RestMethod retourne les résultats au pipeline. Pour envoyer les résultats à un fichier et au pipeline, utilisez le paramètre -Passthru.

Propriétés du paramètre

Jeux de paramètres

-PassThru

Retourne les résultats, en plus de les écrire dans un fichier. Ce paramètre est valide uniquement lorsque le paramètre -OutFile est également utilisé dans la commande.

Propriétés du paramètre

Jeux de paramètres

-Proxy

Utilise un serveur proxy pour la requête, plutôt que de se connecter directement à la ressource Internet. Entrez l’URI d’un serveur proxy réseau.

Propriétés du paramètre

Jeux de paramètres

-ProxyCredential

Spécifie un compte d’utilisateur autorisé à 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 », ou entrez un objet PSCredential, tel qu’un objet généré par l’applet de commande Get-Credential.

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.

Propriétés du paramètre

Jeux de paramètres

-ProxyUseDefaultCredentials

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.

Propriétés du paramètre

Jeux de paramètres

-SessionVariable

Crée une session de requête web et l’enregistre dans la valeur de la variable spécifiée. Entrez un nom de variable sans 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 Windows PowerShell. Vous pouvez utiliser la variable dans votre session dès que la commande est terminée.

Contrairement à une session distante, 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 requêtes web.

Pour utiliser la session de requête web dans les requêtes web suivantes, spécifiez la variable de session dans la valeur du paramètre -WebSession. Windows 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 requête web, utilisez un paramètre d’applet de commande, tel que -UserAgent ou -Credential. Les valeurs des paramètres sont prioritaires sur les valeurs de la session de requête web.

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

Propriétés du paramètre

Jeux de paramètres

-TimeoutSec

Spécifie la durée pendant laquelle la requête peut être en attente avant qu’elle expire. Entrez une valeur en secondes. La valeur par défaut, 0, spécifie un délai d’attente indéfini.

Une requête DNS (Domain Name System) peut prendre jusqu’à 15 secondes pour retourner ou expirer. 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 moins de 15 secondes, cela peut prendre 15 secondes ou plus avant qu’une exception WebException soit levée, et votre requête expire.

Propriétés du paramètre

Jeux de paramètres

-TransferEncoding

Spécifie une valeur pour l’en-tête de réponse HTTP d’encodage de transfert. Les valeurs acceptables pour ce paramètre sont les suivantes :

• Segmenté
• Compresser
• Dégonfler
• GZip
• Identité

Propriétés du paramètre

Jeux de paramètres

-Uri

Spécifie l’URI (Uniform Resource Identifier) de la ressource Internet à laquelle la requête 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.

Propriétés du paramètre

Jeux de paramètres

-UseBasicParsing

Indique que l’applet de commande utilise l’analyse de base. L’applet de commande retourne le code HTML brut dans un objet String.

Propriétés du paramètre

Jeux de paramètres

-UseDefaultCredentials

Utilise les informations d’identification de l’utilisateur actuel pour envoyer la requête web.

Propriétés du paramètre

Jeux de paramètres

-UserAgent

Spécifie une chaîne d’agent utilisateur pour la requête web.

L’agent utilisateur par défaut est similaire à « Mozilla/5.0 (Windows NT ; Windows NT 6.1 ; en-US) WindowsPowerShell/3.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, telle que Chrome, FireFox, Internet Explorer, Opera et Safari.

Par exemple, la commande suivante utilise la chaîne de l’agent utilisateur pour Internet

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

Propriétés du paramètre

Jeux de paramètres

-WebSession

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

Pour remplacer une valeur dans la session de requête web, utilisez un paramètre d’applet de commande, tel que -UserAgent ou -Credential. Les valeurs des paramètres sont prioritaires sur les valeurs de la session de requête web.

Contrairement à une session distante, 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 requêtes 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 commande Invoke-RestMethod. 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.

Propriétés du paramètre

Jeux de paramètres

CommonParameters

Entrées

Object

Sorties

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

PSObject

Liens associés

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