Tutoriel : Créer un graphe Azure Digital Twins à l’aide d’un exemple d’application cliente

  • Article

Dans ce tutoriel, vous allez créer un graphe dans Azure Digital Twins à l’aide de modèles, de jumeaux et de relations. L’outil utilisé pour ce tutoriel est un exemple d’application cliente en ligne de commande pour interagir avec une instance Azure Digital Twins. L’application cliente est semblable à celle écrite dans Coder une application cliente.

Vous pouvez utiliser cet exemple pour effectuer des actions Azure Digital Twins essentielles, telles que le chargement de modèles, la création et la modification de jumeaux et la création de relations. Vous pouvez également consulter le code de l’exemple pour en savoir plus sur les API Azure Digital Twins, et vous exercer à implémenter vos propres commandes en modifiant l’exemple de projet comme bon vous semble.

Ce tutoriel présente les procédures suivantes :

  • Modéliser un environnement
  • Créer des jumeaux numériques
  • Ajouter des relations pour former un graphe
  • Interroger le graphe pour répondre aux questions

Prérequis

Avant de commencer ce tutoriel, configurez ces prérequis :

  • Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
  • Ce tutoriel utilise .NET. Vous pouvez télécharger la dernière version du SDK .NET pour plusieurs plateformes à partir de Télécharger .NET.

Ensuite, lisez le reste de cette section pour configurer les prérequis restants.

Obtenir des exemples de ressource

Ce tutoriel est piloté par un exemple de projet de bout en bout Azure Digital Twins écrit en C#. Pour obtenir l’exemple de projet sur votre machine, suivez le lien vers l’exemple, puis sélectionnez le bouton Parcourir le code sous le titre.

Vous accédez alors au dépôt GitHub d’exemples, que vous pouvez télécharger sous forme de fichier .zip en sélectionnant le bouton Code, puis Télécharger le ZIP.

Screenshot of the digital-twins-samples repo on GitHub, highlighting the steps to download it as a zip.

Cela entraîne le téléchargement d’un fichier nommé digital-twins-samples-main.zip sur votre machine. Décompressez le dossier et extrayez les fichiers.

Préparer une 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.

Configurer l’exemple de projet

Ensuite, configurez un exemple d’application cliente qui interagit avec votre instance Azure Digital Twins.

Sur votre ordinateur, accédez au dossier que vous avez téléchargé précédemment à partir des Exemples Azure Digital Twins de bout en bout (et décompressez-le si vous ne l’avez pas déjà fait).

Une fois dans le dossier, accédez au fichier digital-twins-samples-main\AdtSampleApp\SampleClientApp et ouvrez le fichier appsettings.json. Ce fichier JSON contient une variable de configuration nécessaire pour exécuter le projet.

