Partage via

Guide pratique pour envoyer des demandes aux API Azure Digital Twins avec Postman

  • Article

Postman est un outil de test REST qui fournit des fonctionnalités clés de requête HTTP dans une interface utilisateur graphique Bureau basée sur un plug-in. Vous pouvez l’utiliser pour créer des requêtes HTTP et envoyer celles-ci aux API REST Azure Digital Twins. Cet article explique comment configurer le client REST Postman pour interagir avec les API Azure Digital Twins. Ces informations sont spécifiques au service Azure Digital Twins.

Cet article contient des informations sur les étapes suivantes :

  1. Utilisez Azure CLI pour obtenir un jeton du porteur permettant d’effectuer des demandes API dans Postman.
  2. Créez une collection Postman et configurez le client REST Postman afin qu’il utilise votre jeton du porteur pour s’authentifier. Lors de la configuration de la collection, vous pouvez choisir l’une des options suivantes :
    1. Importer une collection prédéfinie de demandes d’API Azure Digital Twins.
    2. Créer votre propre collection à partir de rien.
  3. Ajouter des demandes à votre collection configurée et les envoyer aux API Azure Digital Twins.

Azure Digital Twins comprend deux ensembles API que vous pouvez utiliser : un plan de données et un plan de contrôle. Pour plus d’informations sur la différence entre ces ensembles API, consultez API et kits de développement logiciel (SDK) Azure Digital Twins. Cet article contient des informations sur les deux ensembles API.

Prérequis

Pour utiliser Postman pour accéder aux API Azure Digital Twins, vous devez configurer une instance Azure Digital Twins et télécharger Postman. Le reste de cette section vous guidera dans ces étapes.

Configurer l’instance Azure Digital Twins

Pour utiliser Azure Digital Twins dans cet article, vous avez besoin d’une instance Azure Digital Twins et des autorisations requises pour l’utiliser. Si vous disposez déjà d’une instance Azure Digital Twins configurée, vous pouvez utiliser cette instance et passer à la section suivante. Dans le cas contraire, suivez les instructions indiquées dans Configurer une instance et l’authentification. Les instructions contiennent des informations qui vous aideront à vérifier que vous avez correctement effectué chaque étape.

Une fois l’instance configurée, notez son nom d’hôte. Vous trouverez le nom d’hôte dans le portail Azure.

Téléchargez Postman.

Ensuite, téléchargez la version de bureau du client Postman.

Obtenir un jeton du porteur

À présent que vous avez configuré Postman et votre instance Azure Digital Twins, vous devez obtenir un jeton du porteur que les demandes Postman peuvent utiliser pour autoriser les API Azure Digital Twins.

Il existe plusieurs façons d’obtenir ce jeton. Cet article utilise Azure CLI pour vous connecter à votre compte Azure et obtenir un jeton.

Si vous disposez d’une interface de ligne de commande Azure installée localement, vous pouvez démarrer une invite de commandes sur votre ordinateur pour exécuter les commandes suivantes. Dans le cas contraire, vous pouvez ouvrir une fenêtre Azure Cloud Shell dans votre navigateur et y exécuter les commandes.

  1. Tout d’abord, assurez-vous que vous êtes connecté à Azure avec les informations d’identification appropriées, en exécutant la commande suivante :

    az login

  2. Ensuite, utilisez la commande az account get-access-token pour obtenir un jeton du porteur ayant accès au service Azure Digital Twins. Dans cette commande, vous allez transmettre l’ID de ressource pour le point de terminaison de service Azure Digital Twins afin d’obtenir un jeton d’accès permettant d’accéder aux ressources Azure Digital Twins.

    Le contexte requis pour le jeton dépend de l’ensemble d’API que vous utilisez. Utilisez donc les onglets suivants pour sélectionner entre le plan de données et les API du plan de contrôle.

    Pour obtenir un jeton à utiliser avec les API du plan de données, utilisez la valeur statique suivante pour le contexte de jeton : 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Cette valeur constitue l’ID de ressource du point de terminaison de service Azure Digital Twins.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Remarque

    Si vous devez accéder à votre instance Azure Digital Twins à l’aide d’un principal de service ou d’un compte d’utilisateur appartenant à un autre locataire Microsoft Entra de l’instance, vous devez demander un jeton à partir du locataire « home » de l’instance Azure Digital Twins. Pour plus d’informations sur ce processus, consultez Écrire le cade d’authentification de l’application.

  3. Copiez la valeur de accessToken dans le résultat, puis enregistrez-la pour l’utiliser dans la section suivante. Il s’agit de la valeur de jeton que vous allez fournir à Postman pour autoriser vos demandes.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

