Tutoriel : Déployer La préversion d’Azure Digital Twins et configurer un graphe spatial

Article
01/10/2020

Important

Une nouvelle version du service Azure Digital Twins a été publiée. À la lumière des fonctionnalités étendues du nouveau service, le service Azure Digital Twins d’origine (décrit dans cet ensemble de documentation) a été supprimé.

Pour afficher la documentation du nouveau service, consultez la documentation Azure Digital Twins active.

Vous pouvez utiliser le service Azure Digital Twins en préversion pour rassembler des personnes, des lieux et des appareils dans un système spatial homogène. Cette série de tutoriels montre comment utiliser Azure Digital Twins pour détecter l’occupation d’une salle avec des conditions optimales de qualité d’air et de température.

Ces tutoriels vous guident dans une application de console .NET pour créer un scénario de bâtiment hébergeant des bureaux. L’immeuble comprend plusieurs étages et plusieurs salles à chaque étage. Dans les salles se trouvent des appareils auxquels sont reliés des capteurs qui détectent les mouvements, la température ambiante et la qualité de l’air.

Vous allez apprendre à répliquer les entités et les zones physiques du bâtiment, tels que des objets numériques en utilisant le service Azure Digital Twins. Vous allez simuler des événements d’appareil à l’aide d’une autre application console. Ensuite, vous allez apprendre à superviser presque en temps réel les événements qui proviennent de ces entités et zones physiques.

Un administrateur de bureau peut utiliser ces informations pour aider un employé travaillant dans ce bâtiment à réserver des salles de réunion avec des conditions optimales. Un responsable des locaux de bureau peut utiliser votre configuration pour obtenir les tendances d’utilisation des salles, et également surveiller les conditions de travail à des fins de maintenance.

Dans le premier didacticiel de cette série, vous allez apprendre à effectuer les actions suivantes :

Déployer Digital Twins.
Accorder des autorisations à votre application.
Modifier un exemple d’application Digital Twins.
Provisionner votre bâtiment.

Ces didacticiels utilisent et modifient les mêmes exemples que ceux du démarrage rapide de recherche de salles disponibles, pour une couverture plus détaillée des concepts.

Prérequis

Un abonnement Azure. Si vous n’avez pas de compte Azure, créez un compte gratuit.
Le kit SDK .NET Core. Les exemples Azure Digital Twins utilisés dans ces tutoriels sont écrits en C#. Veillez à installer le kit SDK .NET Core version 2.1.403 ou ultérieure sur votre machine de développement pour créer et exécuter l’exemple. Vérifiez que la version appropriée est installée sur votre machine en exécutant dotnet --version dans une fenêtre de commande.
Visual Studio Code pour explorer l’exemple de code.

Déployer Digital Twins

Utilisez les étapes de cette section pour créer une instance du service Azure Digital Twins. Une seule instance peut être créée par abonnement. Passez à la section suivante si vous en avez déjà une en cours d’exécution.

Connectez-vous au portail Azure.
Sélectionnez la barre latérale, puis + Créer une ressource.
Recherchez Digital Twins, puis sélectionnez Digital Twins.

Vous pouvez également sélectionner Internet des objets, puis Digital Twins (version préliminaire).
Sélectionnez Créer pour commencer le processus de déploiement.
Dans le volet Digital Twins, entrez les informations suivantes :
- Nom de la ressource : créez un nom unique pour votre instance Digital Twins.
- Abonnement : choisissez l’abonnement que vous souhaitez utiliser pour créer cette instance Digital Twins.
- Groupe de ressources : sélectionnez ou créez un groupe de ressources pour l’instance Digital Twins.
- Emplacement : sélectionnez l’emplacement le plus proche de vos appareils.
Vérifiez les informations de votre instance Digital Twins et sélectionnez Créer. La création de votre instance Digital Twins peut prendre quelques minutes. Vous pouvez suivre la progression dans le volet Notifications.
Ouvrez le volet Vue d’ensemble de votre instance Digital Twins. Notez le lien sous API de gestion. L’URL de l’API de gestion respecte le format suivant :
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
Cette URL vous renvoie à la documentation de l’API REST d’Azure Digital Twins qui correspond à votre instance. Pour savoir comment lire et utiliser la documentation de cette API, consultez la section Comment utiliser Azure Digital Twins Swagger. Copiez et modifiez l’URL de l’API de gestion pour qu’elle respecte le format suivant :
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
Votre application se servira de l’URL modifiée comme de l’URL de base pour accéder à votre instance. Copiez cette URL modifiée dans un fichier temporaire. Vous en aurez besoin dans la prochaine section.