Dans le corps du fichier, remplacez instanceUrl par l’URL de nom d’hôte de votre instance Azure Digital Twins (en ajoutant https:// devant le nom d’hôte, comme indiqué ci-dessous).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Enregistrez et fermez le fichier.

Configurer les informations d’identification Azure locales

Cet exemple utilise DefaultAzureCredential (qui fait partie de la bibliothèque Azure.Identity) pour authentifier les utilisateurs auprès de l’instance Azure Digital Twins quand vous l’exécutez sur votre ordinateur local. Pour plus d’informations sur les différentes façons dont une application cliente peut s’authentifier auprès d’Azure Digital Twins, consultez Écrire le code d’authentification de l’application.

Avec DefaultAzureCredential, l’exemple recherche les informations d’identification dans votre environnement local, comme une connexion Azure dans une interface de ligne de commande Azure locale ou dans Visual Studio ou Visual Studio Code. C’est la raison pour laquelle vous devez vous connecter à Azure localement via l’un de ces mécanismes afin de configurer les informations d’identification pour l’exemple.

Si vous utilisez Visual Studio ou Visual Studio Code pour exécuter des exemples de code, vérifiez que vous êtes connecté à cet éditeur avec les mêmes informations d’identification Azure que celles que vous souhaitez utiliser pour accéder à votre instance Azure Digital Twins. Si vous utilisez une fenêtre CLI locale, exécutez la commande az login pour vous connecter à votre compte Azure. Après cela, lorsque vous exécutez votre échantillon de code, vous devriez être authentifié automatiquement.

Exécuter l’exemple de projet

Maintenant que l’application et l’authentification sont configurées, ouvrez une fenêtre de console locale que vous allez utiliser pour exécuter le projet. Accédez à la console vers le dossier digital-twins-samples-main\AdtSampleApp\SampleClientApp , puis exécutez le projet avec cette commande dotnet :

dotnet run

Le projet commence à s’exécuter, à effectuer l’authentification et à attendre une commande.

Voici une capture d’écran montrant à quoi ressemble la console projet :

Screenshot of the welcome message from the command-line app.

Conseil

Pour obtenir la liste de toutes les commandes que vous pouvez utiliser avec ce projet, entrez help dans la console de projet et appuyez sur Entrée.

Une fois que vous avez confirmé que l’application s’exécute correctement, vous pouvez arrêter d’exécuter le projet. Vous l’exécuterez à nouveau plus tard dans le didacticiel.

Modéliser un environnement physique avec DTDL

Maintenant que l’instance Azure Digital Twins et l’exemple d’application sont configurés, vous pouvez commencer à créer un graphe d’un scénario.

La première étape de la création d’une solution Azure Digital Twins consiste à définir des modèles de jumeaux pour votre environnement.

Les modèles sont similaires aux classes dans les langages de programmation orienté objet ; ce sont des modèles définis par l’utilisateur que vous pouvez instancier pour créer des jumeaux numériques. Les modèles pour Azure Digital Twins sont écrits dans un langage de type JSON appelé DTDL (Digital Twins Definition Language) et définissent un type de jumeau en termes de propriétés, de relations et de composants.

Remarque

DTDL permet également de définir des commandes sur des jumeaux numériques. Toutefois, les commandes ne sont actuellement pas prises en charge dans le service Azure Digital Twins.

Dans l’exemple de dossier de projet que vous avez téléchargé précédemment, accédez au dossier digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models. Ce dossier contient des exemples de modèles.

Ouvrez Room.json pour modifier et apportez les modifications suivantes au code :

  1. Mettez à jour le numéro de version pour indiquer que vous fournissez une version mise à jour de ce modèle. Pour ce faire, remplacez le 1 à la fin de la valeur @id par un 2. Tout nombre supérieur au numéro de version actuel convient aussi.

  2. Modifiez une propriété. Remplacez le nom de la propriété Humidity par HumidityLevel (ou une autre valeur si vous le souhaitez. Si vous utilisez autre chose que HumidityLevel, souvenez-vous de ce que vous avez utilisé et continuez à l’utiliser à la place de HumidityLevel tout au long du tutoriel).

  3. Ajoutez une propriété. Sous la propriété HumidityLevel qui se termine à la ligne 15, collez le code suivant pour ajouter une propriété RoomName à la pièce :

    ,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}

  4. Ajoutez une relation. Sous la propriété RoomName que vous venez d’ajouter, collez le code suivant pour permettre à ce type de jumeau de former des relations contains avec d’autres jumeaux :

    ,{
  "@type": "Relationship",
  "name": "contains"
}

Quand vous avez terminé, le modèle mis à jour doit ressembler à ceci :

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

N’oubliez pas d’enregistrer le fichier avant de continuer.

Charger des modèles sur Azure Digital Twins