Conseil

Ce jeton est valide pendant au minimum cinq minutes et au maximum 60 minutes. Si le temps alloué ne suffit pas pour le jeton actuel, vous pouvez répéter les étapes décrites dans cette section pour en obtenir un nouveau.

Ensuite, vous allez configurer Postman afin d’utiliser ce jeton pour envoyer des demandes API à Azure Digital Twins.

À propos des collections Postman

Les demandes dans Postman sont enregistrées dans des collections (groupes de demandes). Lorsque vous créez une collection pour regrouper vos demandes, vous pouvez appliquer des paramètres communs à de nombreuses demandes à la fois. Les paramètres courants peuvent simplifier considérablement l’autorisation si vous envisagez de créer plusieurs requêtes sur les API Azure Digital Twins, car vous n’avez à configurer ces détails qu’une seule fois pour l’ensemble du regroupement.

Quand utilisez Azure Digital Twins, vous pouvez commencer par importer une collection prédéfinie de toutes les demandes Azure Digital Twins. Vous pouvez importer cette collection si vous explorez les API et souhaitez configurer rapidement un projet avec des exemples de requête.

Vous pouvez également choisir de commencer à partir de rien en créant votre propre collection vide, puis en la remplissant de demandes individuelles qui appellent uniquement les API dont vous avez besoin.

Les sections suivantes décrivent les deux processus. Le reste de l’article ayant trait à votre application Postman locale, vous devez ouvrir l’application sur votre ordinateur maintenant.

Importer une collection d’API Azure Digital Twins

Un moyen rapide de bien démarrer avec Azure Digital Twins dans Postman consiste à importer une collection prédéfinie de requêtes pour les API. Suivez les étapes ci-dessous pour importer une collection de demandes d’API de plan de données Azure Digital Twins populaires contenant des exemples de données de requête.

  1. Dans la fenêtre principale de Postman, sélectionnez le bouton Importer. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. Dans la fenêtre Importer qui suit, sélectionnez Lien et entrez l’URL suivante : https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Sélectionnez Ensuite Importer pour confirmer.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

La collection importée est visible dans l’affichage principal de Postman, sous l’onglet Collections.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Conseil

Pour importer l’ensemble complet d’appels d’API pour une certaine version des API Azure Digital Twins (y compris le plan de contrôle ou le plan de données), vous pouvez également importer des fichiers Swagger en tant que collections. Pour obtenir des liens vers les fichiers Swagger pour les API de plan de contrôle et de plan de données, consultez les API et sdk Azure Digital Twins.

Ensuite, passez à la section suivante pour ajouter un jeton du porteur à la collection pour l’autorisation, et le connecter à votre instance Azure Digital Twins.

Configurer une autorisation

Ensuite, modifiez la collection que vous avez créée afin de configurer des détails d’accès. Mettez en surbrillance la collection que vous avez créée et sélectionnez l’icône Afficher plus d’actions pour afficher les options d’action. Sélectionnez Modifier.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Procédez comme suit pour ajouter un jeton du porteur à la collection pour l’autorisation. Utilisez la valeur de jeton que vous avez recueillie dans la section Récupération du jeton du porteur pour toutes les demandes API de votre collection.

  1. Dans la boîte de dialogue d’édition de votre collection, vérifiez que vous êtes sous l’onglet Autorisation .

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Définissez le type sur OAuth 2.0 et collez votre jeton d’accès dans la zone Jeton d’accès. Vous devez utiliser le jeton correct pour le type d’API que vous utilisez, car il existe différents jetons pour les API de plan de données et les API du plan de contrôle. Cliquez sur Enregistrer.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Conseil

    Vous pouvez choisir d’activer le partage de jetons si vous souhaitez stocker le jeton avec la demande sur le cloud Postman, et éventuellement partager votre jeton avec d’autres personnes.

