Partager via

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

Apprenez à utiliser PowerShell avec l’API Web Dataverse dans Visual Studio Code. 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 guide de démarrage rapide vous aide à commencer à utiliser 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 apprenez à :

  • 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 PowerShellInvoke-RestMethod.

Note

Ce guide de démarrage rapide présente uniquement les concepts de base. Cette introduction suffit pour les tests de base. Après avoir effectué les étapes décrites dans cet article, accédez à Utiliser PowerShell et Visual Studio Code avec l’API Web Dataverse pour en savoir plus sur les fonctionnalités plus avancées qui vous rendent plus productif, par exemple :

Les instructions de cet article doivent fonctionner pour Windows, Linux et macOS, mais ces étapes ne sont testées que sur Windows. Si des modifications sont nécessaires, faites-nous savoir à l’aide de la section Commentaires en bas de cet article.

Conditions préalables

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

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

Vérifier l’installation

  1. Ouvrez Visual Studio Code.

  2. Dans le menu Terminal, sélectionnez Nouveau terminal.

  3. Dans le volet de navigation Visual Studio Code, sélectionnez l’icône pour l’extension PowerShell.

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

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

Vous aurez également 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

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

    Vous n’avez pas à enregistrer le fichier.

  2. 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
$secureToken = (Get-AzAccessToken `
   -ResourceUrl $environmentUrl `
   -AsSecureString).Token

# Convert the secure token to a string
$token = ConvertFrom-SecureString `
   -SecureString $secureToken `
   -AsPlainText


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

  3. Modifiez la valeur de la variable $environmentUrl (https://yourorg.crm.dynamics.com/) pour qu’elle corresponde à l’URL Dataverse de votre environnement.

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

  5. 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": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
"UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
"OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}

  6. Dans la fenêtre du terminal, tapez cls pour effacer le contenu du terminal.

  7. 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à authentifié, 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 retourne une erreur. Le script utilise le -ErrorAction SilentlyContinue paramètre pour ignorer l’erreur et ne rien retourner.

Lorsque la Get-AzTenant commande ne retourne rien, le script utilise la commande Connect-AzAccount pour ouvrir une fenêtre de navigateur interactive dans laquelle vous pouvez entrer ou sélectionner vos informations d’identification 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 paramètre pour obtenir une instance PSAccessToken , qui contient une propriété SecureString Token que vous pouvez convertir en jeton d’accès que vous pouvez utiliser pour vous authentifier auprès de Dataverse.

Lorsque vous souhaitez vous connecter à un autre ensemble d’informations d’identification, utilisez la commande Disconnect-AzAccount .

Utiliser Invoke-RestMethod avec la fonction WhoAmI

Après avoir défini le jeton d’accès sur la $token variable, composez la requête sur l’API Web Dataverse et envoyez-la à l’aide de l’applet de commandeInvoke-RestMethod.

Définir les en-têtes

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

# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

Envoyer la demande

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 l’applet de commande Invoke-RestMethod avec les paramètres Uri, Method et Headers pour envoyer cette requête.

# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Pour les opérations qui utilisent POST ou PATCH des méthodes HTTP, définissez le Body paramètre 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 UserId propriété de la réponse, utilisez le script suivant :

# 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 votre clavier dispose de touches de fonction activées en appuyant sur la touche F-Lock, Fn Lock ou Function Lock .

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 le compte qui a accès à l’environnement Dataverse spécifié par le $environmentUrl paramètre.

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. 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 pouvez authentifier et envoyer des demandes d’API Web Dataverse à l’aide de PowerShell, essayez 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

  • Last updated on