Après avoir conçu les modèles, vous devez les charger sur votre instance Azure Digital Twins. Cette action configure votre instance du service Azure Digital Twins avec votre propre vocabulaire de domaine personnalisé. Une fois que vous avez chargé les modèles, vous pouvez créer des instances de jumeau qui les utilisent.

  1. Revenez à votre fenêtre de console qui s’ouvre sur le dossier digital-twins-samples-main\AdtSampleApp\SampleClientApp, puis réexécutez l’application console avec dotnet run.

  2. Dans la fenêtre de console du projet, exécutez la commande suivante pour charger votre modèle Room mis à jour avec un modèle Floor que vous utiliserez aussi dans la section suivante pour créer différents types de jumeaux.

    CreateModels Room Floor

    La sortie doit indiquer que les modèles ont été créés avec succès.

  3. Vérifiez que les modèles ont été créés en exécutant la commande GetModels true. Cette commande affiche toutes les informations pour tous les modèles qui ont été chargés sur votre instance Azure Digital Twins. Recherchez le modèle Room modifié dans les résultats :

    Screenshot of the result from GetModels, showing the updated Room model.

Conservez l’application console en cours d’exécution pour les étapes suivantes.

Erreurs

L’exemple d’application gère également les erreurs du service.

Pour tester ce problème, réexécutez la commande CreateModels pour essayer de recharger le modèle Room que vous avez déjà chargé :

CreateModels Room

Les modèles ne pouvant pas être remplacés, cette commande retourne maintenant une erreur de service indiquant que certains des ID de modèles que vous essayez de créer existent déjà.

Pour plus d’informations sur la façon de supprimer des modèles existants, consultez Gérer des modèles DTDL.

Créer des jumeaux numériques

Maintenant que certains modèles ont été chargés sur votre instance Azure Digital Twins, vous pouvez créer des jumeaux numériques basés sur les définitions de modèle. Les jumeaux numériques représentent les entités au sein de votre environnement d’entreprise (par exemple les capteurs dans une ferme, les salles d’un bâtiment ou les voyants d’une voiture).

Pour créer un jumeau numérique, utilisez la commande CreateDigitalTwin. Vous devez référencer le modèle sur lequel le jumeau est basé, et vous pouvez éventuellement définir des valeurs initiales pour les propriétés du modèle. Vous n’avez pas besoin de transmettre d’informations de relation à ce stade.

  1. Exécutez ce code dans la console de projet en cours d’exécution pour créer plusieurs jumeaux, basés sur le modèle Room que vous avez mis à jour et sur un autre modèle, Floor. Rappelez-vous que Room a trois propriétés ; vous pouvez donc fournir des arguments avec les valeurs initiales de ces propriétés. (L’initialisation des valeurs de propriétés est facultative en général, mais elle est nécessaire pour ce tutoriel.)

    CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1

    La sortie de ces commandes doit indiquer que les jumeaux ont été créés avec succès.

    Screenshot showing an excerpt from the result of the CreateDigitalTwin commands, which includes floor0, floor1, room0, and room1.

  2. Vous pouvez vérifier que les jumeaux ont été créés en exécutant la commande Query. Cette commande interroge votre instance Azure Digital Twins pour obtenir tous les jumeaux numériques qu’elle contient. Recherchez les jumeaux room0, room1, floor0 et floor1 dans les résultats.

Notes

Vous pouvez constater une latence jusqu’à 10 secondes pour que les changements que vous apportez aux données de votre graphe prennent effet dans les requêtes.

L’API DigitalTwins reflète les changements tout de suite, donc si vous avez besoin d’une réponse instantanée, utilisez une demande d’API DigitalTwins GetById ou un appel de SDK (GetDigitalTwin) pour obtenir des données de jumeau au lieu d’une requête.

Modifier un jumeau numérique

Vous pouvez également modifier les propriétés d’un jumeau que vous avez créé.

Notes

L’API REST sous-jacente utilise le format JSON Patch pour définir les mises à jour d’un jumeau. L’application en ligne de commande utilise également ce format pour offrir une expérience correspondant davantage à ce qui est attendu par les API sous-jacentes.

  1. Exécutez cette commande pour changer le RoomName de room0 de « Room0 » en « PresidentialSuite » :

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    La sortie doit indiquer que le jumeau a été correctement mis à jour.

  2. Vous pouvez vérifier que la mise à jour a réussi en exécutant cette commande pour voir les informations de room0 :

    GetDigitalTwin room0

    La sortie doit refléter le nom mis à jour.

Créer un graphe en ajoutant des relations