Autre configuration

Vous pouvez aider la collection à se connecter facilement à vos ressources Azure Digital Twins en définissant certaines variables fournies avec la collection. Lorsque de nombreuses demandes d’une collection requièrent la même valeur (comme le nom d’hôte de votre instance Azure Digital Twins), vous pouvez stocker la valeur dans une variable s’appliquant à chaque demande de la collection. La collection Azure Digital Twins est fournie avec des variables précréées que vous pouvez définir au niveau de la collection.

  1. Toujours dans la boîte de dialogue de modification de votre collection, accédez à l’onglet Variables .

  2. Utilisez le tableau suivant pour définir les valeurs des variables dans la collection :

    Variable Ensemble d’API Description
    digitaltwins-hostname Plan de données Le nom d’hôte de l’instance Azure Digital Twins. Vous trouverez cette valeur sur la page vue d’ensemble de votre instance dans le portail.
    subscriptionId Plan de contrôle Votre ID d’abonnement Azure.
    digitalTwinInstance Plan de contrôle Nom de votre instance Azure Digital Twins.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. Si votre collection comprend des variables supplémentaires, remplissez-les et enregistrez-les également.

  4. Cliquez sur Enregistrer.

Une fois les étapes ci-dessus accomplies, vous avez fini de configurer la collection. Vous pouvez fermer l’onglet de modification de la collection si vous le souhaitez.

Explorer les demandes

Ensuite, explorez les demandes à l’intérieur de la collection d’API Azure Digital Twins. Vous pouvez développer la collection pour afficher les demandes prêtes à l’emploi (triées par catégorie d’opération).

Les différentes demandes requièrent des informations différentes sur votre instance et ses données. Pour afficher toutes les informations requises pour élaborer une demande particulière, recherchez les détails de la demande dans la documentation de référence sur l’API REST Azure Digital Twins.

Vous pouvez modifier les détails d’une demande dans la collection Postman en procédant comme suit :

  1. Sélectionnez-la dans la liste pour extraire ses détails modifiables.

  2. La plupart des requêtes de l’exemple de collection sont préconfigurées pour s’exécuter sans apporter de modifications supplémentaires.

  3. La capture d’écran suivante montre l’API Add DigitalTwinModels . Sous l’onglet Corps , vous pouvez voir la charge utile JSON qui définit le nouveau modèle à ajouter :

  4. Entrez les valeurs des variables répertoriées sous l’onglet Paramètres, sous Variables de chemin d’accès.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Pour exécuter la requête, utilisez le bouton Envoyer .

Vous pouvez également ajouter vos propres demandes à la collection à l’aide du processus décrit dans la section Ajouter une demande individuelle.

Créer votre propre collection

Au lieu d’importer la collection existante d’API Azure Digital Twins, vous pouvez également créer votre propre collection à partir de zéro. Vous pouvez ensuite la remplir de demandes individuelles en procédan de la manière décrite dans la documentation de référence sur l’API REST Azure Digital Twins.

Créer une collection Postman

  1. Pour créer une collection, sélectionnez le bouton Nouveau dans la fenêtre principale de Postman.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Choisissez un type de Collection.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Un onglet s’ouvre. Renseignez les informations relatives à la nouvelle collection. Sélectionnez l’icône Modifier en regard du nom par défaut de la collection (Nouvelle collection) pour le remplacer par le nom de votre choix.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

Ensuite, passez à la section suivante pour ajouter un jeton du porteur à la collection à des fins d’autorisation.

Configurer une autorisation

Procédez comme suit pour ajouter un jeton du porteur à la collection pour l’autorisation. Utilisez la valeur de jeton que vous avez recueillie dans la section Récupération du jeton du porteur pour toutes les demandes API de votre collection.

  1. Toujours dans la boîte de dialogue de modification de votre nouvelle collection, accédez à l’onglet Autorisation .

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Définissez le Type sur OAuth 2.0, collez votre jeton d’accès dans la zone Jeton d’accès, puis sélectionnez Enregistrer.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

