Démarrage rapide : API web avec PowerShell et Visual Studio Code

Article
02/01/2024

PowerShell est un langage de script puissant capable d’automatiser les tâches répétitives et de rationaliser les flux de travail, ce qui en fait un outil idéal pour l’intégration avec Dataverse. Ce démarrage rapide vise à vous aider à prendre en main PowerShell avec l’API web Dataverse dans Visual Studio Code. Visual Studio Code avec PowerShell offre une alternative à l’utilisation des clients API tels que Postman ou Insomnia.

Dans ce guide de démarrage rapide, vous allez découvrir comment :

Utilisez Visual Studio Code avec PowerShell pour vous authentifier de manière interactive avec Dataverse sans enregistrer d’application.
Composez des requêtes à l’API web Dataverse à l’aide de l’applet de commande PowerShell Invoke-RestMethod.

Notes

Cet article de démarrage rapide présente uniquement les concepts de base. Cela devrait suffire pour les tests de base. Après avoir suivi les étapes de cet article, accédez à Utiliser PowerShell et Visual Studio Code avec l’API web Dataverse pour en savoir plus sur les fonctionnalités avancées qui vous rendront plus productif, telles que :

Les instructions de cet article devraient fonctionner pour Windows, Linux et macOS, mais ces étapes n’ont été testées que sous Windows. Si des modifications sont nécessaires, veuillez nous en informer en utilisant la section Commentaires au bas de cet article.

Conditions préalables

Ne continuez pas sans confirmer que chacune des conditions préalables suivantes est remplie.

Installer ou vérifier que les éléments suivants sont installés

Installez Visual Studio Code. Voir Télécharger Visual Studio Code
Installez l’extension PowerShell pour Visual Studio Code. Voir PowerShell pour Visual Studio Code
Installez PowerShell 7.4 ou version ultérieure. Voir Installer PowerShell sur Windows, Linux et macOS
Installez le module Az PowerShell version 11.1.0 ou supérieure. Voir Procédure d’installation d’Azure PowerShell

Pour mettre à jour une installation existante vers la plus récente, utilisez Update-Module -Name Az -Force

Vérifier l’installation

Ouvrez Visual Studio Code.
Dans le menu Terminal, sélectionnez Nouveau terminal.
Dans le volet de navigation Visual Studio Code, sélectionnez l’icône pour l’extension PowerShell.

Copiez et collez le script suivant dans la fenêtre du terminal Visual Studio Code :

Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString()
Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version

Appuyez sur Entrée. La sortie ressemblerait à l’exemple suivant :
```
PowerShell Version: 7.4.0
PowerShell Az version: 11.1.0
```

Si vous ne voyez pas de résultats comme celui-ci, installez ou mettez à jour les prérequis.

Ce dont vous avez besoin

Compte d’utilisateur valide pour un environnement Dataverse
URL vers l’environnement Dataverse auquel vous souhaitez vous connecter. Voir Afficher les ressources des développeurs pour savoir comment les trouver. Cela ressemble à ceci : https://yourorg.crm.dynamics.com/, où yourorg.crm est différent.
Présentation de base du langage de script PowerShell

Essayez-le

Dans Visual Studio Code, sélectionnez Fichier > Nouveau fichier texte, ou Ctrl+N pour ouvrir un nouveau fichier.

Vous n’avez pas à enregistrer le fichier.

Copiez et collez le script suivant dans le nouveau fichier.

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## Login if not already logged in
if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
   Connect-AzAccount | Out-Null
}
# Get an access token
$token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token
# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}
# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Visual Studio Code devrait automatiquement détecter qu’il s’agit d’un script PowerShell.