Ensuite, vous pouvez créer des relations entre ces jumeaux, afin de les raccorder sur un graphe de jumeaux. Les graphes de jumeaux servent à représenter un environnement entier.

Les types de relations que vous pouvez créer d’un jumeau à un autre sont définis dans les modèles que vous avez chargés. La définition de modèle pour Floor spécifie que les étages peuvent avoir un type de relation nommé contains, ce qui permet de créer une relation de type contains entre chaque jumeau Floor et la pièce correspondante qu’il contient.

Pour ajouter une relation, utilisez la commande CreateRelationship. Spécifiez le jumeau d’où provient la relation, le type de relation, et le jumeau avec lequel la relation établit une connexion. Pour finir, attribuez un ID unique à la relation.

  1. Exécutez les commandes suivantes pour ajouter une relation contains entre chaque jumeau Floor que vous avez créé et un jumeau Room correspondant. Les relations sont nommées relationship0 et relationship1.

    CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1

    Conseil

    La relation contains dans le modèle Floor a également été définie avec deux propriétés de chaîne, ownershipUser et ownershipDepartment. Vous pouvez donc aussi fournir des arguments avec les valeurs initiales de ces propriétés lorsque vous créez les relations. Voici une autre version de la commande ci-dessus pour créer relationship0 qui spécifie également des valeurs initiales pour ces propriétés :

    CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment

    La sortie de ces commandes confirme que les relations ont été créées correctement :

    Screenshot of an excerpt from the result of the CreateRelationship commands, which includes relationship0 and relationship1.

  2. Vous pouvez vérifier les relations avec l’une des commandes suivantes, qui affichent les relations dans votre instance Azure Digital Twins.

    • Pour voir toutes les relations partant de chaque étage (affichage des relations d’un côté) : 
      GetRelationships floor0
GetRelationships floor1
    • Pour voir toutes les relations arrivant à chaque pièce (affichage de la relation de l’« autre » côté) : 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • Pour rechercher ces relations individuellement, par ID : 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

Les jumeaux et les relations que vous avez configurés dans ce tutoriel forment le graphe conceptuel suivant :

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

Interroger le graphe de jumeaux pour répondre à des questions environnementales

L’une des principales fonctionnalités d’Azure Digital Twins est la capacité à interroger facilement et efficacement votre graphe de jumeaux pour répondre à des questions sur votre environnement.

Notes

Vous pouvez constater une latence jusqu’à 10 secondes pour que les changements que vous apportez aux données de votre graphe prennent effet dans les requêtes.

L’API DigitalTwins reflète les changements tout de suite, donc si vous avez besoin d’une réponse instantanée, utilisez une demande d’API DigitalTwins GetById ou un appel de SDK (GetDigitalTwin) pour obtenir des données de jumeau au lieu d’une requête.

