Plug-in de requête Azure Digital Twins pour Azure Data Explorer

Cet article présente le plug-in de requête Azure Digital Twins pour Azure Data Explorer, explique comment utiliser les données IoT Azure Data Explorer avec Azure Digital Twins, comment mapper des données dans Azure Data Explorer de données et Azure Digital Twins, et bien plus encore.

Le plug-in Azure Digital Twins pour Azure Data Explorer (ADX) vous permet d’exécuter des requêtes ADX qui accèdent aux données dans le graphe Azure Digital Twins et les bases de données de série chronologique ADX, et les combinent. Utilisez le plug-in pour contextualiser des données de série chronologique disparates en raisonnant sur des jumeaux numériques et leurs relations pour obtenir des insights sur le comportement d’environnements modélisés.

Par exemple, avec ce plug-in, vous pouvez écrire une requête Kusto qui :

1. sélectionne les jumeaux numériques présentant un intérêt via le plug-in de requête Azure Digital Twins ;
2. joint ces jumeaux par rapport à la série chronologique correspondante dans Azure Data Explorer ; puis
3. procède à une analytique avancée de la série chronologique sur ces jumeaux.

La combinaison des données d’un graphe de jumeaux dans Azure Digital Twins avec des données de série chronologique dans Azure Data Explorer peut vous aider à comprendre le comportement opérationnel des différentes parties de votre solution.

Utilisation du plug-in

Vous pouvez appeler le plug-in dans une requête Kusto à l’aide de la commande suivante. Notez la présence de deux espaces réservés : <Azure-Digital-Twins-endpoint> et <Azure-Digital-Twins-query>. Ces chaînes représentent respectivement le point de terminaison de l’instance Azure Digital Twins et la requête Azure Digital Twins.

evaluate azure_digital_twins_query_request(<Azure-Digital-Twins-endpoint>, <Azure-Digital-Twins-query>) 

Le plug-in fonctionne en appelant l’API de requête Azure Digital Twins. La structure du langage de requête est la même que lors de l’utilisation de l’API, à deux exceptions près :

• Le caractère générique * dans la clause SELECT n’est pas pris en charge. Au lieu de cela, les requêtes Azure Digital Twin qui sont exécutées à l’aide du plug-in doivent utiliser des alias dans la clause SELECT.

  Par exemple, considérez la requête Azure Digital Twins qui est exécutée à l’aide de l’API :

  SELECT * FROM DIGITALTWINS
  

  Pour exécuter cette requête lors de l’utilisation du plug-in, elle doit être réécrite comme suit :

  SELECT T FROM DIGITALTWINS T
  

• Les noms de colonnes retournés par le plug-in ne peuvent pas commencer par un $. L’utilisation d’alias dans la clause SELECT permettra également d’éviter ce scénario.

  Par exemple, considérez la requête Azure Digital Twins qui est exécutée à l’aide de l’API :

  SELECT T.$dtId, T.Temperature FROM DIGITALTWINS T
  

  Pour exécuter cette requête lors de l’utilisation du plug-in, elle doit être réécrite comme suit :

  SELECT T.$dtId as tid, T.Temperature FROM DIGITALTWINS T
  

Pour plus d’informations sur l’utilisation du plug-in, consultez la documentation Kusto pour le plug-in azure_digital_twins_query_request.

Pour obtenir des exemples de requêtes et effectuer une procédure pas-à-pas avec un exemple de données, consultez les exemples de requêtes et la procédure pas-à-pas du plug-in de requête Azure Digital Twins pour Azure Data Explorer dans GitHub.

Ingestion de données Azure Digital Twins dans Azure Data Explorer

Avant d’interroger les données avec le plug-in, vous devez ingérer vos données Azure Digital Twins dans Azure Data Explorer. Vous pouvez procéder de deux façons : par le biais de la fonctionnalité d’historique des données ou par le biais d’une ingestion directe. Les sections suivantes décrivent ces options plus en détail.

Ingestion avec l’historique des données

La façon la plus simple d’ingérer des données IoT dans Azure Data Explorer à partir d’Azure Digital Twins consiste à utiliser la fonctionnalité d’historique des données. Cette fonctionnalité vous permet de configurer une connexion entre votre instance Azure Digital Twins et un cluster Azure Data Explorer. De cette façon, les mises à jour de graphiques (notamment les mises à jour des propriétés de jumeaux, les événements de cycle de vie des jumeaux et les événements de cycle de vie de relation) sont automatiquement placées dans l’historique du cluster. Cette fonctionnalité constitue un bon choix si vous utilisez des données de télémétrie d’appareils pour créer vos jumeaux numériques. Pour plus d’informations sur cette fonctionnalité, consultez Historique des données (avec Azure Data Explorer).

Ingestion directe