Accorder des autorisations à votre application

Digital Twins utilise Azure Active Directory (Azure AD) pour contrôler l’accès en lecture/écriture au service. Les applications devant se connecter à votre instance Digital Twins doivent être inscrites auprès d’Azure AD. La procédure décrite dans cette section montre comment inscrire votre exemple d’application.

Si vous disposez déjà d’une inscription d’application, vous pouvez la réutiliser pour votre exemple. Toutefois, parcourez cette section pour vous assurer que l’inscription de votre application est correctement configurée.

Notes

Cette section fournit les instructions sur l’inscription de l'application Azure AD.

Dans le Portail Azure, ouvrez Azure Active Directory dans le menu de gauche développable, puis ouvrez le volet Inscriptions d’applications.
Sélectionnez le bouton + Nouvelle inscription.
Dans la zone Nom, donnez un nom convivial à l’inscription de cette application.
1. Sous la section URI de redirection (facultatif), entrez https://microsoft.com dans la zone de texte.
2. Vérifiez quels comptes et locataires sont pris en charge par votre application Azure Active Directory.
3. Sélectionnez Inscription.
Le panneau Authentification spécifie les paramètres importants de configuration d’authentification.
1. Ajoutez des URI de redirection et configurez des Jetons d’accès en sélectionnant + Ajouter une plateforme.
2. Sélectionnez Oui pour indiquer que l’application est un client public.
3. Vérifiez quels comptes et locataires sont pris en charge par votre application Azure Active Directory.
Après avoir sélectionné la plateforme appropriée, configurez vos URI de redirection et Jetons d’accès dans le volet latéral situé à droite de l’interface utilisateur.
1. L’URI de redirection doit correspondre à l’adresse fournie par la requête d’authentification :
  - Pour les applications hébergées dans un environnement de développement local, sélectionnez Client public (mobile et bureau) . Veillez à affecter la valeur Oui à Client public.
  - Pour les applications monopages hébergées sur Azure App Service, sélectionnez Web.
2. Déterminez si une URL de déconnexion est appropriée.
3. Activez le flux d’octroi implicite en cochant les Jeton d'accès ou Jetons d'ID.
Cliquez sur Configurer, puis sur Enregistrer.
Ouvrez le volet Vue d’ensemble de votre application inscrite, et copiez les valeurs des entités suivantes dans un fichier temporaire. Ces valeurs vous permettront de configurer votre exemple d’application dans les sections suivantes.
- ID d’application (client)
- ID de l’annuaire (locataire)
Ouvrez le volet API autorisées pour l’inscription de votre application. Sélectionnez le bouton + Ajouter une autorisation. Dans le volet Demander des autorisations d’API, sélectionnez l’onglet API utilisées par mon organisation, puis recherchez un des éléments suivants :
1. Azure Digital Twins. Sélectionnez l’API Azure Digital Twins.
2. Vous pouvez également rechercher Azure Smart Spaces Service. Sélectionnez l’API Azure Smart Spaces Service.
Important

Le nom et l’ID de l’API Azure AD qui s’affichent dépendent de votre locataire :
- Les comptes de locataire et client utilisés pour les tests doivent rechercher Azure Digital Twins.
- Les autres comptes Microsoft doivent rechercher Azure Smart Spaces Service.
L'une ou l’autre API apparaît sous Azure Digital Twins dans le même volet Demander des autorisations d’API. Sélectionnez l'option de liste déroulante Read (Lire), puis activez la case à cocher Read.Write (Lire.Écrire). Sélectionnez le bouton Ajouter des autorisations.
Selon les paramètres de votre organisation, vous devrez peut-être prendre des mesures supplémentaires pour autoriser l’accès de l’administrateur à cette API. Contactez votre administrateur pour obtenir plus d’informations. Une fois l’accès administrateur approuvé, la colonne Consentement administrateur requis du volet Autorisations des API affichera vos autorisations.

Vérifiez que Azure Digital Twins s’affiche.

Configurer l’exemple Digital Twins

Cette section vous guide dans une application Azure Digital Twins qui communique avec les API REST Digital Twins.

Télécharger l’exemple

Si vous avez déjà les exemples téléchargés pour le démarrage rapide de recherche de salles disponibles, vous pouvez ignorer ces étapes.

