Intégrer Azure Digital Twins avec Azure Time Series Insights

Article
03/09/2023

Dans cet article, vous allez apprendre à intégrer Azure Digital Twins avec Azure Time Series Insights (TSI).

La solution décrite dans cet article utilise Time Series Insights pour collecter et analyser les données d’historique relatives à votre solution IoT. Azure Digital Twins est idéal pour envoyer des données dans Time Series Insights, car il vous permet de mettre en corrélation plusieurs flux de données et de normaliser vos informations avant de les envoyer à Time Series Insights.

Conseil

Le moyen le plus simple d’analyser les données de jumeau historique au fil du temps consiste à utiliser la fonctionnalité d’historique des données pour connecter une instance Azure Digital Twins à un cluster Azure Data Explorer, afin que les mises à jour de graphe soient automatiquement historisées sur Azure Data Explorer. Vous pouvez ensuite interroger ces données dans Azure Data Explorer à l’aide du plug-in de requête Azure Digital Twins pour Azure Data Explorer. Si vous n’avez pas besoin d’utiliser Time Series Insights, vous pouvez envisager cette alternative pour une expérience d’intégration plus simple.

Prérequis

Avant de pouvoir configurer une relation avec Time Series Insights, vous devez configurer les ressources suivantes :

Une instance d’Azure Digital Twins. Pour obtenir des instructions, consultez Configurer une instance Azure Digital Twins et l’authentification.
Un modèle et un jumeau dans l’instance Azure Digital Twins. Vous devez mettre à jour les informations du jumeau plusieurs fois pour voir ces données suivies dans Time Series Insights. Pour obtenir des instructions, consultez Ajouter un modèle et un jumeau.

Conseil

Dans cet article, les valeurs de jumeau changeantes qui sont affichées dans Time Series Insights sont mises à jour manuellement par souci de simplicité. Toutefois, si vous souhaitez suivre cet article avec des données simulées en temps réel, vous pouvez configurer une fonction Azure qui met à jour les jumeaux en fonction des événements de télémétrie IoT à partir d’un appareil simulé. Pour obtenir des instructions, consultez Ingérer les données d’IoT Hub, notamment les dernières étapes pour exécuter le simulateur d’appareil et valider le fonctionnement du workflow.

Plus tard, recherchez un autre conseil pour vous montrer où démarrer l’exécution du simulateur d’appareil et faire en sorte que vos fonctions Azure mettent à jour automatiquement les jumeaux, au lieu d’envoyer des commandes de mise à jour de jumeau manuellement.

Architecture de solution

Vous allez attacher Time Series Insights à Azure Digital Twins via le chemin d’accès ci-dessous.

Créer un espace de noms Event Hubs

Avant de créer les Event Hubs, vous allez d’abord créer un espace de noms Event Hubs qui recevra les événements de votre instance Azure Digital Twins. Vous pouvez utiliser les instructions Azure CLI ci-dessous ou utiliser le portail Azure en suivant Créer un hub d’événements avec le portail Azure. Pour voir les régions qui prennent en charge Event Hubs, consultez Produits Azure disponibles par région.

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

Conseil

Si vous recevez une erreur indiquant BadRequest: The specified service namespace is invalid., vérifiez que le nom que vous avez choisi pour votre espace de noms répond aux conditions d’attribution de noms décrites dans ce document de référence : Créer un espace de noms.

Vous allez utiliser cet espace de noms Event Hubs pour conserver les deux hubs d’événements qui sont nécessaires pour cet article :

Hub Twins - Instance Event Hub pour recevoir les événements de changement de jumeau
Hub Time Series - Instance Event Hub pour diffuser des événements à Time Series Insights

Les sections suivantes vous guideront dans la création et la configuration de ces hubs dans votre espace de noms Event Hub.

Créer un hub Twins

La première instance Event Hub que vous allez créer dans cet article est le Hub Twins. Cet Event Hub recevra les événements de changement de jumeau d’Azure Digital Twins. Pour configurer le hub Twins, procédez comme suit dans cette section :

Créer le hub Twins
Créer une règle d’autorisation pour contrôler les autorisations sur le hub
Créer un point de terminaison dans Azure Digital Twins qui utilise la règle d’autorisation pour accéder au hub
Créer un itinéraire dans Azure Digital Twins qui envoie un événement de mise à jour de jumeau au point de terminaison et au hub Twins connecté
Définir la chaîne de connexion du hub Twins

Créez le hub Twins avec la commande CLI suivante. Spécifiez un nom pour votre hub Twins.

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Créer une règle d’autorisation pour le hub Twins