Vous pouvez également choisir d’ingérer les données IoT directement dans votre cluster Azure Data Explorer à partir d’IoT Hub ou d’autres sources. Ensuite, le graphe Azure Digital Twins est utilisé pour contextualiser les données de série chronologique avec des requêtes Azure Digital Twins/Azure Data Explorer mixtes. Cette option est un bon choix pour les charges de travail d’ingestion directe. Toutefois, vous ne pourrez pas tirer parti de l’architecture basée sur les événements d’Azure Digital Twins pour mettre à jour d’autres jumeaux, déclencher des services en aval ou émettre des notifications lorsque les jumeaux changent d’état. Pour plus d’informations sur ce processus, consultez le reste de cette section.

Mappage de données dans Azure Data Explorer et Azure Digital Twins

Si vous ingérez des données de série chronologique directement dans Azure Data Explorer, vous devrez probablement convertir ces données brutes en schéma adapté aux requêtes Azure Digital Twins/Azure Data Explorer mixtes.

Une stratégie de mise à jour dans Azure Data Explorer vous permet de transformer et d’ajouter automatiquement des données à une table cible chaque fois que de nouvelles données sont insérées dans une table source.

Si l’ID de capteur de vos données de télémétrie d’appareil diffère de l’ID du jumeau correspondant dans Azure Digital Twins, vous pouvez utiliser une stratégie de mise à jour pour enrichir vos données de série chronologique brutes avec l’ID du jumeau, et les rendre persistantes dans une table cible. À l’aide de l’ID de jumeau, la table cible peut ensuite être jointe aux jumeaux numériques sélectionnés par le plug-in Azure Digital Twins.

Par exemple, imaginons que vous avez créé la table suivante pour stocker les données de série chronologique brutes transmises à votre instance Azure Data Explorer.

.create-merge table rawData (Timestamp:datetime, someId:string, Value:string, ValueType:string)  

Vous pouvez créer une table de mappage pour associer les ID de série chronologique aux ID de jumeau et d’autres champs facultatifs.

.create-merge table mappingTable (someId:string, twinId:string, otherMetadata:string) 

Ensuite, créez une table cible pour stocker les données de série chronologique enrichies.

.create-merge table timeseriesSilver (twinId:string, Timestamp:datetime, someId:string, otherMetadata:string, ValueNumeric:real, ValueString:string)  

Créez à présent une fonction Update_rawData pour enrichir les données brutes en les joignant à la table de mappage. Cela a pour effet d’ajouter l’ID de jumeau à la table cible résultante.

.create-or-alter function with (folder = "Update", skipvalidation = "true") Update_rawData() { 
rawData 
| join kind=leftouter mappingTable on someId 
| project 
    Timestamp, ValueNumeric = toreal(Value), ValueString = Value, ... 
} 

Enfin, créez une stratégie de mise à jour pour appeler la fonction et mettre à jour la table cible.

.alter table timeseriesSilver policy update 
@'[{"IsEnabled": true, "Source": "rawData", "Query": "Update_rawData()", "IsTransactional": false, "PropagateIngestionProperties": false}]' 

Une fois la table cible créée, vous pouvez utiliser le plug-in Azure Digital Twins pour sélectionner les jumeaux présentant un intérêt, puis les joindre aux données de série chronologique dans la table cible.

Exemple de schéma

Voici un exemple de schéma qui peut être utilisé pour représenter des données partagées. L’exemple suit le schéma d’historique des données pour les mises à jour de propriété de jumeau d’Azure Data Explorer.

Les propriétés des jumeaux numériques sont stockées sous la forme de paires clé-valeur (name, value). name et value sont stockées sous la forme de types de données dynamiques.

Le schéma prend également en charge le stockage des propriétés pour les relations, grâce aux champs relationshipTarget et relationshipID. Le schéma clé-valeur vous évite d’avoir à créer une colonne pour chaque propriété de jumeau.

Représentation de propriétés avec plusieurs champs

Vous pouvez être amené à stocker une propriété dans votre schéma avec plusieurs champs. Pour représenter ces propriétés, stockez un objet JSON en tant que value dans votre schéma.

Par exemple, si vous souhaitez représenter une propriété avec trois champs (roulis, tangage et lacet), l’objet de valeur ressemble à ceci : {"roll": 20, "pitch": 15, "yaw": 45}.

Étapes suivantes

• Consultez la documentation du plug-in pour le langage Kusto dans Azure Data Explorer : azure_digital_twins_query_request plugin

• Examinez des exemples de requêtes utilisant le plug-in, notamment une procédure pas-à-pas qui exécute les requêtes dans un exemple de scénario : Plug-in de requête Azure Digital Twins pour Azure Data Explorer : exemples de requêtes et procédure pas-à-pas