Partager via

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

  • Article

Visual Studio 2022 prend en charge les fichiers .http, qui peuvent être utilisés pour structurer, stocker et envoyer directement des demandes HTTP à partir de l’application. L’utilisation de cette fonctionnalité de Visual Studio est un moyen d’élaborer des demandes HTTP et de les soumettre aux API REST Azure Digital Twins. Cet article explique comment configurer un fichier .http dans Visual Studio qui peut interagir avec les API Azure Digital Twins.

Cet article contient des informations sur les étapes suivantes :

  1. Configurez un projet Visual Studio et un fichier .http avec des variables qui représentent votre instance Azure Digital Twins.
  2. Utilisez l’interface de ligne de commande Azure pour obtenir un jeton du porteur permettant d’envoyer des demandes d’API dans Visual Studio.
  3. Utilisez la documentation de l’API REST Azure Digital Twins en tant que ressource pour créer des demandes dans le fichier .http et envoyez-les 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 jeux d’API, consultez API et kits de développement logiciel (SDK) Azure Digital Twins. Cet article contient des instructions pour les deux jeux d’API.

Pour plus d’informations sur la prise en charge des fichiers .http dans Visual Studio, consultez Utiliser des fichiers .http dans Visual Studio 2022.

Prérequis

Pour utiliser Visual Studio afin de faire des demandes aux API Azure Digital Twins, vous devez configurer une instance Azure Digital Twins et télécharger Visual Studio 2022. Cette section concerne 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écharger Visual Studio 2022

Ensuite, téléchargez Visual Studio 2022. Veillez à inclure la charge de travail ASP.NET et développement web dans votre installation.

Configurer un projet Visual Studio

Dans cette section, vous configurez dans Visual Studio le projet qui sera utilisé pour créer des demandes HTTP.

Ouvrez Visual Studio sur votre ordinateur et créez un projet. Utilisez le modèle de projet ASP.NET Core Empty.

Capture d’écran d’un modèle de projet ASP.NET Core Empty dans Visual Studio.

Suivez les instructions dans Créer un fichier .http pour créer un fichier .http dans votre projet.

Ajouter des variables

Ensuite, ajoutez quelques variables en haut de votre fichier .http qui seront utilisées pour se connecter à votre ressource Azure Digital Twins.

Le jeu de variables dont vous avez besoin dépend du jeu d’API que vous utilisez. Utilisez donc les onglets ci-dessous pour choisir entre les API de plan de données et de plan de contrôle.

Ajoutez les variables suivantes pour les demandes de plan de données. Il y a un espace réservé pour le nom d’hôte de votre instance Azure Digital Twins (se termine par digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

Ajouter un jeton du porteur

Maintenant que vous avez configuré votre instance Azure Digital Twins et votre projet Visual Studio, vous devez obtenir un jeton du porteur que les demandes HTTP 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 de cette façon.

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. D’abord, assurez-vous d’être connecté à Azure avec les bons identifiants 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 transmettez 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 ci-dessous 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 la réponse. Il s’agit de votre valeur de jeton que vous collez dans Visual Studio 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 et sa valeur d’exemple sont mis 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.

Ajouter un jeton au fichier .http

Dans votre fichier .http dans Visual Studio, ajoutez une autre variable qui contient la valeur de votre jeton.

@token=<paste-data-plane-token>

Vos variables doivent désormais ressembler à ce qui suit :

Capture d’écran des variables de plan de données, avec un jeton.

Ajouter des demandes

Maintenant que votre fichier .http est configuré, vous pouvez ajouter des demandes aux API Azure Digital Twins.

Commencez par ouvrir la référence de l’API REST Azure Digital Twins. Cette documentation contient des détails sur toutes les opérations couvertes par les API. Naviguez vers la page de référence de la requête que vous souhaitez exécuter.

Cet article utilise comme exemple l’API DigitalTwins Update du plan de données.

  1. Ajouter un modèle de requête : copiez la requête HTTP affichée dans la documentation de référence.

    Capture d’écran de la requête HTTP dans la documentation de l’API Digital Twins.

    Dans Visual Studio, collez la requête dans une nouvelle ligne sous les variables de votre fichier .http.

  2. Ajouter des paramètres : consultez la section paramètres URI de la documentation de référence pour connaître les valeurs de paramètres dont la requête a besoin. Vous pouvez en remplacer certaines par les variables que vous avez précédemment créées et renseigner les autres valeurs de paramètres comme il se doit. Pour référencer une variable, placez le nom de la variable dans des accolades doubles, par exemple {{variable}}. Pour plus d’informations, consultez Variables.

    Remarque

    Pour les demandes de plan de données, digitaltwins-hostname est également un paramètre. Remplacez cela par {{hostName}} pour utiliser la valeur de votre variable de nom d’hôte.

    Voici à quoi ressemble cette étape dans un exemple de requête :

    Capture d’écran de la requête avec des paramètres dans Visual Studio.

  3. Ajouter une autorisation : ajoutez la ligne suivante (exactement telle qu’écrite) directement en dessous de la requête pour spécifier l’authentification avec votre variable de jeton du porteur.

    Authorization: Bearer {{token}}

    Voici à quoi ressemble cette étape dans un exemple de requête :

    Capture d’écran de la requête avec la ligne d’autorisation dans Visual Studio.

  4. Ajouter des en-têtes supplémentaires : consultez la section En-tête de demande de la documentation de référence pour savoir quelles valeurs d’en-tête peuvent accompagner la demande. Vous pouvez également inclure des en-têtes HTTP traditionnels comme Content-Type. Ajoutez chaque en-tête sur sa propre ligne au format HeaderName: Value. Pour plus d’informations, consultez En-têtes de demandes.

    Voici à quoi ressemble cette étape dans un exemple de requête :

    Capture d’écran de la requête avec un autre en-tête dans Visual Studio.

  5. Ajouter le corps : consultez la section Corps de la demande de la documentation de référence pour savoir quelles informations de corps peuvent être demandées par la requête. Ajoutez le corps de requête après une ligne vide. Pour plus de détails, consultez Corps de la demande.

    Voici à quoi ressemble cette étape dans un exemple de requête : Capture d’écran de la requête avec un corps dans Visual Studio.

  6. Lorsque la requête est prête, sélectionnez Envoyer la requête au-dessus de la requête pour l’envoyer.

    Capture d’écran d’Envoyer une requête dans Visual Studio.

Visual Studio affiche un volet avec les détails de la réponse. Consultez la section Réponses de la documentation de référence pour interpréter le code d’état et toutes les données dans le corps de réponse.

Capture d’écran de la réponse dans Visual Studio.

Ajouter des demandes supplémentaires

Pour ajouter d’autres demandes au fichier .http, séparez-les par ### en tant que délimiteur.

Capture d’écran de plusieurs demandes au sein d’un fichier dans Visual Studio.

Étapes suivantes

Pour plus d’informations sur l’envoi de demandes avec des fichiers .http dans Visual Studio, notamment les détails de syntaxe et les scénarios avancés, consultez Utiliser des fichiers .http dans Visual Studio 2022.

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.