Utiliser Insomnia avec l’API Web Dataverse

Il existe de nombreux outils API clients que vous pouvez utiliser pour vous authentifier dans les environnements Microsoft Dataverse pour composer et envoyer des requêtes de l’API Web. Ces outils facilitent l’apprentissage, le test et l’exécution de requêtes ad hoc à l’aide de l’API Web Dataverse.

Cet article a deux objectifs :

1. Démontrer une stratégie pour s’authentifier et se connecter à Dataverse en utilisant le Client API Insomnia avec un ID d’application Microsoft Entra (client) fourni par Microsoft et préapprouvé pour tous les environnements Dataverse. Cela signifie que vous n’avez pas besoin d’enregistrer une application pour commencer à utiliser l’API Web Dataverse.
2. Vous présenter quelques opérations de données de base que vous pouvez effectuer à l’aide de l’API Web Dataverse dans le contexte du client API Insomnia. De cette façon, vous pouvez utiliser Insomnia pour continuer à expérimenter et à en apprendre davantage sur l’API Web Dataverse.

Confidentialité

Les requêtes que vous envoyez avec les outils API clients contiennent des informations qui peuvent être sensibles. De nombreux développeurs ne souhaitent pas que ces informations soient chargées dans un service cloud.

Le Bloc-notes local Insomnia ne nécessite pas que vous créiez un compte, ni ne stocke d’informations sur les requêtes que vous envoyez. Les instructions fournies ici décrivent comment utiliser uniquement le bloc-notes Insomnia. Vous pouvez choisir de créer un compte et d’utiliser toutes les fonctionnalités d’Insomnia si vous le souhaitez. Si vous souhaitez une version qui ne dispose d’aucune option pour créer un compte et qui est axée sur la confidentialité, consultez Insomnium.

Installer Insomnia

Consultez la documentation d’Insomnia sur les étapes pour installer Insomnia. Les instructions sont différentes pour macOS, Windows et Linux.

Pour Windows, le programme d’installation est un exécutable (exe) que vous téléchargez et exécutez. Une fois l’installation terminée, différentes options peuvent être disponibles. Ces options ne devraient pas interférer avec les instructions de cet article, mais elles peuvent changer. Au moment de la rédaction de cet article, ces options étaient présentées :

• Pour l’option permettant d’activer les fonctionnalités pour synchroniser les données avec le cloud, choisissez Continuer à stocker localement dans le coffre local.

• Pour l’option permettant de créer un compte, choisissez Utiliser le bloc-notes local. En savoir plus sur le bloc-notes Insomnia

  

Configurer l’environnement de base

Utilisez les environnements Insomnia pour stocker des variables d’environnement. Les variables d’environnement sont un objet JSON contenant des paires de données clé-valeur que vous pouvez référencer à de nombreuses fins.

L’environnement de base est attribué à chaque espace de travail et les variables qui y sont contenues sont accessibles dans tout l’espace de travail.

1. Après avoir ouvert Insomnia, sélectionnez l’icône d’engrenage en regard de l’environnement de base pour ouvrir la boîte de dialogue Gérer les environnements. Ou bien, utilisez le raccourci clavier Ctrl + E.

2. Copiez le JSON suivant :

   {
      "url": "https://yourorg.api.crm.dynamics.com",
      "version": "9.2",
      "webapiurl": "{{ _.url }}/api/data/v{{ _.version }}/",
      "redirecturl": "https://localhost",
      "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{ _.url }}",
      "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
   }
   

3. Collez le JSON dans l’environnement de base.

4. Modifiez la valeur de la propriété url et remplacez la valeur https://yourorg.api.crm.dynamics.com pour qu’elle corresponde à l’URL de votre environnement Dataverse.

   Vous trouverez le point de terminaison de l’API Web pour votre environnement en utilisant les instructions dans Afficher les ressources pour les développeurs. Supprimez /api/data/v9.2 de l’URL du point de terminaison de l’API Web. Cette URL doit se terminer par dynamics.com.

   Vous devez vous attendre à ce que les références aux variables _.url et _.version ne soient pas résolues immédiatement ; par conséquent, vous pouvez voir les avertissements suivants :

   

   Cependant, après avoir fermé la fenêtre et l’avoir rouverte, vous pouvez voir que les variables sont maintenant connues et résolues.

   

