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 avez le choix entre les 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. Dans le cadre de cet article, vous allez utiliser l’interface de ligne de commande Azure 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 API que vous utilisez. Utilisez donc les onglets suivants pour choisir entre les API de plan de données et de plan de contrôle.

    Pour obtenir un jeton à utiliser avec les API de plan de données, utilisez la valeur statique suivante comme contexte du 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 avez besoin d’accéder à votre instance Azure Digital Twins à l’aide d’un principal de service ou d’un compte d’utilisateur qui appartient à un autre locataire Microsoft Entra de l’instance, vous devez demander un jeton au locataire « d’accueil » 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.

    Capture d’écran de la console montrant le résultat de la commande az account get-access-token. Le champ accessToken avec sa valeur d’exemple mise en surbrillance.

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 considérablement simplifier l’autorisation si vous envisagez de créer plusieurs demandes d’API Azure Digital Twins, car vous ne devez configurer ces détails qu’une seule fois pour l’ensemble de la collection.

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 prendre en main Azure Digital Twins dans Postman consiste à importer une collection prédéfinie de demandes 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. Capture d’écran d’une fenêtre de Postman venant de s’ouvrir, avec le bouton « Importer » en évidence

  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.

    Capture d’écran de la fenêtre « Importer » de Postman, montrant le fichier à importer en tant que collection et le bouton Importer.

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

Capture d’écran de la fenêtre principale de Postman, avec la collection que vous venez de créer est mise en évidence sous l’onglet « Collections ».

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 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, puis sélectionnez l’icône Afficher d’autres actions pour afficher les options d’action. Sélectionnez Modifier.

Capture d’écran de Postman. L’icône « Afficher d’autres actions » pour la collection importée est mise en évidence, ainsi que l’option « Modifier ».

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 .

    Capture d’écran de la boîte de dialogue de modification de la collection importée dans Postman, montrant l’onglet « Autorisation ».

  2. Définissez le Type sur OAuth 2.0, puis collez votre jeton d’accès dans la zone Jeton d’accès. Vous devez utiliser le bon jeton 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 de plan de contrôle. Cliquez sur Enregistrer.

    Capture d’écran de la boîte de dialogue de modification de Postman pour la collection importée, sous l’onglet « Autorisation ». Le type est « OAuth 2.0 » et la zone Jeton d’accès est mise en évidence.

    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 pouvez trouvez cette valeur sur la page de présentation de votre instance dans le portail.
    subscriptionId Plan de contrôle Votre ID d’abonnement Azure.
    digitalTwinInstance Plan de contrôle Le nom de votre instance Azure Digital Twins.

    Capture d’écran de la boîte de dialogue de modification de la collection importée dans Postman, montrant l’onglet « Variables », avec le champ « CURRENT VALUE » (Valeur actuelle) mis en évidence.

  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 avoir à apporter de modifications supplémentaires.

  3. La capture d’écran suivante montre l’API Ajouter 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.

    Capture d’écran de Postman. La collection est développée pour afficher l’onglet Corps d’une requête.

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

Vous pouvez également ajouter vos propres demandes à la collection, en procédant de la manière décrite dans la section Ajouter une demande individuelle.

Créer votre propre collection

Au lieu d’importer la collection existante des API Azure Digital Twins, vous pouvez créer votre propre collection à partir de rien. 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.

    Capture d’écran de la fenêtre principale de Postman, avec le bouton « Nouveau » mis en évidence.

    Choisissez un type de Collection.

    Capture d’écran de la boîte de dialogue « Créer » dans Postman, avec l’option « Collection » mise en évidence.

  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.

    Capture d’écran de la boîte de dialogue de modification de la nouvelle collection dans Postman, avec l’icône Modifier en regard du nom de la « Nouvelle collection » mise en évidence.

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 .

    Capture d’écran de la boîte de dialogue de modification de la nouvelle collection dans Postman, montrant l’onglet « Autorisation ».

  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.

    Capture d’écran de la boîte de dialogue de modification de Postman pour la nouvelle collection, sous l’onglet « Autorisation ». Le type est « OAuth 2.0 » et la zone Jeton d’accès est mise en évidence.

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.

Capture d’écran de la fenêtre principale de Postman, avec la collection personnalisée nouvellement créée en évidence sous l’onglet « Collections ».

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.

    Capture d’écran de la fenêtre principale de Postman, avec le bouton « Nouveau » mis en évidence.

    Choisissez un type de Demande.

    Capture d’écran de la boîte de dialogue « Créer » dans Postman, avec l’option « Demande » mise en évidence.

  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.

Capture d’écran de la fenêtre « Enregistrer la demande » dans Postman, montrant les champs décrits et le bouton « Enregistrer dans la collection Azure Digital Twins » mis en évidence.

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

Capture d’écran de Postman, avec la collection Azure Digital Twins développée pour afficher les détails de la demande.

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 continuer avec un exemple de requête, cet article utilise l’API de 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 POST https://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.

    Capture d’écran des détails de la nouvelle demande dans Postman, avec l’URL de requête de la documentation de référence renseignée dans la zone URL de demande.

  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. Sous l’onglet Autorisation, définissez le Type sur Hériter 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 :

    Capture d’écran des détails de la nouvelle demande dans Postman, sous l’onglet Corps. Celui-ci contient un corps JSON brut avec une requête « 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. Capture d’écran de Postman montrant les détails de la nouvelle demande, avec le bouton Envoyer mis en évidence.

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.

Capture d’écran de la demande envoyée dans Postman. Sous les détails de la demande, la réponse est affichée. L’État est 200 OK et le corps contient les résultats de la requête.

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.