Créez une règle d’autorisation avec les autorisations d’envoi et de réception. Spécifiez un nom pour la règle.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Créer un point de terminaison pour le hub Twins

Créez un point de terminaison Azure Digital Twins qui lie votre hub d’événements à votre instance Azure Digital Twins. Spécifiez un nom pour le point de terminaison de votre hub Twins.

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Créer un itinéraire d’événement hub Twins

Les instances Azure Digital Twins peuvent émettre des événements de mise à jour des jumeaux chaque fois que l’état d’un jumeau est mis à jour. Dans cette section, vous allez créer un itinéraire d’événement Azure Digital Twins qui dirigera ces événements de mise à jour vers le hub Twins en vue d’un traitement ultérieur.

Créez un itinéraire dans Azure Digital Twins pour envoyer des événements de mise à jour de jumeaux à votre point de terminaison à partir d’en haut. Le filtre de cet itinéraire permet uniquement aux messages de mise à jour de jumeaux d’être transmis à votre point de terminaison. Spécifiez un nom pour l’itinéraire d’événement du hub Twins. Pour l’espace réservé de nom d’instance Azure Digital Twins dans cette commande, vous pouvez utiliser le nom convivial ou le nom d’hôte pour améliorer les performances.

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Obtient la chaîne de connexion du hub Twins

Récupérez la chaîne de connexion Event Hub de Twins à l’aide des règles d’autorisation que vous avez créées ci-dessus pour le Hub de Twins.

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

Prenez note de la valeur primaryConnectionString du résultat pour configurer le paramètre d’application du hub Twins plus loin dans cet article.

Créer un hub Time Series

Le deuxième Event Hub que vous allez créer dans cet article est le hub Time Series. Ce hub d’événements est celui qui enverra en streaming les événements Azure Digital Twins à Time Series Insights. Pour configurer le hub Time Series, effectuez les étapes suivantes :

Créer le hub Time Series
Créer une règle d’autorisation pour contrôler les autorisations sur le hub
Obtient la chaîne de connexion du hub Time Series

Plus tard, lorsque vous créerez l’instance Time Series Insights, vous connecterez ce hub Time Series en tant que source d’événements pour l’instance Time Series Insights.

Créez le hub Time Series à l’aide de la commande suivante. Spécifiez un nom pour le hub Time Series.

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Créer une règle d’autorisation de hub Time Series

Créez une règle d’autorisation avec les autorisations d’envoi et de réception. Spécifiez un nom pour la règle d’authentification du hub Time Series.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Obtient la chaîne de connexion du hub Time Series

Récupérez la chaîne de connexion du hub Time Series à l’aide des règles d’autorisation que vous avez créées ci-dessus pour le hub Time Series Insights :

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

Prenez note de la valeur primaryConnectionString du résultat pour configurer le paramètre d’application du hub Time Series plus loin dans cet article.

Notez également les valeurs suivantes pour les utiliser ultérieurement pour créer une instance Time Series Insights.

Espace de noms du hub d’événements
Nom du hub Time Series
Règle d’authentification du hub Time Series

Créer une fonction

Dans cette section, vous allez créer une fonction Azure qui convertit les événements de mise à jour de jumeaux de leur forme d’origine en tant que documents de correctifs JSON en objets JSON contenant uniquement des valeurs mises à jour et ajoutées à partir de vos jumeaux.

Tout d’abord, créez un projet d’application de fonction.