Créer des sous-environnements (facultatif)

Si vous devez vous connecter à un seul environnement Dataverse, vous pouvez simplement utiliser l’environnement de base. Si vous devez vous connecter à plusieurs environnements, vous pouvez créer des sous-environnements pour chaque environnement Dataverse. Par exemple, vous pouvez créer un sous-environnement pour vos environnements Dataverse de développement et de test.

1. Comme vous l’avait fait avec l’environnement de base, sélectionnez l’icône d’engrenage en regard de l’environnement de base pour ouvrir la boîte de dialogue Gérer les environnements. Ou bien, utilisez le raccourci clavier Ctrl + E.

2. Sélectionnez l’icône pour créer un nouvel environnement. Les environnements peuvent être partagés ou privés. Choisissez Environnement privé.

3. Double-cliquez sur le nom du Nouvel environnement que vous avez créé et renommez-le comme vous le souhaitez. Vous pouvez lui donner le nom de l’environnement Dataverse auquel vous souhaitez vous connecter, ou quelque chose comme Environnement de développement.

4. Copiez le JSON suivant :

   {
      "url": "https://yourdevorg.api.crm.dynamics.com"
   }
   

5. Collez le JSON dans l’environnement que vous avez créé.

6. Modifiez la valeur de la propriété url pour représenter le point de terminaison de l’API Web pour votre autre environnement, comme vous l’avez fait pour l’environnement de base.

   Notes

   Vous devez simplement inclure la propriété url dans le sous-environnement. Lorsque le sous-environnement est sélectionné, cette valeur remplacera la valeur url spécifiée dans l’environnement de base. Vous pouvez également inclure l’une des 5 autres propriétés si vous le souhaitez, mais la valeur de la propriété url est la seule qui soit différente pour chaque environnement Dataverse.

Configurer les requêtes

Après avoir configuré votre environnement de base et tous les sous-environnements, vous êtes prêt à configurer une requête.

1. Sélectionnez le bouton Nouvelle requête HTTP ou utilisez le raccourci clavier Ctrl+N.

2. Après la méthode HTTP, qui est GET par défaut, saisissez _. et attendez un instant. Insomnia affiche une liste de variables disponibles parmi lesquelles choisir :

   

3. Choisissez la variable _.webapiurl. Le champ URL PREVIEW doit afficher la valeur en utilisant la valeur de la propriété url pour votre environnement sélectionné.

4. Dans l’onglet Authentification, utilisez le menu déroulant pour sélectionner le TYPE D’AUTHENTIFICATION OAuth 2.0.

   

5. Modifiez la configuration de l’authentification comme indiqué dans le tableau suivant, en utilisant les variables d’environnement que vous avez créées :

   Champ	Valeur
   TYPE D’AUTORISATION	Implicite
   URL D’AUTORISATION	_.authurl
   ID CLIENT	_.clientid
   URL DE REDIRECTION	_.redirecturl

