Azure Digital Twins-datahistorik (med Azure Data Explorer)
Datahistorik är en integreringsfunktion i Azure Digital Twins. Det gör att du kan ansluta en Azure Digital Twins-instans till ett Azure Data Explorer-kluster så att grafuppdateringar automatiskt historiseras till Azure Data Explorer. Dessa historiserade uppdateringar omfattar uppdateringar av tvillingegenskap, händelser i tvillinglivscykeln och relationslivscykelhändelser.
När grafuppdateringar har historiserats till Azure Data Explorer kan du köra gemensamma frågor med hjälp av Azure Digital Twins-plugin-programmet för Azure Data Explorer för att resonera mellan digitala tvillingar, deras relationer och tidsseriedata. Detta kan användas för att se tillbaka i tiden på vilket tillstånd diagrammet brukade vara, eller för att få insikter om beteendet för modellerade miljöer. Du kan också använda dessa frågor för att driva operativa instrumentpaneler, berika 2D- och 3D-webbappar och driva engagerande upplevelser med förhöjd/mixad verklighet för att förmedla det aktuella och historiska tillståndet för tillgångar, processer och personer som modellerats i Azure Digital Twins.
Om du vill ha mer av en introduktion till datahistorik, inklusive en snabb demo, kan du titta på följande IoT-showvideo:
Meddelanden som genereras av datahistorik mäts under prisdimensionen Meddelande.
Förutsättningar: Resurser och behörigheter
Datahistorik kräver följande resurser:
- Azure Digital Twins-instans med en systemtilldelad hanterad identitet aktiverad.
- Event Hubs-namnrymd som innehåller en händelsehubb.
- Azure Data Explorer-kluster som innehåller en databas. Klustret måste ha åtkomst till det offentliga nätverket aktiverat.
Dessa resurser är anslutna till följande flöde:
När diagrammet för den digitala tvillingen uppdateras skickas informationen genom händelsehubben till Azure Data Explorer-målklustret, där Azure Data Explorer lagrar data som en tidsstämpelpost i motsvarande tabell.
När du arbetar med datahistorik rekommenderar vi att du använder 2023-01-31-versionen eller senare av API:erna. Med 2022-05-31-versionen kan endast tvillingegenskaper (inte tvillinglivscykel eller relationslivscykelhändelser) historiseras. Med tidigare versioner är datahistoriken inte tillgänglig.
Behörigheter som krävs
För att kunna konfigurera en datahistorikanslutning måste din Azure Digital Twins-instans ha följande behörigheter för att få åtkomst till Resurser för Event Hubs och Azure Data Explorer. Med de här rollerna kan Azure Digital Twins konfigurera händelsehubben och Azure Data Explorer-databasen åt dig (till exempel att skapa en tabell i databasen). Du kan också ta bort dessa behörigheter när datahistoriken har konfigurerats.
- Event Hubs-resurs: Azure Event Hubs-dataägare
- Azure Data Explorer-kluster: Deltagare (begränsad till hela klustret eller en specifik databas)
- Huvudtilldelning för Azure Data Explorer-databasen: Administratör (begränsad till den databas som används)
Senare måste din Azure Digital Twins-instans ha följande behörighet för Event Hubs-resursen medan datahistorik används: Azure Event Hubs Data Sender (du kan också välja att i stället behålla Azure Event Hubs Data Owner från datahistorikkonfigurationen).
Dessa behörigheter kan tilldelas med hjälp av Azure CLI eller Azure-portalen.
Om du vill begränsa nätverksåtkomsten till de resurser som ingår i datahistoriken (din Azure Digital Twins-instans, händelsehubb eller Azure Data Explorer-kluster) bör du ange dessa begränsningar när du har konfigurerat anslutningen till datahistoriken. Mer information om den här processen finns i Begränsa nätverksåtkomst till datahistorikresurser.
Skapa och hantera anslutning till datahistorik
Det här avsnittet innehåller information om hur du skapar, uppdaterar och tar bort en datahistorikanslutning.
Skapa en datahistorikanslutning
När alla resurser och behörigheter har konfigurerats kan du använda Azure CLI, Azure Portal eller Azure Digital Twins SDK för att skapa datahistorikanslutningen mellan dem. CLI-kommandouppsättningen är az dt data-history.
Kommandot skapar alltid en tabell för historiserade tvillingegenskapshändelser, som kan använda standardnamnet eller ett anpassat namn som du anger. Du kan också ta bort tvillingegenskapen i den här tabellen. Du kan också ange tabellnamn för relationslivscykelhändelser och tvillinglivscykelhändelser, och kommandot skapar tabeller med dessa namn för att historisera dessa händelsetyper.
Stegvisa instruktioner för hur du konfigurerar en datahistorikanslutning finns i Skapa en datahistorikanslutning.
Historik från flera Azure Digital Twins-instanser
Om du vill kan du ha flera Azure Digital Twins-instanser som historiserar uppdateringar till samma Azure Data Explorer-kluster.
Varje Azure Digital Twins-instans har en egen datahistorikanslutning som riktar sig till samma Azure Data Explorer-kluster. I klustret kan instanser skicka sina tvillingdata till antingen...
- en separat uppsättning tabeller i Azure Data Explorer-klustret.
- samma uppsättning tabeller i Azure Data Explorer-klustret. Det gör du genom att ange samma Azure Data Explorer-tabellnamn när du skapar datahistorikanslutningarna. I datahistoriktabellscheman
ServiceIdinnehåller kolumnen i varje tabell URL:en för Azure Digital Twins-källinstansen, så du kan använda det här fältet för att lösa vilken Azure Digital Twins-instans som genererat varje post i delade tabeller.
Uppdatera en datahistorikanslutning endast för egenskaper
Före februari 2023 har datahistoriken endast historiserade tvillingegenskapsuppdateringar. Om du har en datahistorikanslutning endast för egenskaper från den tiden kan du uppdatera den till att historisera alla grafuppdateringar till Azure Data Explorer (inklusive tvillingegenskaper, händelser i tvillinglivscykeln och relationslivscykelhändelser).
Detta kräver att du skapar nya tabeller i Azure Data Explorer-klustret för de nya typerna av historiserade uppdateringar (dubbla livscykelhändelser och relationslivscykelhändelser). För tvillingegenskapshändelser kan du bestämma om du vill att den nya anslutningen ska fortsätta använda samma tabell från den ursprungliga datahistorikanslutningen för att lagra uppdateringar av tvillingegenskaper framöver, eller om du vill att den nya anslutningen ska använda en helt ny uppsättning tabeller. Följ sedan anvisningarna nedan för dina önskemål.
Om du vill fortsätta att använda din befintliga tabell för uppdateringar av tvillingegenskaper: Använd anvisningarna i Skapa en datahistorikanslutning för att skapa en ny datahistorikanslutning med de nya funktionerna. Anslutningsnamnet för datahistorik kan vara samma som det ursprungliga eller ett annat namn. Använd parameteralternativen för att ange nya namn för de två nya tabellerna för händelsetyp och skicka det ursprungliga tabellnamnet för tabellen för uppdateringstabellen för tvillingegenskapen. Den nya anslutningen åsidosätter den gamla och fortsätter att använda den ursprungliga tabellen för framtida historiserade tvillingegenskapsuppdateringar.
Om du vill använda alla nya tabeller: Ta först bort den ursprungliga datahistorikanslutningen. Använd sedan anvisningarna i Skapa en datahistorikanslutning för att skapa en ny datahistorikanslutning med de nya funktionerna. Anslutningsnamnet för datahistorik kan vara samma som det ursprungliga eller ett annat namn. Använd parameteralternativen för att ange nya namn för alla tre tabeller av händelsetyp.
Ta bort en datahistorikanslutning
Du kan använda API:er och SDK:er för Azure CLI, Azure-portalen eller Azure Digital Twins för att ta bort en datahistorikanslutning. CLI-kommandot är az dt data history connection delete.
Om du tar bort en anslutning kan du även rensa resurser som är associerade med anslutningen till datahistoriken (för CLI-kommandot är --clean trueden valfria parametern att lägga till ). Om du använder det här alternativet tar kommandot bort de resurser i Azure Data Explorer som används för att länka klustret till din händelsehubb, inklusive dataanslutningar för databasen och inmatningsmappningar som är associerade med tabellen. Alternativet "rensa resurser" tar inte bort den faktiska händelsehubben och Azure Data Explorer-klustret som används för datahistorikanslutningen.
Rensningen är ett bästa försök och kräver att kontot som kör kommandot har borttagningsbehörighet för dessa resurser.
Kommentar
Om du har flera datahistorikanslutningar som delar samma händelsehubb eller Azure Data Explorer-kluster kan det störa dina andra datahistorikanslutningar som är beroende av dessa resurser genom att använda alternativet "rensa resurser" när du tar bort en av dessa anslutningar.
Datatyper och scheman
Datahistorik historiserar tre typer av händelser från din Azure Digital Twins-instans till Azure Data Explorer: relationslivscykelhändelser, dubbla livscykelhändelser och uppdateringar av tvillingegenskap (som kan inkludera borttagningar av tvillingegenskaper). Var och en av dessa händelsetyper lagras i en egen tabell i Azure Data Explorer-databasen, vilket innebär att datahistoriken behåller tre tabeller totalt. Du kan ange anpassade namn för tabellerna när du konfigurerar datahistorikanslutningen.
I resten av det här avsnittet beskrivs de tre Azure Data Explorer-tabellerna i detalj, inklusive dataschemat för varje tabell.
Uppdateringar av tvillingegenskap
Azure Data Explorer-tabellen för tvillingegenskapsuppdateringar har standardnamnet AdtPropertyEvents. Du kan lämna standardnamnet när du skapar anslutningen eller ange ett anpassat tabellnamn.
Tidsseriedata för tvillingegenskapsuppdateringar lagras med följande schema:
| Attribut | Typ | Beskrivning |
|---|---|---|
TimeStamp |
Datum/tid | Datum/tid då egenskapsuppdateringsmeddelandet bearbetades av Azure Digital Twins. Det här fältet anges av systemet och kan inte skrivas av användarna. |
SourceTimeStamp |
Datum/tid | En valfri, skrivbar egenskap som representerar tidsstämpeln när egenskapsuppdateringen observerades i verkligheten. Den här egenskapen kan bara skrivas med 2022-05-31-versionen av Azure Digital Twins API:er/SDK:er och värdet måste uppfylla ISO 8601-datum- och tidsformatet. Mer information om hur du uppdaterar den här egenskapen finns i Uppdatera en egenskaps sourceTime. |
ServiceId |
String | Tjänstinstans-ID för Azure IoT-tjänsten som loggar posten |
Id |
String | Tvilling-ID:t |
ModelId |
String | DTDL-modell-ID (DTMI) |
Key |
String | Namnet på den uppdaterade egenskapen |
Value |
Dynamisk | Värdet för den uppdaterade egenskapen |
RelationshipId |
String | När en egenskap som definierats för en relation (till skillnad från tvillingar eller enheter) uppdateras fylls fältet i med ID:t för relationen. När en tvillingegenskap uppdateras är det här fältet tomt. |
RelationshipTarget |
String | När en egenskap som definierats för en relation (till skillnad från tvillingar eller enheter) uppdateras fylls det här fältet i med tvilling-ID:t för tvillingen som relationen riktar sig mot. När en tvillingegenskap uppdateras är det här fältet tomt. |
Action |
String | Den här kolumnen finns bara om du väljer att historisera egenskapsborttagningshändelser. I så fall innehåller den här kolumnen typen av tvillingegenskapshändelse (uppdatera eller ta bort) |
Nedan visas en exempeltabell med uppdateringar av tvillingegenskap som lagras i 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 |
Representerar egenskaper med flera fält
Du kan behöva lagra en egenskap med flera fält. Dessa egenskaper representeras med ett JSON-objekt i Value schemats attribut.
Om du till exempel representerar en egenskap med tre fält för roll, pitch och yaw lagrar datahistoriken följande JSON-objekt som Value: {"roll": 20, "pitch": 15, "yaw": 45}.
Händelser för tvillinglivscykel
Azure Data Explorer-tabellen för tvillinglivscykelhändelser har ett anpassat namn som du anger när du skapar datahistorikanslutningen.
Tidsseriedata för tvillinglivscykelhändelser lagras med följande schema:
| Attribut | Typ | Description |
|---|---|---|
TwinId |
String | Tvilling-ID:t |
Action |
String | Typen av tvillinglivscykelhändelse (skapa eller ta bort) |
TimeStamp |
Datum/tid | Datum/tid då tvillingens livscykelhändelse bearbetades av Azure Digital Twins. Det här fältet anges av systemet och kan inte skrivas av användarna. |
ServiceId |
String | Tjänstinstans-ID för Azure IoT-tjänsten som loggar posten |
ModelId |
String | DTDL-modell-ID (DTMI) |
Nedan visas en exempeltabell med uppdateringar av tvillinglivscykeln som lagras i Azure Data Explorer.
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| PasteurizationMachine_A01 | Skapa | 2022-12-15 07:14:12.4160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| PasteurizationMachine_A02 | Skapa | 2022-12-15 07:14:12.4210 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| SaltMachine_C0 | Skapa | 2022-12-15 07:14:12.5480 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:SaltMachine;1 |
| PasteurizationMachine_A02 | Delete | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
Händelser i relationslivscykeln
Azure Data Explorer-tabellen för relationslivscykelhändelser har ett anpassat namn som du anger när du skapar datahistorikanslutningen.
Tidsseriedata för relationslivscykelhändelser lagras med följande schema:
| Attribut | Typ | Description |
|---|---|---|
RelationshipId |
String | Relations-ID:t. Det här fältet anges av systemet och kan inte skrivas av användarna. |
Name |
String | Namnet på relationen |
Action |
Typen av relationslivscykelhändelse (skapa eller ta bort) | |
TimeStamp |
Datum/tid | Datum/tid då relationslivscykelhändelsen bearbetades av Azure Digital Twins. Det här fältet anges av systemet och kan inte skrivas av användarna. |
ServiceId |
Tjänstinstans-ID för Azure IoT-tjänsten som loggar posten | |
Source |
Källtvillingens ID. Det här är ID:t för tvillingen där relationen kommer. | |
Target |
Måltvillingens ID. Det här är ID:t för tvillingen där relationen kommer. |
Nedan visas en exempeltabell med uppdateringar av relationslivscykeln som lagras i Azure Data Explorer.
RelationshipId |
Name |
Action |
TimeStamp |
ServiceId |
Source |
Target |
|---|---|---|---|---|---|---|
| PasteurizationMachine_A01_feeds_Relationship0 | Feeds | Skapa | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | Feeds | Skapa | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | Feeds | Skapa | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | innehåller | Delete | 2022-12-15 07:16:13.1780 | dairyadtinstance.api.wcus.digitaltwins.azure.net | OsloFactory | SaltMachine_C0 |
Svarstid för inmatning från slutpunkt till slutpunkt
Azure Digital Twins-datahistorik bygger på den befintliga inmatningsmekanismen som tillhandahålls av Azure Data Explorer. Azure Digital Twins ser till att diagramuppdateringshändelser görs tillgängliga för Azure Data Explorer inom mindre än två sekunder. Extra svarstid kan introduceras genom att Azure Data Explorer matar in data.
Det finns två metoder i Azure Data Explorer för att mata in data: batchinmatning och strömmande inmatning. Du kan konfigurera dessa inmatningsmetoder för enskilda tabeller enligt dina behov och det specifika datainmatningsscenariot.
Inmatning av direktuppspelning har den lägsta svarstiden. Men på grund av bearbetningskostnader bör det här läget endast användas om mindre än 4 GB data matas in varje timme. Batchinmatning fungerar bäst om höga datahastigheter för inmatning förväntas. Azure Data Explorer använder batchinmatning som standard. I följande tabell sammanfattas den förväntade svarstiden från slutpunkt till slutpunkt:
| Azure Data Explorer-konfiguration | Förväntad svarstid från slutpunkt till slutpunkt | Rekommenderad datahastighet |
|---|---|---|
| Strömningsinmatning | <12 sek (<3 sek typiskt) | <4 GB/tim |
| Batchinmatning | Varierar (12 sek-15 m, beroende på konfiguration) | >4 GB/tim |
Resten av det här avsnittet innehåller information om hur du aktiverar varje typ av inmatning.
Batchinmatning (standard)
Om du inte har konfigurerat något annat använder Azure Data Explorer batchinmatning. Standardinställningarna kan leda till att data endast är tillgängliga för frågor 5–10 minuter efter att en uppdatering av en digital tvilling har utförts. Inmatningsprincipen kan ändras, så att batchbearbetningen sker högst var 10:e sekund (minst eller högst 15 minuter). Om du vill ändra inmatningsprincipen måste följande kommando utfärdas i frågevyn Azure Data Explorer:
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
Se till att <table_name> ersätts med namnet på den tabell som har konfigurerats åt dig. MaximumBatchingTimeSpan ska anges till önskat batchintervall. Det kan ta 5–10 minuter innan principen börjar gälla. Du kan läsa mer om batchbearbetning för inmatning på följande länk: Kommandot Kusto IngestionBatching policy management.
Strömningsinmatning
Aktivering av strömmande inmatning är en tvåstegsprocess:
- Aktivera strömningsinmatning för klustret. Den här åtgärden behöver bara utföras en gång. (Varning! Detta påverkar mängden lagringsutrymme som är tillgängligt för frekvent cache och kan medföra extra begränsningar). Anvisningar finns i Konfigurera strömmande inmatning i ditt Azure Data Explorer-kluster.
- Lägg till en princip för strömmande inmatning för den önskade tabellen. Du kan läsa mer om att aktivera strömmande inmatning för klustret i Azure Data Explorer-dokumentationen: Kommandot Kusto IngestionBatching policy management.
Om du vill aktivera strömmande inmatning för din Azure Digital Twins-datahistoriktabell måste följande kommando utfärdas i frågefönstret i Azure Data Explorer:
.alter table <table_name> policy streamingingestion enable
Se till att <table_name> ersätts med namnet på den tabell som har konfigurerats åt dig. Det kan ta 5–10 minuter innan principen börjar gälla.
Visualisera historiserade egenskaper
Azure Digital Twins Explorer, ett utvecklarverktyg för att visualisera och interagera med Azure Digital Twins-data, erbjuder en datahistorikutforskare för att visa historiserade egenskaper över tid i ett diagram eller en tabell. Den här funktionen är också tillgänglig i 3D Scenes Studio, en uppslukande 3D-miljö för att ge Azure Digital Twins den visuella kontexten för 3D-tillgångar.
Mer detaljerad information om hur du använder datahistorikutforskaren finns i Verifiera och utforska historiserade egenskaper.
Kommentar
Om du stöter på problem med att välja en egenskap i utforskarupplevelsen för visuell datahistorik kan det innebära att det finns ett fel i någon modell i din instans. Om du till exempel har icke-unika uppräkningsvärden i attributen för en modell kommer den här visualiseringsfunktionen att brytas. Om detta händer granskar du modelldefinitionerna och kontrollerar att alla egenskaper är giltiga.
Nästa steg
När tvillingdata har historiserats till Azure Data Explorer kan du använda Azure Digital Twins-frågeprogrammet för Azure Data Explorer för att köra frågor över data. Läs mer om plugin-programmet här: Fråga med Plugin-programmet Azure Data Explorer.
Du kan också fördjupa dig i datahistoriken med skapandeinstruktioner och ett exempelscenario: Skapa en datahistorikanslutning.