Modifiez la valeur de la variable $environmentUrl (https://yourorg.crm.dynamics.com/) pour qu’elle corresponde à l’URL Dataverse de votre environnement.
Appuyez sur F5, ou utilisez la commande de menu Visual Studio Code Exécuter > Démarrer le débogage.

Une fenêtre de navigateur s’ouvre. Dans la fenêtre du navigateur, saisissez ou sélectionnez les informations d’identification que vous souhaitez utiliser pour vous authentifier.

Vérifiez le résultat dans la fenêtre du terminal Visual Studio Code.

En bas du terminal, recherchez la valeur Type complexe WhoAmIResponse attendue pour la fonction WhoAmI. La syntaxe devrait être similaire à ceci :

{
"@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId": "639dea3c-505c-4c3a-b8b5-d916cb507e1e",
"UserId": "d2159662-498a-406b-83cd-f515b7e561d6",
"OrganizationId": "83e197ed-ede1-4886-81f2-f41fe9395297"
}

Dans la fenêtre du terminal, tapez cls pour effacer le contenu du terminal.
Appuyez sur F5, ou utilisez la commande de menu Visual Studio Code Exécuter > Démarrer le débogage pour exécuter à nouveau le script.

Comme vous êtes déjà connecté, la fenêtre du navigateur ne s’ouvre pas. Vous pouvez continuer à modifier et exécuter votre script pour essayer différentes requêtes.

Fonctionnement

Cette section décrit les détails du script PowerShell inclus dans la Section Essayer.

Authentification

Le script utilise la commande Get-AzTenant du module PowerShell Az pour obtenir les locataires autorisés pour l’utilisateur actuel. Lorsque vous n’êtes pas connecté, cette commande renvoie une erreur. Ce script utilise le paramètre -ErrorAction SilentlyContinue pour ignorer l’erreur et rien n’est renvoyé.

Lorsque la commande Get-AzTenant ne renvoie rien, le script utilise la commande Connect-AzAccount pour ouvrir une fenêtre de navigateur interactive dans laquelle vous pouvez saisir ou sélectionner votre identifiants pour vous connecter. Apprenez-en davantage sur la connexion à Azure PowerShell de manière interactive ou non interactive avec un principal de service.

Enfin, le script utilise la commande Get-AzAccessToken avec le -ResourceUrl $environmentUrl pour obtenir une instance PSAccessToken, qui contient une propriété de chaîne Jeton qui est un jeton que vous pouvez utiliser pour vous authentifier avec Dataverse.

Lorsque vous souhaitez vous connecter avec un ensemble d’informations d’identification différent, vous devez utiliser la commande Disconnect-AzAccount.

S’authentifier à l’aide de différents environnements shell

Azure PowerShell fonctionne avec les environnements de shell Windows PowerShell et PowerShell, mais pas avec les environnements de shell Cmd et Bash. Si vous souhaitez vous authentifier auprès des environnements shell Cmd ou Bash, vous pouvez utiliser Azure CLI.

Ce script utilise les commandes Azure CLI pour s’authentifier :

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## <a name="login-if-not-already-logged-in"></a>Login if not already logged in
if ($null -eq (az account tenant list  --only-show-errors)) {
   az login --allow-no-subscriptions | Out-Null
}
# <a name="get-token"></a>Get token
$token = az account get-access-token --resource=$environmentUrl --query accessToken --output tsv

Ce tableau montre les commandes Az PowerShell et Azure CLI équivalentes :

Az PowerShell	Azure CLI	Description
Get-AzTenant	liste des locataires du compte az	Essayez de récupérer une liste de locataires pour détecter si vous êtes déjà connecté
Connect-AzAccount	connexion az	Pour vous connecter à Azure
Get-AzAccessToken	az account get-access-token	Pour obtenir un jeton d’accès
Disconnect-AzAccount	déconnexion az	Se déconnecter d’Azure

Utiliser `Invoke-RestMethod` avec la fonction WhoAmI

Une fois que vous avez défini un jeton sur la variable $token, vous devez composer la requête vers l’API web Dataverse API et l’envoyer à l’aide de l’applet de commande Invoke-RestMethod.

Définir les en-têtes

Toutes les requêtes de l’API web Dataverse doivent inclure un ensemble d’en-têtes de requête HTTP courants, notamment un en-tête Authorization qui inclut la valeur du jeton d’accès. Certaines opérations nécessitent plus d’en-têtes. En savoir plus sur les en-têtes de demande de l’API web Dataverse

# <a name="common-headers"></a>Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

Envoyer la requête

La fonction WhoAmI est l’une des opérations les plus simples Dataverse que vous puissiez effectuer. Puisqu’il s’agit d’une fonction OData plutôt que d’une action, elle nécessite la méthode HTTP GET. En savoir plus sur les fonctions d’API web

Utilisez les paramètres de commande Invoke-RestMethod Uri, Method et Headers pour envoyer cette requête.

# <a name="invoke-whoami-function"></a>Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Pour les opérations qui utilisent des méthodes HTTP POST ou PATCH, définissez l’utilisation du paramètre Body pour envoyer la charge utile JSON.

L’applet de commande ConvertTo-Json convertit l’objet renvoyé en une chaîne au format JSON facile à voir dans le terminal.

Si vous souhaitez capturer uniquement la propriété UserId de la réponse, vous pouvez utiliser le script suivant :

# <a name="get-userid"></a>Get UserId
$userId = (
   Invoke-RestMethod `
   -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') `
   -Method 'Get' `
   -Headers $baseHeaders
   ).UserId
Write-Host $userId

Résolution des problèmes

Assurez-vous de vérifier que tous les programmes requis sont installés comme décrit dans Vérifier l’installation.

Les situations suivantes peuvent entraîner l’échec des instructions de ce démarrage rapide :

Rien ne se passe lorsque j’appuie sur `F5`

Assurez-vous que vos touches de fonction sont activées sur votre clavier en appuyant sur la touche F-Lock, Fn Lock ou Verrouillage des fonctions de votre clavier.

Vous pouvez également utiliser la commande de menu Visual Studio Code Exécuter > Démarrer le débogage .

Aucun tel hôte n’est connu

Si vous voyez cette erreur après avoir exécuté le script :

Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   | No such host is known.

Vérifiez que l’URL $environmentUrl représente un environnement auquel vous avez accès. Assurez-vous que vous l’avez modifié par rapport à la valeur par défaut (https://yourorg.crm.dynamics.com/).

L’utilisateur n’est pas membre de l’organisation

Si vous voyez cette erreur après avoir exécuté le script :

Invoke-RestMethod: untitled:Untitled-1:14:1                                                                             
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   |  {   "error": {     "code": "0x80072560",     "message": "The user is not a member of the organization."   } }

Assurez-vous que le compte que vous sélectionnez dans la fenêtre du navigateur est celui qui a accès à l’environnement Dataverse spécifié par le paramètre $environmentUrl.

Si vous utilisez un ensemble d’informations d’identification différent de celui utilisé auparavant, utilisez la commande Disconnect-AzAccount dans la fenêtre du terminal.

AVERTISSEMENT : TenantId ’<votre identifiant de locataire>’ contient plusieurs abonnements actifs

Lorsque vous exécutez le script pour la première fois et que vous vous connectez à l’aide du navigateur, vous pouvez recevoir cet avertissement :

WARNING: TenantId '<your tenant id>' contains more than one active subscription. First one will be selected for further use. 
To select another subscription, use Set-AzContext. 
To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`. 
Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.

Vous pouvez ignorer cet avertissement si vous le voyez. Ces demandes ne nécessitent pas d’abonnement.

Étapes suivantes

Découvrez des fonctionnalités plus avancées pour être plus productif en utilisant PowerShell et Visual Studio Code avec l’API web Dataverse, par exemple comment :

Utiliser PowerShell et Visual Studio Code avec l’API web Dataverse

Maintenant que vous avez la possibilité d’authentifier et d’envoyer des requêtes d’API web Dataverse à l’aide de PowerShell, vous pouvez essayer d’autres opérations d’API web.

En savoir plus sur les fonctionnalités de l’API web Dataverse en comprenant les documents de service.

Types d’API web et opérations