6. Cliquez sur Envoyer.

   Une boîte de dialogue devrait s’ouvrir pour saisir les informations d’identification de l’environnement.

   Après avoir saisi vos informations d’identification, vous devriez voir des résultats dans le volet Aperçu qui se présentent comme suit :

   {
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata",
   "value": [
      {
         "name": "aadusers",
         "kind": "EntitySet",
         "url": "aadusers"
      },
      {
         "name": "accounts",
         "kind": "EntitySet",
         "url": "accounts"
      },
      {
         "name": "aciviewmappers",
         "kind": "EntitySet",
         "url": "aciviewmappers"
      },
      {
         "name": "actioncards",
         "kind": "EntitySet",
         "url": "actioncards"
      },
      ...
   

   Ce résultat est le document de service de l’API Web. Vous affichez le document de service en envoyant une requête GET à la racine de l’URL du service de l’API Web. Il répertorie les noms des ensembles d’entités pour toutes les tables de votre environnement Dataverse. Lorsque vous pouvez voir le document de service, vous vous êtes authentifié avec succès dans votre environnement Dataverse.

   Conseil

   Il s’agit d’un moyen pratique de rechercher ou de vérifier le nom de l’ensemble d’entités pour une table que vous utilisez.

Afficher le document CSDL $metadata

Le document Common Schema Definition Language (CSDL) $metadata est la source de vérité pour tout ce qui concerne l’API Web. Vous voudrez y faire référence fréquemment.

1. Modifiez l’URL en ajoutant $metadata?annotations=true après la variable _.webapiurl. L’URL doit être :

   GET _.webapiurl $metadata?annotations=true

2. Cliquez sur Envoyer.

Dans le volet Aperçu, vous devriez voir un message indiquant Réponse de plus de 5 Mo masquée pour des raisons de performances, avec les options pour Enregistrer dans un fichier et Afficher quand même. Le fichier est volumineux, mais vous devriez pouvoir le prévisualiser sans problème.

Rechercher des définitions de types

Le document CSDL $metadata est volumineux. La version préliminaire d’Insomnia fournit un outil de filtrage des réponses dans la partie inférieure. Vous pouvez utiliser des requêtes XPath pour filtrer la réponse et trouver ce dont vous avez besoin. Le tableau suivant présente quelques exemples :

En savoir plus sur les types définis dans le document CSDL $metadata

Envoyer une requête WhoAmI

Maintenant que vous êtes authentifié, modifiez votre requête pour appeler la fonction WhoAmI. Comme WhoAmI est une fonction, vous utilisez une méthode GET. Cette fonction n’a pas de paramètres, elle est donc facile à utiliser. En savoir plus sur l’utilisation des fonctions de l’API Web

1. Modifiez l’URL en ajoutant WhoAmI après la variable _.webapiurl. L’URL doit être :

   GET _.webapiurl WhoAmI

2. Définissez les en-têtes de requête.

   Comme décrit dans En-têtes HTTP, chaque requête de l’API Web doit avoir un ensemble spécifique d’en-têtes de requête et vous devrez peut-être modifier les valeurs d’en-tête pour différents comportements.

   Dans l’onglet En-têtes, sélectionnez le bouton Ajouter pour saisir chacun des en-têtes courants suivants :

   En-tête	active
   Accept	application/json
   OData-MaxVersion	4.0
   OData-Version	4.0
   If-None-Match	null
   Prefer	odata.include-annotations="*"

   Ces en-têtes ne changent pas le comportement de la fonction WhoAmI, mais il est recommandé de commencer à les ajouter au début.

3. Cliquez sur Envoyer.

   Dans le volet Aperçu, vous devriez voir les données correspondant au type complexe WhoAmIResponse.

   {
      "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
      "BusinessUnitId": "77164db8-dbc7-ee11-907a-00224803d046",
      "UserId": "e6b56e50-a3d5-ee11-9078-000d3a59a579",
      "OrganizationId": "100462a3-76cb-ee11-9075-00224806e300"
   }
   

Récupérer des données

Pour utiliser Insomnia pour récupérer des enregistrements, vous devez définir le nom de l’ensemble d’entités pour la ressource.

1. Modifiez l’URL pour supprimer WhoAmI après la variable _.webapiurl et remplacez-le par accounts, le nom de l’ensemble d’entités pour le type d’entité de compte. L’URL doit être :

   GET _.webapiurl accounts

2. Dans l’onglet Paramètres, définissez les paramètres de votre requête.

   Vous pouvez ajouter des paramètres individuellement en sélectionnant le bouton Ajouter. Mais vous pouvez également sélectionner l’option Modification en bloc, que vous pouvez trouver plus facile.

   1. Sélectionnez l’option Modification en bloc.
   2. Copiez les paramètres suivants :

   $top: 3
   $select: name,revenue,address1_city
   $expand: primarycontactid($select=fullname)
   $filter: address1_city eq 'Redmond'
   

   Cette requête renvoie les colonnes sélectionnées des trois principaux enregistrements de compte situés dans la ville de Redmond et inclut des informations sur tout contact associé spécifié comme contact principal pour les comptes.

   1. Collez les valeurs dans le champ PARAMÈTRES DE LA REQUÊTE.

      Votre requête devrait ressembler à ceci :

      

3. Cliquez sur Envoyer.

   Dans le volet Aperçu, vous devriez voir des résultats semblables aux suivants :

   {
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city,primarycontactid(fullname))",
   "@Microsoft.Dynamics.CRM.totalrecordcount": -1,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
   "@Microsoft.Dynamics.CRM.globalmetadataversion": "2341840",
   "value": [
      {
         "@odata.etag": "W/\"2343103\"",
         "name": "City Power & Light (sample)",
         "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
         "revenue": 100000.0,
         "address1_city": "Redmond",
         "accountid": "01eaf28f-81e1-ee11-904d-000d3a3517c4",
         "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
         "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
         "address1_composite": "Redmond",
         "primarycontactid": {
         "fullname": "Scott Konersmann (sample)",
         "contactid": "15eaf28f-81e1-ee11-904d-000d3a3517c4"
         }
      },
      {
         "@odata.etag": "W/\"2343104\"",
         "name": "Contoso Pharmaceuticals (sample)",
         "revenue@OData.Community.Display.V1.FormattedValue": "$60,000.00",
         "revenue": 60000.0,
         "address1_city": "Redmond",
         "accountid": "03eaf28f-81e1-ee11-904d-000d3a3517c4",
         "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
         "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
         "address1_composite": "Redmond",
         "primarycontactid": {
         "fullname": "Robert Lyon (sample)",
         "contactid": "17eaf28f-81e1-ee11-904d-000d3a3517c4"
         }
      },
      {
         "@odata.etag": "W/\"2343106\"",
         "name": "A. Datum Corporation (sample)",
         "revenue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
         "revenue": 10000.0,
         "address1_city": "Redmond",
         "accountid": "07eaf28f-81e1-ee11-904d-000d3a3517c4",
         "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
         "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
         "address1_composite": "Redmond",
         "primarycontactid": {
         "fullname": "Rene Valdes (sample)",
         "contactid": "1beaf28f-81e1-ee11-904d-000d3a3517c4"
         }
      }
   ]
   }
   

   Notes

   Ces résultats incluent de nombreuses valeurs d’annotation telles que @OData.Community.Display.V1.FormattedValue, car l’en-tête de requête Prefer: odata.include-annotations="*" défini dans Envoyer une requête WhoAmI est défini pour renvoyer toutes les annotations. Découvrez comment demander des annotations spécifiques

En savoir plus sur la façon d’interroger les données

Créer un enregistrement

Avec Insomnia, vous pouvez définir plusieurs requêtes que vous pouvez réutiliser. Le moyen le plus simple de créer une nouvelle requête qui conserve toutes les configurations dont vous disposez consiste à dupliquer une requête existante. Dans cette étape, nous dupliquons la requête définie dans la section Récupérer les données et créons une nouvelle requête pour créer un enregistrement.

1. La requête que vous avez créée dans Récupérer les données a le nom par défaut Nouvelle requête, à moins que vous l’ayez modifié. Renommez la requête Récupérer les comptes.

2. Lorsque vous pointez le curseur de la souris sur la requête Récupérer les comptes, sélectionnez le menu déroulant et sélectionnez Dupliquer.

   

3. Dans la boîte de dialogue Dupliquer la requête, définissez le Nouveau nom sur Créer un compte.

4. Dans la nouvelle requête Créer un compte, modifiez la méthode HTTP de GET en POST. L’URL est déjà définie pour utiliser le nom de l’ensemble d’entités accounts, vous n’avez donc rien d’autre à modifier ici. L’URL doit être :

   POST _.webapiurl accounts

5. Dans l’onglet Paramètres, vous pouvez supprimer tous les paramètres car ils ne sont pas utilisés pour l’opération de création.

6. Dans l’onglet Corps, utilisez le menu déroulant pour sélectionner JSON dans le groupe TEXTE :

   

7. Copiez le JSON suivant :

   {
      "name": "An Example Account record (sample)",
      "revenue": 10000.0,
      "address1_city": "Redmond"
   }
   

8. Collez le JSON dans le champ Corps.

   Notes

   Avant d’appuyer sur Envoyer pour créer l’enregistrement, examinez les données dans les onglets Authentification et En-têtes. Comme vous avez créé cette requête en dupliquant la requête Récupérer les comptes, toutes les informations que vous avez configurées précédemment sont réutilisées.

9. Appuyez sur Envoyer pour créer l’enregistrement.

   Vous devriez voir que le service a renvoyé 204 Aucun contenu. Il n’y a donc aucun contenu à voir dans le volet Aperçu.

   L’URL de l’enregistrement créé est visible dans la liste En-têtes. Recherchez l’en-tête de réponse odata-entityid. La valeur devrait ressembler à ceci :

   https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)
   

   Cette URL contient la valeur du champ de clé primaire pour l’enregistrement créé, dans ce cas la valeur de la propriété accountid.