Une fois les étapes ci-dessus accomplies, vous avez fini de configurer la collection. Vous pouvez fermer l’onglet de modification pour la nouvelle collection si vous le souhaitez.

La collection est visible dans l’affichage principal de Postman, sous l’onglet Collections.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Ajouter une demande individuelle.

À présent que votre collection est configurée, vous pouvez ajouter vos propres demandes aux API Azure Digital Twins.

  1. Pour créer une demande, appuyez utiliser le bouton Nouveau.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Choisissez un type de Demande.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. Cette action ouvre la fenêtre ENREGISTRER LA DEMANDE dans laquelle vous pouvez entrer un nom et une description facultative pour votre demande, ainsi que choisir la collection à laquelle elle appartient. Entrez les détails et enregistrez la demande dans la collection que vous avez créée précédemment.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

Vous pouvez maintenant afficher votre demande dans la collection, et la sélectionner pour extraire ses détails modifiables.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Définir les détails d’une demande

Pour envoyer une demande Postman à l’une des API Azure Digital Twins, vous avez besoin de l’URL de l’API et d’informations sur les détails requis. Vous trouverez ces informations dans la documentation de référence sur l’API REST Azure Digital Twins.

Pour suivre un exemple de requête, cet article utilise l’API requête Azure Digital Twins pour rechercher tous les jumeaux numériques dans une instance.

  1. Trouvez l’URL et le type de la demande dans la documentation de référence. Pour l’API de requête, il s’agit actuellement de POSThttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. Dans Postman, définissez le type de la demande, puis entrez son URL en remplissant les espaces réservés dans l’URL de manière appropriée. Utilisez le nom d’hôte de votre instance, issu de la section Prérequis.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Vérifiez que les paramètres indiqués pour la demande sous l’onglet Params correspondent à ceux décrits dans la documentation de référence. Pour cette demande dans Postman, le paramètre api-version a été automatiquement renseigné lors de l’entrée de l’URL de la demande à l’étape précédente. Pour l’API de requête, comme il s’agit du seul paramètre requis, cette étape est accomplie.

  4. Dans l’onglet Autorisation , définissez le type sur Hériter de l’authentification du parent. Cela indique que cette demande utilisera l’autorisation que vous avez configurée précédemment pour la collection entière.

  5. Vérifiez que les en-têtes affichés pour la demande sous l’onglet En-têtes correspondent à ceux décrits dans la documentation de référence. Pour cette demande, plusieurs en-têtes ont été remplis automatiquement. Pour l’API de requête, aucune des options d’en-tête n’étant requise, cette étape est accomplie.

  6. Vérifiez que le corps affiché pour la demande sous l’onglet Corps correspond à celui décrit dans la documentation de référence. Pour l’API de requête, un corps JSON est requis pour fournir le texte de la requête. Voici un exemple de corps associé à cette demande qui recherche tous les jumeaux numériques de l’instance :

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Pour plus d’informations sur la création de requêtes Azure Digital Twins, consultez Interroger le graphique de jumeaux.

  7. Consultez la documentation de référence pour connaître les autres champs susceptibles d’être requis pour votre type de demande. Pour l’API de requête, toutes les exigences ayant été satisfaites dans la demande Postman, cette étape est accomplie.

  8. Utilisez le bouton Envoyer pour envoyer votre demande terminée. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

Après l’envoi de la demande, les détails de la réponse s’affichent dans la fenêtre Postman sous la demande. Vous pouvez afficher le code d’état de la réponse et tout texte de corps.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

Vous pouvez également comparer la réponse aux données de réponse attendues dans la documentation de référence pour vérifier le résultat ou en savoir plus sur les erreurs qui se produisent.

Étapes suivantes

Pour en savoir plus sur les API Digital Twins, lisezAPI et kits de développement logiciel (SDK) Azure Digital Twins ou afficher la documentation de référence pour les API REST.