Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
L’historique des données est une fonctionnalité d’intégration d’Azure Digital Twins. Il vous permet de connecter une instance Azure Digital Twins à un cluster Azure Data Explorer afin que les mises à jour de graphiques soient automatiquement historisées vers Azure Data Explorer. Ces mises à jour historisées incluent les mises à jour des propriétés de jumeau, les événements de cycle de vie de jumeau, et les événements de cycle de vie de relation.
Une fois que les mises à jour de graphe sont historisées vers Azure Data Explorer, vous pouvez exécuter des requêtes conjointes à l’aide du plug-in Azure Digital Twins pour Azure Data Explorer pour raisonner entre les jumeaux numériques, leurs relations et les données de série chronologique. Cela peut être utilisé pour revenir en arrière à l’heure sur l’état du graphique utilisé ou pour obtenir des insights sur le comportement des environnements modélisés. Vous pouvez également utiliser ces requêtes pour alimenter des tableaux de bord opérationnels, enrichir des applications web 2D et 3D, et générer des expériences de réalité augmentée/mixte immersives pour transmettre l’état actuel et historique des ressources, des processus et des personnes modélisées dans Azure Digital Twins.
Pour plus d’informations sur l’historique des données, notamment une démonstration rapide, regardez la vidéo d’affichage IoT suivante :
Les messages émis par l’historique des données sont mesurés sous la dimension de tarification des messages.
Conditions préalables : Ressources et autorisations
L’historique des données nécessite les ressources suivantes :
- Instance Azure Digital Twins, avec une identité managée affectée par le système activée.
- Espace de noms Event Hubs contenant un hub d’événements.
- Cluster Azure Data Explorer contenant une base de données. Le cluster doit avoir un accès réseau public activé.
Ces ressources sont connectées au flux suivant :
Lorsque le graphe de jumeau numérique est mis à jour, les informations transitent par le hub d’événements dans le cluster Azure Data Explorer cible, où Azure Data Explorer stocke les données sous forme d’enregistrement horodaté dans la table correspondante.
Lorsque vous utilisez l’historique des données, il est recommandé d’utiliser la version 2023-01-31 ou ultérieure des API. Avec la version 2022-05-31, seules les propriétés de jumeau (pas les événements de cycle de vie des jumeaux ou de cycle de vie des relations) peuvent être historisées. Avec les versions antérieures, l’historique des données n’est pas disponible.
Autorisations requises
Pour configurer une connexion d’historique des données, votre instance Azure Digital Twins doit disposer des autorisations suivantes pour accéder aux ressources Event Hubs et Azure Data Explorer. Ces rôles permettent à Azure Digital Twins de configurer le hub d’événements et la base de données Azure Data Explorer en votre nom (par exemple, la création d’une table dans la base de données). Ces autorisations peuvent éventuellement être supprimées une fois l’historique des données configuré.
- Ressource Event Hubs : Propriétaire des données Azure Event Hubs
- Cluster Azure Data Explorer : Contributeur (limité à l’ensemble du cluster ou à une base de données spécifique)
- Attribution d’un principal de base de données Azure Data Explorer : Administrateur (limité à la base de données en cours d’utilisation)
Par la suite, votre instance Azure Digital Twins doit disposer de l’autorisation suivante sur la ressource Event Hubs pendant que l’historique des données est utilisé : Expéditeur de données Azure Event Hubs (vous pouvez également choisir de conserver le propriétaire des données Azure Event Hubs à partir de la configuration de l’historique des données).
Ces autorisations peuvent être attribuées à l’aide d’Azure CLI ou du portail Azure.
Si vous souhaitez restreindre l’accès réseau aux ressources impliquées dans l’historique des données (votre instance Azure Digital Twins, event hub ou cluster Azure Data Explorer), vous devez définir ces restrictions après avoir configuré la connexion d’historique des données. Pour plus d’informations sur ce processus, consultez Restreindre l’accès réseau aux ressources d’historique des données.
Créer et gérer la connexion d’historique des données
Cette section contient des informations sur la création, la mise à jour et la suppression d’une connexion d’historique des données.
Créer une connexion d’historique des données
Une fois toutes les ressources et autorisations configurées, vous pouvez utiliser Azure CLI, le portail Azure ou le Kit de développement logiciel (SDK) Azure Digital Twins pour créer la connexion d’historique des données entre elles. Le jeu de commandes CLI est az dt data-history.
La commande crée toujours une table pour les événements de propriété de jumeau historisés, qui peuvent utiliser le nom par défaut ou un nom personnalisé que vous fournissez. Les suppressions de propriétés de jumeau peuvent être incluses dans cette table. Vous pouvez également fournir des noms de tables pour les événements de cycle de vie de relation et les événements de cycle de vie de jumeau, et la commande crée des tables avec ces noms pour historiser ces types d’événements.
Pour obtenir des instructions pas à pas sur la configuration d’une connexion d’historique des données, consultez Créer une connexion d’historique des données.
Historique de plusieurs instances Azure Digital Twins
Si vous le souhaitez, vous pouvez avoir plusieurs instances Azure Digital Twins historiser les mises à jour du même cluster Azure Data Explorer.
Chaque instance Azure Digital Twins aura sa propre connexion pour l'historique des données en ciblant le même cluster Azure Data Explorer. Dans le cluster, les instances peuvent envoyer leurs données de jumeau au choix à...
- un ensemble distinct de tables dans le cluster Azure Data Explorer.
-
le même ensemble de tables dans le cluster Azure Data Explorer. Pour ce faire, spécifiez les mêmes noms de tables Azure Data Explorer au moment de la création des connexions d’historique des données. Dans les schémas de la table d’historique des données, la
ServiceIdcolonne de chaque table contiendra l’URL de l’instance Azure Digital Twins source. Vous pouvez donc utiliser ce champ pour résoudre l’instance Azure Digital Twins émise chaque enregistrement dans des tables partagées.
Mettre à jour une connexion d’historique des données axée uniquement sur les propriétés
Avant février 2023, la fonctionnalité d’historique des données ne met à jour que les propriétés de jumeau historisées. Si vous disposez d’une connexion d’historique des données limitée aux propriétés de cette période, vous pouvez la mettre à jour pour historiser toutes les modifications du graphe vers Azure Data Explorer (y compris les propriétés de jumeau, les événements de cycle de vie de jumeau, et les événements de cycle de vie de relation).
Cela nécessite la création de tables dans votre cluster Azure Data Explorer pour les nouveaux types de mises à jour historisées (événements de cycle de vie des jumeaux et événements de cycle de vie des relations). Pour les événements de propriétés jumelles, vous pouvez décider si vous souhaitez que la nouvelle connexion continue d'utiliser la même table que votre connexion d'historique de données d'origine pour stocker les mises à jour des propriétés jumelles dans le futur, ou si vous préférez que la nouvelle connexion utilise un tout nouvel ensemble de tables. Ensuite, suivez les instructions ci-dessous pour votre préférence.
Si vous souhaitez continuer à utiliser votre table existante pour les mises à jour des propriétés de jumeau : Utilisez les instructions de Créer une connexion d’historique des données pour créer une nouvelle connexion d’historique des données avec les nouvelles fonctionnalités. Le nom de la connexion d’historique des données peut être identique au nom original, ou différent. Utilisez les options de paramètre pour définir de nouveaux noms pour les deux nouvelles tables de types d’événements, et pour transmettre le nom de la table d’origine pour la table de mise à jour des propriétés jumelles. La nouvelle connexion remplacera l’ancienne et continuera à utiliser la table d’origine pour les futures mises à jour de propriétés de jumeau historisées.
Si vous souhaitez utiliser toutes les nouvelles tables : Tout d’abord, supprimez votre connexion d’historique des données d’origine. Ensuite, utilisez les instructions de créer une connexion d’historique des données pour créer une connexion d’historique des données avec les nouvelles fonctionnalités. Le nom de la connexion d’historique des données peut être identique au nom original, ou différent. Utilisez les options de paramètre pour fournir de nouveaux noms pour les trois tables de types d’événements.
Supprimer une connexion à l’historique des données
Vous pouvez utiliser les API et sdk Azure CLI, le portail Azure ou Azure Digital Twins pour supprimer une connexion d’historique des données. La commande CLI est az dt data-history connection delete.
La suppression d’une connexion offre également la possibilité de nettoyer les ressources associées à la connexion d’historique des données (pour la commande CLI, le paramètre facultatif à ajouter est --clean true). Si vous utilisez cette option, la commande supprime les ressources dans Azure Data Explorer utilisées pour lier votre cluster à votre hub d’événements, y compris les connexions de données pour la base de données et les mappages d’ingestion associés à votre table. L’option « Nettoyer les ressources » ne supprime pas le hub d’événements et le cluster Azure Data Explorer utilisés pour la connexion d’historique des données.
Le nettoyage est une tentative optimale et nécessite que le compte exécutant la commande dispose d’une autorisation de suppression pour ces ressources.
Remarque
Si vous avez plusieurs connexions d’historique des données qui partagent le même hub d’événements ou le même cluster Azure Data Explorer, l’option « nettoyer les ressources » lors de la suppression de l’une de ces connexions peut perturber vos autres connexions d’historique des données qui s’appuient sur ces ressources.
Types de données et schémas
L'historique des données enregistre l'historique de trois types d'événements de votre instance Azure Digital Twins dans Azure Data Explorer : événements de cycle de vie des relations, événements de cycle de vie des jumeaux et mises à jour des propriétés du jumeau (qui peuvent éventuellement inclure des suppressions de propriétés du jumeau). Chacun de ces types d’événements est stocké dans sa propre table à l’intérieur de la base de données Azure Data Explorer, ce qui signifie que l’historique des données conserve trois tables au total. Vous pouvez spécifier des noms personnalisés pour les tables lorsque vous configurez la connexion d’historique des données.
Le reste de cette section décrit en détail les trois tables Azure Data Explorer, y compris le schéma de données de chaque table.
Mises à jour de propriétés de jumeau
La table Azure Data Explorer pour les mises à jour de propriétés de jumeau a un nom par défaut de AdtPropertyEvents. Vous pouvez conserver le nom par défaut lorsque vous créez la connexion ou spécifiez un nom de table personnalisé.
Les données de séries chronologiques pour les mises à jour des propriétés jumelles sont stockées avec le schéma suivant :
| Caractéristique | Type | Descriptif |
|---|---|---|
TimeStamp |
Date et heure | Date/heure du traitement du message de mise à jour de propriété par Azure Digital Twins. Ce champ est défini par le système et n’est pas accessible en écriture par les utilisateurs. |
SourceTimeStamp |
Date et heure | Propriété facultative accessible en écriture qui représente la date et l’heure auxquelles la mise à jour de la propriété a été observée. Cette propriété peut uniquement être écrite à l’aide de la version 2022-05-31 des API/SDK Azure Digital Twins et sa valeur doit respecter le format ISO 8601 de date et d’heure. Pour plus d’informations sur la mise à jour de cette propriété, consultez Mettre à jour le sourceTime d’une propriété. |
ServiceId |
Chaîne | ID d’instance de service du service Azure IoT journalisant l’enregistrement |
Id |
Chaîne | ID du jumeau |
ModelId |
Chaîne | ID de modèle DTDL (DTMI) |
Key |
Chaîne | Nom de la propriété mise à jour |
Value |
Dynamique | Valeur de la propriété mise à jour |
RelationshipId |
Chaîne | Lorsqu’une propriété définie sur une relation (par opposition aux jumeaux ou aux appareils) est mise à jour, ce champ est rempli avec l’ID de la relation. Lorsqu’une propriété de jumeau est mise à jour, ce champ est vide. |
RelationshipTarget |
Chaîne | Lorsqu’une propriété définie sur une relation (par opposition aux jumeaux ou aux appareils) est mise à jour, ce champ est rempli avec l’ID de jumeau du jumeau ciblé par la relation. Lorsqu’une propriété de jumeau est mise à jour, ce champ est vide. |
Action |
Chaîne | Cette colonne existe uniquement si vous choisissez d’historiser les événements de suppression de propriété. Dans ce cas, cette colonne contient le type d'événement de propriété jumelle (mise à jour ou suppression) |
Vous trouverez ci-dessous un exemple de table comprenant les mises à jour des propriétés d’un jumeau stockées dans Azure Data Explorer.
TimeStamp |
SourceTimeStamp |
ServiceId |
Id |
ModelId |
Key |
Value |
RelationshipTarget |
RelationshipID |
|---|---|---|---|---|---|---|---|---|
| 2022-12-15 20:23:29.8697482 | 2022-12-15 20:22:14.3854859 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Output | 130 | ||
| 2022-12-15 20:23:39.3235925 | 2022-12-15 20:22:26.5837559 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Output | 140 | ||
| 2022-12-15 20:23:47.078367 | 2022-12-15 20:22:34.9375957 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Output | 130 | ||
| 2022-12-15 20:23:57.3794198 | 2022-12-15 20:22:50.1028562 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Output | 123 |
Représentation de propriétés avec plusieurs champs
Vous pouvez avoir besoin de stocker une propriété avec plusieurs champs. Ces propriétés sont représentées avec un objet JSON dans l’attribut Value du schéma.
Par exemple, si vous représentez une propriété avec trois champs pour roll, pitch et yaw, l’historique des données stockera l’objet JSON suivant en tant que Value : {"roll": 20, "pitch": 15, "yaw": 45}.
Événements de cycle de vie de jumeau
La table Azure Data Explorer pour les événements de cycle de vie de jumeau a un nom personnalisé que vous spécifiez lors de la création de la connexion d’historique des données.
Les données des séries chronologiques pour les événements de cycle de vie de jumeau sont stockées selon le schéma suivant :
| Caractéristique | Type | Descriptif |
|---|---|---|
TwinId |
Chaîne | ID du jumeau |
Action |
Chaîne | Type d'événement de cycle de vie de jumeau (création ou suppression) |
TimeStamp |
Date et heure | Date/heure du traitement de l’événement de cycle de vie de jumeau par Azure Digital Twins. Ce champ est défini par le système et n’est pas accessible en écriture par les utilisateurs. |
ServiceId |
Chaîne | ID d’instance de service du service Azure IoT journalisant l’enregistrement |
ModelId |
Chaîne | ID de modèle DTDL (DTMI) |
Vous trouverez ci-dessous un exemple de tableau de mises à jour de cycle de vie des jumeaux stockées dans Azure Data Explorer.
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| PasteurizationMachine_A01 | Créer | 2022-12-15 07:14:12.4160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| Machine de Pasteurisation_A02 | Créer | 2022-12-15 07:14:12.4210 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| SaltMachine_C0 | Créer | 2022-12-15 07:14:12.5480 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:SaltMachine;1 |
| Machine de Pasteurisation_A02 | Supprimer | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
Événements de cycle de vie des relations
La table Azure Data Explorer pour les événements de cycle de vie des relations a un nom personnalisé que vous spécifiez lors de la création de la connexion d’historique des données.
Les données de série chronologique pour les événements de cycle de vie des relations sont stockées avec le schéma suivant :
| Caractéristique | Type | Descriptif |
|---|---|---|
RelationshipId |
Chaîne | ID de relation. Ce champ est défini par le système et n’est pas accessible en écriture par les utilisateurs. |
Name |
Chaîne | Nom de la relation |
Action |
Type d’événement de cycle de vie de relation (créer ou supprimer) | |
TimeStamp |
Date et heure | La date/heure de l’événement de cycle de vie de relation a été traité par Azure Digital Twins. Ce champ est défini par le système et n’est pas accessible en écriture par les utilisateurs. |
ServiceId |
ID d’instance de service du service Azure IoT journalisant l’enregistrement | |
Source |
ID du jumeau source. Il s’agit de l’ID du jumeau à l’origine de la relation. | |
Target |
ID du jumeau cible. Il s’agit de l’ID du jumeau destinataire de la relation. |
Vous trouverez ci-dessous un exemple de tableau des mises à jour du cycle de vie des relations stockées dans Azure Data Explorer.
RelationshipId |
Name |
Action |
TimeStamp |
ServiceId |
Source |
Target |
|---|---|---|---|---|---|---|
| PasteurizationMachine_A01_feeds_Relationship0 | feeds | Créer | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | feeds | Créer | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | Machine de Pasteurisation_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | feeds | Créer | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | contains | Supprimer | 2022-12-15 07:16:13.1780 | dairyadtinstance.api.wcus.digitaltwins.azure.net | OsloFactory | SaltMachine_C0 |
Latence d’ingestion de bout en bout
L’historique des données Azure Digital Twins repose sur le mécanisme d’ingestion existant fourni par Azure Data Explorer. Azure Digital Twins garantit que les événements de mise à jour de graphe sont mis à la disposition d’Azure Data Explorer en moins de deux secondes. Une latence supplémentaire peut être introduite par l’Explorateur de données Azure qui ingère les données.
Il existe deux méthodes dans Azure Data Explorer pour l’ingestion de données : l’ingestion par lots et l’ingestionde streaming. Vous pouvez configurer ces méthodes d’ingestion pour des tables individuelles en fonction de vos besoins et du scénario d’ingestion de données spécifique.
L'ingestion en streaming a la latence la plus faible. Toutefois, en raison de la surcharge de traitement, ce mode ne doit être utilisé que si moins de 4 Go de données sont ingérées toutes les heures. L’ingestion par lot fonctionne mieux si des taux de données d’ingestion élevés sont attendus. Azure Data Explorer utilise l’ingestion par lot par défaut. Le tableau suivant récapitule la latence de bout en bout attendue :
| Configuration d’Azure Data Explorer | Latence de bout en bout attendue | Débit de données recommandé |
|---|---|---|
| Ingestion de streaming | <12 secondes (<3 secondes typique) | <4 Go/h |
| Ingestion par lots | Varie (12 secondes à 15 m, selon la configuration) | >4 Go/h |
Le reste de cette section contient des détails pour activer chaque type d’ingestion.
Ingestion par lots (par défaut)
Si ce n’est pas le cas, Azure Data Explorer utilise l’ingestion par lots. Les paramètres par défaut peuvent entraîner la disponibilité des données pour une requête de 5 à 10 minutes seulement après l’exécution d’une mise à jour d’un jumeau numérique. La stratégie d’ingestion peut être modifiée, de sorte que le traitement par lots se produit au maximum toutes les 10 secondes (au minimum ; ou 15 minutes au maximum). Pour modifier la stratégie d’ingestion, la commande suivante doit être émise dans la vue de requête Azure Data Explorer :
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
Vérifiez que <table_name> est remplacé par le nom de la table qui a été configurée pour vous. MaximumBatchingTimeSpan doit être défini sur l’intervalle de traitement par lots préféré. La politique peut prendre 5 à 10 minutes pour entrer en vigueur. Pour plus d’informations sur l’ingestion par lots, consultez Commande de gestion des stratégies IngestionBatching Kusto.
Ingestion de streaming
L’activation de l’ingestion de streaming est un processus en 2 étapes :
- Activez l’ingestion par streaming pour votre cluster. Cette action ne doit être effectuée qu’une seule fois. (Avertissement : Cela aura un effet sur la quantité de stockage disponible pour le cache à chaud et peut introduire des limitations supplémentaires). Pour obtenir des instructions, consultez Configurer l’ingestion de streaming sur votre cluster Azure Data Explorer.
- Ajoutez une stratégie d’ingestion par streaming pour la table souhaitée. Vous pouvez en savoir plus sur l’activation de l’ingestion de streaming pour votre cluster dans la documentation Azure Data Explorer : commande de gestion des stratégies Kusto IngestionBatching.
Pour activer l’ingestion de streaming pour votre table d’historique des données Azure Digital Twins, la commande suivante doit être émise dans le volet de requête Azure Data Explorer :
.alter table <table_name> policy streamingingestion enable
Vérifiez que <table_name> est remplacé par le nom de la table qui a été configurée pour vous. La politique peut prendre 5 à 10 minutes pour entrer en vigueur.
Visualiser les propriétés historisées
Azure Digital Twins Explorer, outil de développement permettant de visualiser et d’interagir avec les données Azure Digital Twins, offre une fonctionnalité d’explorateur d’historique des données pour afficher les propriétés historisées au fil du temps dans un graphique ou une table. Cette fonctionnalité est également disponible dans 3D Scenes Studio, un environnement 3D immersif pour donner à Azure Digital Twins le contexte visuel des ressources 3D.
Pour plus d’informations sur l’utilisation de l’Explorateur d’historique des données, consultez Valider et explorer les propriétés historisées.
Remarque
Si vous rencontrez des problèmes lors de la sélection d’une propriété dans l’expérience de l’Explorateur d’historique des données visuels, cela peut signifier qu’il existe une erreur dans un modèle dans votre instance. Par exemple, avoir des valeurs d’énumération non uniques dans les attributs d’un modèle interrompt cette fonctionnalité de visualisation. Si cela se produit, passez en revue vos définitions de modèle et vérifiez que toutes les propriétés sont valides.
Étapes suivantes
Une fois que les données de jumeau ont été historisées dans Azure Data Explorer, vous pouvez utiliser le plug-in de requête Azure Digital Twins pour Azure Data Explorer pour exécuter des requêtes sur les données. En savoir plus sur le plug-in ici : interrogation avec le plug-in Azure Data Explorer.
Vous pouvez également approfondir l’historique des données avec des instructions de création et un exemple de scénario : Créer une connexion d’historique des données.