En savoir plus sur la création d’enregistrements

Récupérer un enregistrement

Maintenant que vous avez créé un enregistrement de compte et connaissez la valeur du champ de clé primaire, vous pouvez le récupérer en utilisant cette valeur. Commencez par dupliquer la requête Récupérer les comptes.

1. Dupliquez la requête Récupérer les comptes.

2. Nommez-la Récupérer le compte.

3. Modifiez l’URL pour ajouter la valeur accountid entre parenthèses après le nom de l’ensemble d’entités. Si le accountid du compte que vous avez créé dans Créer un enregistrement était 5b4ced1c-88e1-ee11-904c-6045bd05e9d4, modifiez l’URL en :

   GET _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

4. Dans l’onglet Paramètres, supprimez les paramètres $top, $expand et $filter, en ne laissant que le paramètre $select pour limiter le nombre de colonnes renvoyées.

5. Dans l’onglet En-têtes, cochez la case en regard de l’en-tête Prefer pour la désactiver afin qu’aucune annotation ne soit renvoyée.

6. Cliquez sur Envoyer.

   La réponse devrait renvoyer 200 OK et le volet Aperçu devrait contenir des données telles que les suivantes :

   {
      "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city)/$entity",
      "@odata.etag": "W/\"2343128\"",
      "name": "An Example Account record (sample)",
      "revenue": 10000.0000000000,
      "address1_city": "Redmond",
      "accountid": "5b4ced1c-88e1-ee11-904c-6045bd05e9d4",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond"
   }
   