Exécutez les commandes suivantes dans la console de projet en cours d’exécution pour répondre à certaines questions à propos de l’exemple d’environnement.

  1. Quelles sont les entités de mon environnement représentées dans Azure Digital Twins ? (interroger tout)

    Query

    Cette commande vous permet d’évaluer votre environnement en un coup d’œil et de vérifier que tout est représenté comme vous le souhaitez dans Azure Digital Twins. Le résultat de cette commande est une sortie contenant chaque jumeau numérique avec ses détails. Voici un extrait :

    Screenshot showing a partial result from the twin query, including room0 and floor1.

    Conseil

    Dans l’exemple de projet, la commande Query sans argument supplémentaire équivaut à Query SELECT * FROM DIGITALTWINS. Pour interroger tous les jumeaux dans votre instance à l’aide des API de requête ou des commandes CLI, utilisez la requête la plus longue (complète).

  2. Quelles sont les pièces dans mon environnement ? (requête par modèle)

    Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')

    Vous pouvez limiter votre requête aux jumeaux d’un certain type, afin d’obtenir des informations plus spécifiques sur ce qui est représenté. Le résultat montre room0 et room1, mais ne montre pas floor0 ni floor1 (car il s’agit d’étages, et non de pièces).

    Screenshot of the result from the model query, showing only room0 and room1.

  3. Quelles sont les pièces de floor0 ? (requête par relation)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'

    Vous pouvez interroger en fonction des relations de votre graphe, afin d’obtenir des informations sur la façon dont les jumeaux sont raccordés ou de limiter votre requête à une certaine zone. Seule room0 se trouve à l’étage floor0 ; il s’agit donc de la seule pièce dans le résultat.

    Screenshot of the result from the relationship query, showing room0.

  4. Quels sont les jumeaux dans mon environnement dont la température est supérieure à 75 ? (requête par propriété)

    Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75

    Vous pouvez interroger le graphe en fonction de propriétés afin de répondre à diverses questions, notamment pour rechercher les anomalies dans votre environnement qui peuvent nécessiter votre attention. D’autres opérateurs de comparaison (<, >, = ou !=) sont également pris en charge. room1 apparaît ici dans les résultats, car elle a une température de 80.

    Screenshot of the result from the property query, showing only room1.

  5. Quelles sont les pièces de l’étage floor0 dont la température est supérieure à 75 ? (requête composée)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75

    Vous pouvez également combiner les requêtes précédentes comme vous le feriez dans SQL, à l’aide d’opérateurs de combinaison tels que AND, OR et NOT. Cette requête utilise AND pour rendre plus spécifique la requête précédente sur les températures des jumeaux. Le résultat contient désormais uniquement les pièces dont la température est supérieure à 75 et qui se trouvent à l’étage floor0 (en l’occurrence, aucune). Le jeu de résultat est vide.

    Screenshot of the result from the compound query, showing no results.

Maintenant que vous avez exécuté plusieurs requêtes sur le scénario que vous avez configuré, le didacticiel est terminé. Arrêtez l’exécution du projet et fermez la fenêtre de console.

Nettoyer les ressources

À l’issue de ce tutoriel, vous pourrez choisir les ressources à supprimer, en fonction de ce que vous souhaitez faire ensuite.

  • Si vous envisagez de continuer avec le tutoriel suivant, vous pouvez conserver les ressources configurées ici pour continuer à utiliser cette instance Azure Digital Twins et l’exemple d’application configurée pour le prochain tutoriel.

  • Si vous souhaitez continuer à utiliser l’instance Azure Digital Twins tout en effaçant complètement ses modèles, jumeaux et relations, vous pouvez utiliser les commandes DeleteAllTwins et DeleteAllModels de l’exemple d’application pour effacer les jumeaux et modèles de l’instance, respectivement.

  • Si vous n’avez besoin d’aucune des ressources que vous avez créées dans ce tutoriel, vous pouvez supprimer l’instance d’Azure Digital Twins et toutes les autres ressources de cet article à l’aide de la commande CLI az group delete. Cette opération supprime toutes les ressources Azure d’un groupe de ressources ainsi que ce dernier.

    Important

    La suppression d’un groupe de ressources est irréversible. Le groupe de ressources et toutes les ressources qu’il contient sont supprimés définitivement. Veillez à ne pas supprimer accidentellement les mauvaises ressources ou le mauvais groupe de ressources.

    Ouvrez Azure Cloud Shell ou une fenêtre CLI locale, puis exécutez la commande suivante pour supprimer le groupe de ressources et tout ce qu’il contient.

    az group delete --name <your-resource-group>

Vous pouvez également supprimer le dossier de projet téléchargé depuis votre machine locale.

Étapes suivantes

Dans ce tutoriel, vous avez commencé à utiliser Azure Digital Twins en générant un graphe dans votre instance à l’aide d’un exemple d’application cliente. Vous avez créé des modèles, des jumeaux numériques et des relations pour former un graphe. Vous avez également exécuté des requêtes sur le graphe, pour vous faire une idée des types de questions auxquelles Azure Digital Twins peut répondre à propos d’un environnement.

Passez au tutoriel suivant pour combiner Azure Digital Twins à d’autres services Azure afin de bénéficier d’un scénario de bout en bout piloté par les données :

Connecter une solution de bout en bout