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

  • Article

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 requête Azure Digital Twins et la structure du langage de requête est la même que lors de l’utilisation de l’API, avec deux exceptions :

  • 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

Important

L’utilisateur du plug-in doit disposer du rôle Lecteur de données Azure Digital Twins ou du rôle Propriétaire des données Azure Digital Twins, car le jeton Microsoft Entra de l’utilisateur est utilisé pour s’authentifier. Vous trouverez des informations sur la façon d’attribuer ce rôle dans Sécurité pour les solutions Azure Digital Twins.

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 et les mises à jour de graphiques (notamment les mises à jour de propriétés de jumeau, les événements de cycle de vie des jumeaux et les événements de cycle de vie des relations) sont automatiquement historisées sur le cluster. Il s’agit d’un bon choix si vous utilisez des données de télémétrie d’appareil pour donner vie à 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 dans vos données de télémétrie d’appareil diffère de l’ID de 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 de jumeau et la conserver 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 Azure Data Explorer pour les mises à jour des propriétés de jumeau.

TimeStamp SourceTimeStamp TwinId ModelId Name Value RelationshipTarget RelationshipID
01-02-2021 17:24 2021-02-01 17:11 ConfRoomTempSensor dtmi:com:example:TemperatureSensor;1 température 301.0

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