En savoir plus sur la récupération d’enregistrements

Supprimer un enregistrement

Maintenant que vous avez créé et récupéré un enregistrement à l’aide de la valeur de la clé primaire, vous pouvez maintenant le supprimer.

1. Dupliquez la requête Récupérer le compte. Nommez la nouvelle demande Supprimer le compte.

2. Modifiez la méthode HTTP de GET à DELETE.

   L’URL devrait toujours contenir les données avec le accountid de l’enregistrement que vous avez créé et récupéré auparavant :

   DELETE _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

3. Dans l’onglet Paramètres, supprimez le paramètre $select, car il est inutile pour une opération de suppression.

4. Cliquez sur Envoyer.

   Vous devriez voir que le service a renvoyé 204 Aucun contenu. Il n’y a donc aucun contenu à voir dans le volet Aperçu.

5. Essayez d’envoyer la requête Récupérer le compte maintenant, elle renvoie 404 Introuvable et le volet Aperçu affiche cette erreur :

   {
      "error": {
         "code": "0x80040217",
         "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
      }
   }
   

6. Réactivez l’en-tête Prefer de la requête Récupérer le compte afin que toutes les annotations soient renvoyées.

7. Renvoyez la requête et vous pouvez maintenant voir que de nombreuses annotations sont renvoyées avec la réponse 404 Introuvable :

   {
      "error": {
         "code": "0x80040217",
         "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionSourceKey": "Plugin/Microsoft.Crm.Common.ObjectModel.AccountService",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepKey": "81cbbb1b-ea3e-db11-86a7-000a3a5473e8",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiDepthKey": "1",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiActivityIdKey": "ef7da2d8-c3bc-40f3-b67f-9d2981341086",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiPluginSolutionNameKey": "System",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepSolutionNameKey": "System",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionCategory": "ClientError",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionMessageName": "ObjectDoesNotExist",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionHttpStatusCode": "404",
         "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040217&client=platform",
         "@Microsoft.PowerApps.CDS.InnerError.Message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
      }
   }
   

   Ces détails ne sont pas utiles dans ce contexte, car le problème est évident. Mais ces détails pourraient être utiles dans d’autres scénarios. En savoir plus sur l’ajout de détails supplémentaires avec des erreurs

En savoir plus sur la suppression d’enregistrements

Étapes suivantes

En savoir plus sur ce que vous pouvez faire avec l’API Web Dataverse :