Téléchargez les exemples .NET Digital Twins.
Extrayez le contenu du dossier zip sur votre machine.

Explorer l’exemple

Dans l’exemple de dossier extrait, ouvrez le fichier digital-twins-samples-csharp\digital-twins-samples.code-workspace dans Visual Studio Code. Il inclut deux projets :

Vous pouvez utiliser l’exemple de provisionnement occupancy-quickstart pour configurer et provisionner un graphe d’intelligence spatiale. Ce graphe constitue l’image numérisée de vos espaces physiques et des ressources qu’ils contiennent. Il utilise un modèle objet qui définit les objets d’un bâtiment intelligent. Pour obtenir une liste complète des objets et API REST Digital Twins, consultez cette documentation sur les API REST ou l’URL de l’API de gestion qui a été créée pour votre instance.

Pour explorer l’exemple et comprendre comment il communique avec votre instance Digital Twins, vous pouvez commencer avec le dossier src\actions. Les fichiers dans ce dossier implémentent les commandes que vous allez utiliser dans ces tutoriels :
- Le fichier provisionSample.cs montre comment provisionner votre graphe spatial.
- Le fichier getSpaces.cs récupère des informations sur les espaces provisionnés.
- Le fichier getAvailableAndFreshSpaces.cs récupère les résultats d’une fonction personnalisée appelée fonction définie par l’utilisateur.
- Le fichier createEndpoints.cs crée des points de terminaison pour interagir avec d’autres services.
L’exemple de simulation device-connectivity simule les données de capteur et les envoie au hub IoT qui est provisionné pour votre instance Digital Twins. Vous allez utiliser cet exemple dans le tutoriel suivant, après avoir provisionné votre graphe spatial. Les identificateurs d’appareils et de capteurs que vous utilisez pour configurer cet exemple doivent être les mêmes que ceux que vous allez utiliser pour provisionner votre graphe.

Configurer l’exemple d’approvisionnement

Ouvrez une fenêtre de commande et accédez à l’exemple téléchargé. Exécutez la commande suivante :
```
cd occupancy-quickstart/src
```
Restaurez les dépendances sur l’exemple de projet en exécutant cette commande :
```
dotnet restore
```
Dans Visual Studio Code, ouvrez le fichier appSettings.json dans le projet occupancy-quickstart. Utilisez les valeurs suivantes :
- ClientId : entrez l’ID d’application de l’inscription de votre application Azure AD. Vous avez noté cet ID à la section où vous avez défini des autorisations d’application.
- Tenant : entrez l’ID de répertoire de votre locataire Azure AD. Vous avez également noté cet ID à la section où vous avez défini des autorisations d’application.
- BaseUrl: entrez l’URL de votre instance Digital Twins. Pour obtenir cette URL, remplacez les espaces réservés dans cette URL par les valeurs de votre instance : https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Vous pouvez également obtenir cette URL en modifiant l’URL API de gestion depuis la section de déploiement. Remplacez swagger/ par api/v1.0/.
Examinez la liste des fonctionnalités Digital Twins que vous pouvez explorer à l’aide de l’exemple. Exécutez la commande suivante :
```
dotnet run
```

Comprendre le processus de provisionnement

Cette section montre comment l’exemple approvisionne un graphique spatial d’un bâtiment.

Dans Visual Studio Code, accédez au dossier occupancy-quickstart\src\actions et ouvrez le fichier provisionSample.cs. Notez la fonction suivante :

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Cette fonction utilise le fichier provisionSample.yaml dans le même dossier. Ouvrez ce fichier et notez la hiérarchie d’un bâtiment hébergeant des bureaux : Venue (Lieu), Floor (Étage), Area (Zone) et Rooms (Salles). Tous ces espaces physiques peuvent contenir des appareils et des capteurs. Chaque entrée a un prédéfini type, par exemple, Floor, Room.

L’exemple de fichier yaml montre un graphe spatial qui utilise le modèle objet Digital Twins Default. Ce modèle fournit des noms génériques pour la plupart des types. Les noms génériques sont suffisants pour un bâtiment. Les exemples sont Temperature (Température) pour SensorDataType (TypeDonnéesCapteur), et Map (Carte) pour SpaceBlobType (TypeObjetBlobEspace). Un exemple de type d’espace est Room (Salle) avec des sous-types, tels que FocusRoom (SalleTravail), ConferenceRoom (SalleRéunion) et ainsi de suite.