Pour ce faire, vous pouvez utiliser Visual Studio (pour obtenir des instructions, voir Développer Azure Functions à l’aide de Visual Studio), Visual Studio Code (pour obtenir des instructions, voir Créer une fonction C# dans Azure à l’aide de Visual Studio Code) ou d’Azure CLI (pour obtenir des instructions, consultez Créer une fonction C# dans Azure à partir de la ligne de commande).
Créez une nouvelle fonction Azure appelée ProcessDTUpdatetoTSI.cs pour mettre à jour les événements de télémétrie de l’appareil vers Time Series Insights. Le type de fonction sera Déclencheur Event Hub.
Ajoutez les packages suivants à votre projet (vous pouvez utiliser le gestionnaire de package Visual Studio NuGet ou la commande dotnet add package dans un outil de ligne de commande).

Remplacez le code du fichier ProcessDTUpdatetoTSI.cs par le code suivant :

using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

Enregistrez le code de votre fonction.

Publiez le projet avec la fonction ProcessDTUpdatetoTSI.cs dans une application de fonction dans Azure.

Pour obtenir des instructions sur la façon de publier une fonction à l’aide de Visual Studio, consultez Développer des Azure Functions à l’aide de Visual Studio. Pour obtenir des instructions sur la publication de la fonction à l’aide de Visual Studio Code, consultez Créer une fonction C# dans Azure à l’aide de Visual Studio Code. Pour obtenir des instructions sur la publication de la fonction à l’aide d’Azure CLI, consultez Créer une fonction C# dans Azure à partir de la ligne de commande.

Enregistrez le nom de l’application de fonction pour l’utiliser ultérieurement pour configurer les paramètres de l’application pour les deux hubs d’événements.

Configurer l’application de fonction

Ensuite, attribuez un rôle d’accès à la fonction et configurez les paramètres de l’application afin qu’elle puisse accéder à vos ressources.

Exécutez les commandes suivantes dans Azure Cloud Shell ou une interface locale d’Azure CLI.

Notes

Cette section doit être effectuée par un utilisateur Azure qui dispose des autorisations nécessaires pour gérer l’accès utilisateur aux ressources Azure, y compris l’octroi et la délégation d’autorisations. Les rôles communs qui répondent à cette exigence sont Propriétaire, Administrateur de compte ou la combinaison des rôles Administrateur de l’accès utilisateur et Contributeur. Pour plus d’informations sur les exigences d’autorisation pour les rôles Azure Digital Twins, consultez Configurer une instance et l’authentification.

Attribuer un rôle d’accès

La fonction Azure nécessite un jeton de porteur pour transmission. Pour vous assurer que le jeton du porteur est transmis, accordez à l’Application de fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins, ce qui permettra à l’application de fonction d’effectuer des activités de plan de données sur l’instance.

Utilisez la commande suivante pour créer une identité managée par le système pour votre fonction (si la fonction en a déjà une, cette commande imprimera ses détails). Prenez note du champ principalId dans la sortie. Vous utiliserez cet ID pour faire référence à la fonction afin de pouvoir lui accorder des autorisations à l’étape suivante.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Utilisez la principalId valeur dans la commande suivante afin d’affecter à la fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Configurer les paramètres de l’application

Enfin, rendez l’URL de votre instance Azure Digital Twins accessible à votre fonction en lui définissant une variable d’environnement.

Conseil

L’URL de l’instance Azure Digital Twins est créée en ajoutant https:// au début du nom d’hôte de votre instance. Pour afficher le nom d’hôte, ainsi que toutes les propriétés de votre instance, exécutez az dt show --dt-name <your-Azure-Digital-Twins-instance>.

La commande suivante définit une variable d’environnement pour l’URL d’instance que votre fonction utilisera chaque fois qu’elle aura besoin d’accéder à l’instance.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Ensuite, ajoutez des variables d’environnement dans les paramètres de l’application de fonction qui lui permettent d’accéder aux hubs Twins et Time Series.

Utilisez la valeur du hub Twins primaryConnectionString que vous avez enregistrée précédemment pour créer un paramètre d’application dans votre application de fonction qui contient la chaîne de connexion du hub Twins :

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Utilisez la valeur du hub Time Series primaryConnectionString que vous avez enregistrée précédemment pour créer un paramètre d’application dans votre application de fonction qui contient la chaîne de connexion du hub Time Series :

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Créer et connecter une instance Time Series Insights

Dans cette section, vous allez configurer une instance Time Series Insights pour recevoir des données de votre hub Time Series. Pour plus d’informations sur ce processus, consultez Configurer un environnement Azure Time Series Insights Gen2 avec paiement à l’utilisation. Suivez les étapes ci-dessous pour créer un environnement Time Series Insights.

Dans le portail Azure, recherchez Environnements Time Series Insights, puis cliquez sur le bouton Créer. Choisissez les options suivantes pour créer l’environnement Time Series.
- Abonnement : Choisissez votre abonnement.
  - Groupe de ressources : Choisissez votre groupe de ressources.
- Nom de l’environnement : Spécifiez un nom pour votre environnement Time Series.
- Emplacement - Choisissez un emplacement.
- Niveau : choisissez le niveau tarifaire Gen2 (L1) .
- Nom de propriété - Entrez $dtId (Pour plus d’informations sur la sélection d’une valeur d’ID, consultez Meilleures pratiques pour choisir un ID de série chronologique).
- Nom du compte de stockage : Spécifiez un nom de compte de stockage.
- Activer le magasin chaud : laissez ce champ défini sur Oui.
Vous pouvez laisser les valeurs par défaut pour les autres propriétés de cette page. Sélectionnez le bouton Suivant : Source de l’événement >.
Dans l’onglet Source de l’événement, choisissez les champs suivants :
- Créer une source d’événement ? - Choisissez Oui.
- Type de source : Choisissez Event Hub.
- Nom : Spécifiez un nom pour votre source d’événement.
- Abonnement : Choisissez votre abonnement Azure.
- Espace de noms Event Hub : Choisissez l’espace de noms que vous avez créé précédemment dans cet article.
- Nom Event Hub : Choisissez le nom du hub Time Series que vous avez créé précédemment dans cet article.
- Nom de la stratégie d’accès Event Hub : Choisissez la règle d’authentification hub Time Series que vous avez créée précédemment dans cet article.
- Groupe de consommateurs Event Hub : Sélectionnez Nouveau et spécifiez un nom pour votre groupe de consommateurs Event Hub. Sélectionnez ensuite Ajouter.
- Nom de propriété : Laissez ce champ vide.
Choisissez le bouton Vérifier + créer pour passer en revue tous les détails. Ensuite, sélectionnez à nouveau le bouton Vérifier + créer pour créer l’environnement Time Series.

Envoyer des données IoT à Azure Digital Twins

Pour commencer à envoyer des données à Time Series Insights, vous devez commencer à mettre à jour les propriétés dans Azure Digital Twins avec des valeurs de données variables.

Utilisez la commande d’interface de ligne de commande az dt twin update pour mettre à jour une propriété sur le jumeau numérique que vous avez ajouté dans la section Prérequis. Si vous avez utilisé les instructions de création de jumeau depuis Ingérer la télémétrie depuis IoT Hub, vous pouvez utiliser la commande suivante dans l’interface de ligne de commande locale ou le terminal bash Cloud Shell pour mettre à jour la propriété de température sur le jumeau thermostat67. Il existe un espace réservé pour le nom d’hôte de l’instance Azure Digital Twins. (Vous pouvez également utiliser le nom convivial de l’instance avec une légère baisse des performances.)

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Répétez la commande au moins quatre fois avec différentes valeurs de propriété pour créer plusieurs points de données qui peuvent être observés plus tard dans l’environnement Time Series Insights.

Conseil

Si vous souhaitez terminer cet article avec des données simulées en temps réel au lieu de mettre à jour manuellement les valeurs numériques, commencez par vous assurer que vous avez appliqué le Conseil de la section Conditions préalables pour configurer une fonction Azure qui met à jour les jumeaux à partir d’un appareil simulé. Après cela, vous pouvez exécuter l’appareil pour commencer à envoyer des données simulées et mettre à jour votre jumeau par le biais de ce flux de données.

Visualiser vos données dans Time Series Insights

À présent, les données devraient être transmises à votre instance Time Series Insights, prêtes à être analysées. Suivez les étapes ci-dessous pour explorer les données entrantes.

Dans le portail Azure, recherchez le nom de l’environnement Time Series que vous avez créé précédemment. Dans les options de menu sur la gauche, sélectionnez Vue d’ensemble pour afficher l’URL de l’Explorateur Time Series Insights. Sélectionnez l’URL pour afficher les modifications de température reflétées dans l’environnement Time Series Insights.
Dans l’Explorateur, vous voyez les jumeaux dans l’instance Azure Digital Twins affichée à gauche. Sélectionnez le jumeau dont vous avez modifié les propriétés, choisissez la propriété que vous avez changée, puis sélectionnez Ajouter.
Vous devez maintenant voir les modifications de propriété que vous avez apportées dans le graphique, comme indiqué ci-dessous.

Si vous autorisez l’exécution d’une simulation pendant une durée plus longue, votre visualisation ressemble à ce qui suit :

Étapes suivantes

Après avoir établi un pipeline de données pour envoyer des données de série chronologique d’Azure Digital Twins à Time Series Insights, vous pouvez réfléchir à la façon de traduire des modèles de ressources conçus pour Azure Digital Twins en modèles de ressource pour Time Series Insights. Pour obtenir un tutoriel sur cette étape suivante du processus d’intégration, consultez Synchronisation des modèles entre Azure Digital Twins et Time Series Insights Gen2.

Intégrer Azure Digital Twins avec Azure Time Series Insights

Prérequis

Architecture de solution

Créer un espace de noms Event Hubs

Créer un hub Twins

Créer une règle d’autorisation pour le hub Twins

Créer un point de terminaison pour le hub Twins

Créer un itinéraire d’événement hub Twins

Obtient la chaîne de connexion du hub Twins

Créer un hub Time Series

Créer une règle d’autorisation de hub Time Series

Obtient la chaîne de connexion du hub Time Series

Créer une fonction

Configurer l’application de fonction

Attribuer un rôle d’accès

Configurer les paramètres de l’application

Créer et connecter une instance Time Series Insights

Envoyer des données IoT à Azure Digital Twins

Visualiser vos données dans Time Series Insights

Étapes suivantes

Ressources supplémentaires