Si vous deviez créer un graphique spatial pour un lieu de type différent, par exemple une usine, vous auriez probablement besoin d’un autre modèle objet. Vous pouvez rechercher les modèles disponibles en exécutant la commande dotnet run GetOntologies dans la ligne de commande pour l’exemple de provisionnement.

Pour plus d’informations sur les graphes spatiaux et les modèles objet, consultez Présentation du graphe d’intelligence spatiale et des modèles objet Digital Twins.

Modifier l’exemple de graphe spatial

Le fichier provisionSample.yaml contient les nœuds suivants :

ressources : le nœud resources crée une ressource Azure IoT Hub pour communiquer avec les appareils de votre configuration. Un hub IoT au niveau du nœud racine de votre graphe peut communiquer avec tous les appareils et tous les capteurs dans votre graphe.
spaces : dans le modèle d’objet Digital Twins, l’élément spaces représente les emplacements physiques. Chaque espace a un Type( par exemple, Région, Lieu ou Client) et un convivial Name. Les espaces peuvent appartenir à d’autres espaces, ce qui crée une structure hiérarchique. Le fichier provisionSample.yaml contient le graphe spatial d’un bâtiment imaginaire. Remarquez l’imbrication logique des espaces de type Floor au sein de Venue, de Area à un étage, et des nœuds Room dans une zone.
devices: les espaces peuvent contenir des éléments devices, qui sont des entités physiques ou virtuelles gérant un certain nombre de capteurs. Par exemple, un appareil peut être le téléphone d’un utilisateur, un pod de capteur Raspberry Pi ou une passerelle. Dans le bâtiment imaginaire de votre exemple, notez que la salle nommée Focus Room (Salle de réflexion) contient un appareil Raspberry Pi 3 A1. Chaque nœud d’appareil est identifié par un élément hardwareId unique, qui est codé en dur dans l’exemple. Pour configurer cet exemple pour une production réelle, remplacez ces éléments par des valeurs de votre configuration.
capteurs : un appareil peut contenir plusieurs sensors. Ils peuvent détecter et enregistrer des modifications physiques, telles que la température, les mouvements et le niveau de batterie. Chaque nœud de capteur est identifié de façon unique par un élément hardwareId, codé en dur ici. Pour une application réelle, remplacez ceux-ci en utilisant les identificateurs uniques des capteurs de votre configuration. Le fichier provisionSample.yaml contient deux capteurs pour enregistrer Motion (les mouvements) et CarbonDioxide (le dioxyde de carbone). Ajoutez un autre capteur pour enregistrer Température, en ajoutant les lignes suivantes sous les lignes du capteur CarbonDioxide. Ces éléments sont fournis dans provisionSample.yaml en tant que lignes commentées. Vous pouvez supprimer les marques de commentaire en retirant le caractère # au début de chaque ligne.
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
Notes

Assurez-vous que les clés dataType et hardwareId correspondent aux instructions données au-dessus de cet extrait de code. Assurez-vous également que votre éditeur ne remplace pas les espaces par des tabulations.

Enregistrez et fermez le fichier provisionSample.yaml. Dans le tutoriel suivant, vous allez ajouter d’autres informations à ce fichier et provisionner votre exemple de bâtiment Azure Digital Twins.

Conseil

Vous pouvez afficher et modifier votre graphe spatial à l’aide de la Visionneuse de graphe Azure Digital Twins.

Nettoyer les ressources

Si vous souhaitez arrêter votre exploration d’Azure Digital Twins ici, vous pouvez supprimer les ressources créées dans ce tutoriel :

Dans le menu de gauche du portail Azure, sélectionnez Toutes les ressources, puis votre groupe de ressources Digital Twins et Supprimer.

Conseil

Si vous avez rencontré des difficultés pour supprimer votre instance de Digital Twins, une mise à jour du service a été déployée avec le correctif. Réessayez de supprimer votre instance.
Si nécessaire, supprimez l’exemple d’application sur votre machine de travail.

Étapes suivantes

Pour savoir comment implémenter une logique personnalisée et superviser les conditions au sein de votre exemple de bâtiment, passez au tutoriel suivant de cette série :

Tutorial: Provision your building and monitor working conditions with Azure Digital Twins (Didacticiel : Approvisionner votre bâtiment et surveiller les conditions de travail avec Azure Digital Twins)