Historie dat v Azure Digital Twins (ve spojení s Azure Data Explorerem)

Historie dat je funkce integrace služby Azure Digital Twins. Umožňuje připojit instanci Azure Digital Twins ke clusteru Azure Data Exploreru , aby se aktualizace grafu automaticky historizovaly do Azure Data Exploreru. Mezi tyto historizované aktualizace patří aktualizace vlastností dvojčat, události životního cyklu dvojčat a události životního cyklu vztahu.

Jakmile se aktualizace grafu uloží jako historii do Azure Data Explorer, můžete spouštět společné dotazy pomocí modulu plug-in Azure Digital Twins pro Azure Data Explorer k analýze digitálních dvojčat, jejich vztahů a dat časových řad. Dá se použít k tomu, abyste se ohlédli zpět na stav grafu, který byl dříve, nebo abyste získali vhled do chování modelovaných prostředí. Tyto dotazy můžete použít také k výkonu provozních řídicích panelů, obohacení 2D a 3D webových aplikací a řízení imerzivních rozšířených/hybridních prostředí reality k vyjádření aktuálního a historického stavu prostředků, procesů a lidí modelovaných ve službě Azure Digital Twins.

Další informace o úvodu do historie dat, včetně rychlé ukázky, najdete v následujícím videu o IoT:

Zprávy generované historií dat se měří v rámci dimenze Ceny zpráv.

Požadavky: Prostředky a oprávnění

Historie dat vyžaduje následující zdroje informací:

• Instance služby Azure Digital Twins se zapnutou spravovanou identitou systému přiřazenou systémem
• Obor názvů služby Event Hubs obsahující centrum událostí.
• Cluster Azure Data Exploreru obsahující databázi. Cluster musí mít povolený přístup k veřejné síti.

Tyto prostředky jsou připojené k následujícímu toku:

Když se graf digitálního dvojčete aktualizuje, informace procházejí centrem událostí do cílového clusteru Azure Data Exploreru, kde Azure Data Explorer ukládá data jako záznam s časovým razítkem do odpovídající tabulky.

Při práci s historií dat se doporučuje použít rozhraní API verze 2023-01-31 nebo novější. U verze 2022-05-31 je možné historizovat pouze vlastnosti dvojčete (nikoli životní cyklus dvojčete nebo události životního cyklu vztahu). U starších verzí není historie dat dostupná.

Požadovaná oprávnění

Aby bylo možné nastavit připojení historie dat, musí mít vaše instance Služby Azure Digital Twins následující oprávnění pro přístup k prostředkům služby Event Hubs a Azure Data Exploreru. Tyto role umožňují službě Azure Digital Twins nakonfigurovat centrum událostí a databázi Azure Data Exploreru vaším jménem (například vytvoření tabulky v databázi). Tato oprávnění je možné volitelně odebrat po nastavení historie dat.

• Prostředek Event Hubs: Vlastník dat Azure Event Hubs
• Cluster Azure Data Explorer: Přispěvatel (vymezený na celý cluster nebo konkrétní databázi)
• Přiřazení instančního objektu databáze Azure Data Exploreru: Správce (vymezený na použitou databázi)

Později musí mít vaše instance Služby Azure Digital Twins následující oprávnění k prostředku služby Event Hubs, zatímco se používá historie dat: Odesílatel dat služby Azure Event Hubs (můžete se také rozhodnout ponechat vlastníka dat Služby Azure Event Hubs před nastavením historie dat).

Tato oprávnění je možné přiřadit pomocí Azure CLI nebo webu Azure Portal.

Pokud chcete omezit síťový přístup k prostředkům, které jsou součástí historie dat (instance služby Azure Digital Twins, centrum událostí nebo cluster Azure Data Explorer), měli byste tato omezení nastavit po nastavení připojení historie dat. Další informace o tomto procesu naleznete v tématu Omezení síťového přístupu k prostředkům historie dat.

Vytvoření a správa historie připojení dat

Tato část obsahuje informace o vytváření, aktualizaci a odstraňování připojení historických dat.

Vytvořte připojení k historii dat

Jakmile nastavíte všechny prostředky a oprávnění , můžete mezi nimi vytvořit připojení historie dat pomocí Azure CLI, webu Azure Portal nebo sady SDK služby Azure Digital Twins . Sada příkazů rozhraní příkazového řádku je az dt data-history.

Příkaz vždy vytvoří tabulku pro události vlastností historizovaného dvojčete, které můžou použít výchozí název nebo vlastní název, který zadáte. Odstranění vlastností dvojčete lze volitelně zahrnout do této tabulky. Můžete také zadat názvy tabulek pro události životního cyklu relace a události životního cyklu dvojčat a příkaz vytvoří tabulky s těmito názvy pro historizaci těchto typů událostí.

Podrobné pokyny k nastavení připojení historie dat najdete v tématu Vytvoření připojení historie dat.

Historie z více "Azure Digital Twins" instancí

Pokud chcete, můžete mít několik instancí Azure Digital Twins, které historizují aktualizace do stejného clusteru Azure Data Exploreru.

Každá instance Azure Digital Twins bude mít vlastní připojení k historickým datům směřující na stejný cluster Azure Data Exploreru. V rámci clusteru můžou instance odesílat data dvojčete do jednoho ze dvou...

• samostatná sada tabulek v clusteru Azure Data Exploreru.
• stejnou sadu tabulek v clusteru Azure Data Exploreru. Uděláte to tak, že při vytváření připojení historie dat zadáte stejné názvy tabulek Azure Data Exploreru. Ve schématech tabulekServiceId historie dat bude sloupec v každé tabulce obsahovat adresu URL zdrojové instance Služby Azure Digital Twins, takže toto pole můžete použít k vyřešení toho, která instance služby Azure Digital Twins vygenerovala každý záznam ve sdílených tabulkách.

Aktualizace připojení historie dat pouze pro vlastnosti

Před únorem 2023 funkce historie dat historizovala pouze aktualizace vlastností digitálního dvojčete. Pokud máte připojení historie dat pouze pro vlastnosti od té doby, můžete jej aktualizovat tak, aby se všechny aktualizace grafů uchovávaly v Azure Data Exploreru (včetně vlastností digitálních dvojčat, událostí životního cyklu digitálních dvojčat a událostí životního cyklu vztahů).

To bude vyžadovat vytvoření nových tabulek v clusteru Azure Data Exploreru pro nové typy historizovaných aktualizací (události životního cyklu dvojčat a události životního cyklu relací). U událostí vlastností dvojčat můžete rozhodnout, jestli chcete, aby nové připojení nadále používalo stejnou tabulku z původního připojení k historii dat pro ukládání aktualizací vlastností dvojčat v budoucnu, nebo jestli chcete, aby nové připojení používalo zcela novou sadu tabulek. Pak podle následujících pokynů postupujte podle svých preferencí.

Pokud chcete pokračovat v používání stávající tabulky pro aktualizace vlastností dvojčete: Pomocí pokynů v části Vytvoření připojení historie dat vytvořte nové připojení historie dat s novými možnostmi. Název připojení historie dat může být stejný jako původní nebo jiný název. Pomocí možností parametru zadejte nové názvy pro dvě nové tabulky typu události a předáte původní název tabulky pro tabulku aktualizací vlastností dvojčat. Nové připojení přepíše staré a bude nadále používat původní tabulku pro budoucí aktualizace historizované vlastnosti dvojčete.

Pokud chcete použít všechny nové tabulky: Nejprve odstraňte původní připojení historie dat. Potom pomocí pokynů v části Vytvoření připojení historie dat vytvořte nové připojení historie dat s novými možnostmi. Název připojení historie dat může být stejný jako původní nebo jiný název. Pomocí možností parametru můžete zadat nové názvy všech tří tabulek typu událostí.

Smažte připojení historie dat

K odstranění připojení historie dat můžete použít Rozhraní příkazového řádku Azure,Azure Portal nebo rozhraní API služby Azure Digital Twins a sady SDK . Příkaz rozhraní příkazového řádku je az dt data-history connection delete.

Odstranění připojení také umožňuje vyčistit prostředky přidružené k připojení datové historie (pro příkaz v rozhraní příkazového řádku je volitelný parametr, který můžete přidat, --clean true). Pokud použijete tuto možnost, příkaz odstraní prostředky v Azure Data Exploreru, které slouží k propojení clusteru s centrem událostí, včetně datových připojení pro databázi a mapování příjmu dat přidružených k vaší tabulce. Možnost Vyčistit prostředky neodstraní skutečné centrum událostí a cluster Azure Data Explorer použitý pro připojení historie dat.

Vyčištění je pokus o nejlepší úsilí a vyžaduje, aby účet, který spouští příkaz, měl oprávnění k odstranění těchto prostředků.

Poznámka:

Pokud máte více připojení historie dat, která sdílejí stejné centrum událostí nebo cluster Azure Data Exploreru, použijete-li možnost „vyčistit prostředky“ při odstranění jednoho z těchto připojení, může to narušit ostatní připojení historie dat, která na těchto prostředcích spoléhají.

Datové typy a schémata

Historie dat historizuje tři typy událostí z vaší instance Azure Digital Twins do Azure Data Exploreru: události životního cyklu relace, události životního cyklu dvojčat a aktualizace vlastností dvojčete (které můžou volitelně zahrnovat odstranění vlastností dvojčete). Každý z těchto typů událostí je uložený ve své vlastní tabulce v databázi Azure Data Exploreru, což znamená, že historie dat uchovává tři tabulky celkem. Při nastavování připojení historie dat můžete pro tabulky zadat vlastní názvy.

Zbytek této části podrobně popisuje tři tabulky Azure Data Exploreru, včetně schématu dat pro každou tabulku.

Aktualizace vlastností dvojčat

Tabulka Azure Data Exploreru pro aktualizace vlastností dvojčete má výchozí název AdtPropertyEvents. Při vytváření připojení můžete ponechat výchozí název nebo zadat vlastní název tabulky.

Data časových řad pro aktualizace vlastností dvojčete se ukládají s následujícím schématem:

Vlastnost	Typ	Popis
TimeStamp	Datum a čas	Datum/čas, kdy byla zpráva o aktualizaci vlastnosti zpracována službou Azure Digital Twins. Toto pole nastavuje systém a uživatelé ho nemůžou zapisovat.
SourceTimeStamp	Datum a čas	Volitelná zapisovatelná vlastnost představující časové razítko při aktualizaci vlastnosti byla pozorována v reálném světě. Tuto vlastnost lze zapsat pouze pomocí verze 2022-05-31 rozhraní API a sad SDK služby Azure Digital Twins a hodnota musí být v souladu s formátem data a času ISO 8601. Další informace o tom, jak tuto vlastnost aktualizovat, naleznete v tématu Aktualizace zdrojového času vlastnosti.
ServiceId	Řetězec	ID instance služby služby Azure IoT, která protokoluje záznam
Id	Řetězec	ID dvojčete
ModelId	Řetězec	ID modelu DTDL (DTMI)
Key	Řetězec	Název aktualizované vlastnosti
Value	Dynamický	Hodnota aktualizované vlastnosti
RelationshipId	Řetězec	Když se aktualizuje vlastnost definovaná u relace (na rozdíl od dvojčat nebo zařízení), toto pole se naplní ID relace. Při aktualizaci vlastnosti dvojčete je toto pole prázdné.
RelationshipTarget	Řetězec	Pokud se aktualizuje vlastnost definovaná v relaci (na rozdíl od dvojčat nebo zařízení), toto pole se naplní ID dvojčete, na které cílí relace. Při aktualizaci vlastnosti dvojčete je toto pole prázdné.
Action	Řetězec	Tento sloupec existuje pouze v případě, že se rozhodnete zaznamenávat události odstraňování vlastností. Pokud ano, tento sloupec obsahuje typ události týkající se vlastností dvojčete (aktualizace nebo smazání).

Níže je příklad tabulky aktualizací vlastností dvojčat uložených v Azure Data Exploreru.

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	PasteurizačníStroj_A01	dtmi:assetGen:PasteurizationMachine;1	Výstup	130
2022-12-15 20:23:39.3235925	2022-12-15 20:22:26.5837559	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizačníStroj_A01	dtmi:assetGen:PasteurizationMachine;1	Výstup	140
2022-12-15 20:23:47.078367	2022-12-15 20:22:34.9375957	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizačníStroj_A01	dtmi:assetGen:PasteurizationMachine;1	Výstup	130
2022-12-15 20:23:57.3794198	2022-12-15 20:22:50.1028562	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizačníStroj_A01	dtmi:assetGen:PasteurizationMachine;1	Výstup	123

Reprezentace vlastností s více poli

Možná budete muset uložit vlastnost, která má více polí. Tyto vlastnosti jsou reprezentovány objektem JSON v Value atributu schématu.

Pokud například představujete vlastnost se třemi poli pro roll, pitch a yaw, historie dat uloží následující objekt JSON jako Value: {"roll": 20, "pitch": 15, "yaw": 45}.

Události životního cyklu dvojčat

Tabulka Azure Data Exploreru pro události životního cyklu dvojčat má vlastní název, který zadáte při vytváření připojení historie dat.

Data časových řad pro události životního cyklu dvojčat se ukládají s následujícím schématem:

Vlastnost	Typ	Popis
TwinId	Řetězec	ID dvojčete
Action	Řetězec	Typ události životního cyklu dvojčete (vytvoření nebo odstranění)
TimeStamp	Datum a čas	Datum a čas, kdy služba Azure Digital Twins zpracovala událost životního cyklu dvojčete. Toto pole nastavuje systém a uživatelé ho nemůžou zapisovat.
ServiceId	Řetězec	ID instance služby služby Azure IoT, která protokoluje záznam
ModelId	Řetězec	ID modelu DTDL (DTMI)

Níže je příklad tabulky aktualizací životního cyklu dvojčat uložených v Azure Data Exploreru.

TwinId	Action	TimeStamp	ServiceId	ModelId
PasteurizačníStroj_A01	Vytvářet	2022-12-15 07:14:12.4160	dairyadtinstance.api.wcus.digitaltwins.azure.net	dtmi:assetGen:PasteurizationMachine;1
PasteurizationMachine_A02 (Pasterizační stroj)	Vytvářet	2022-12-15 07:14:12.4210	dairyadtinstance.api.wcus.digitaltwins.azure.net	dtmi:assetGen:PasteurizationMachine;1
SaltMachine_C0	Vytvářet	2022-12-15 07:14:12.5480	dairyadtinstance.api.wcus.digitaltwins.azure.net	dtmi:assetGen:SaltMachine;1
PasteurizationMachine_A02 (Pasterizační stroj)	Vymazat	2022-12-15 07:15:49.6050	dairyadtinstance.api.wcus.digitaltwins.azure.net	dtmi:assetGen:PasteurizationMachine;1

Události životního cyklu vztahu

Tabulka Azure Data Exploreru pro události životního cyklu relace má vlastní název, který zadáte při vytváření připojení historie dat.

Data časových řad pro události životního cyklu vztahu se ukládají s následujícím schématem:

Vlastnost	Typ	Popis
RelationshipId	Řetězec	ID vztahu. Toto pole nastavuje systém a uživatelé ho nemůžou zapisovat.
Name	Řetězec	Název vztahu
Action	Typ události životního cyklu relace (vytvoření nebo odstranění)
TimeStamp	Datum a čas	Datum/čas, kdy byla událost životního cyklu relace zpracována službou Azure Digital Twins. Toto pole nastavuje systém a uživatelé ho nemůžou zapisovat.
ServiceId	ID instance služby služby Azure IoT, která protokoluje záznam
Source	ID zdrojového dvojčete. Toto je ID dvojčete, odkud relace pochází.
Target	ID cílového dvojčete. Toto je ID dvojčete, k němuž vztah směřuje.

Níže je příklad tabulky aktualizací životního cyklu relací uložených v Azure Data Exploreru.

RelationshipId	Name	Action	TimeStamp	ServiceId	Source	Target
PasteurizationMachine_A01_feeds_Relationship0	krmí	Vytvářet	2022-12-15 07:16:12.7120	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizačníStroj_A01	SaltMachine_C0
Pasteurizační_stroj_A02_podává_Vztah0	krmí	Vytvářet	2022-12-15 07:16:12.7160	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A02 (Pasterizační stroj)	SaltMachine_C0
PasteurizationMachine_A03_feeds_Relationship0	krmí	Vytvářet	2022-12-15 07:16:12.7250	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizačníStroj_A03	SaltMachine_C1
OsloFactory_contains_Relationship0	obsahuje	Vymazat	2022-12-15 07:16:13.1780	dairyadtinstance.api.wcus.digitaltwins.azure.net	OsloFactory	SaltMachine_C0

Latence příjmu dat od konce do konce

Historie dat Azure Digital Twins vychází ze stávajícího mechanismu příjmu dat, který poskytuje Azure Data Explorer. Azure Digital Twins zajistí, že se události aktualizace grafu zpřístupní Azure Data Exploreru během méně než dvou sekund. Při ingestování dat službou Azure Data Explorer může být zavedena další latence.

V Azure Data Exploreru existují dvě metody pro příjem dat: příjem dávek a streamingový příjem. Tyto metody příjmu dat můžete nakonfigurovat pro jednotlivé tabulky podle vašich potřeb a konkrétního scénáře příjmu dat.

Streamovací příjem má nejnižší latenci. Kvůli režii na zpracování by se ale tento režim měl použít pouze v případě, že se každou hodinu ingestuje méně než 4 GB dat. Dávkové příjem dat funguje nejlépe, pokud se očekává vysoká míra příjmu dat. Azure Data Explorer ve výchozím nastavení používá dávkové příjem dat. Následující tabulka shrnuje očekávanou kompletní latenci nejhoršího případu:

Konfigurace Azure Data Exploreru	Očekávaná end-to-end latence	Doporučená rychlost dat
Příjem streamovaných dat	<12 sekund (<typický 3 sekundy)	<4 GB za hodinu
Dávkový příjem dat	Liší se (12 sekund-15 m v závislosti na konfiguraci)	>4 GB za hodinu

Zbytek této části obsahuje podrobnosti o povolování jednotlivých typů příjmu.

Dávkový příjem dat (výchozí)

Pokud není nakonfigurované jinak, Azure Data Explorer použije dávkové příjem dat. Výchozí nastavení může vést k tomu, že data budou k dispozici pouze 5 až 10 minut po provedení aktualizace digitálního dvojčete. Zásady příjmu dat je možné změnit tak, aby dávkové zpracování probíhalo maximálně každých 10 sekund (minimálně nebo maximálně 15 minut). Pokud chcete změnit zásady příjmu dat, musí být v zobrazení dotazu Azure Data Exploreru vydán následující příkaz:

.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}' 

Ujistěte se, že <table_name> je nahrazen názvem tabulky, která byla nastavena za vás. Parametr MaximumBatchingTimeSpan by měl být nastavený na upřednostňovaný interval dávkování. Může trvat 5 až 10 minut, než se zásada projeví. Další informace o dávkovém zpracování dat najdete na následujícím odkazu: Příkaz pro správu politiky Kusto IngestionBatching.

Příjem streamovaných dat

Povolení streamingového příjmu je proces ve dvou krocích:

1. Povolte streamování dat pro váš cluster. Tuto akci je potřeba provést jenom jednou. (Upozornění: Pokud to uděláte, bude mít vliv na množství úložiště dostupného pro horkou mezipaměť a může dojít k dalším omezením). Pokyny najdete v tématu Konfigurace příjmu streamovaných dat v clusteru Azure Data Exploreru.
2. Přidejte zásadu streamovaného ingestování pro požadovanou tabulku. Další informace o povolení příjmu dat ze streamování pro váš cluster najdete v dokumentaci k Azure Data Exploreru: Příkaz pro správu zásad Kusto IngestionBatching.

Pokud chcete povolit streamovací ingestování pro tabulku historie dat Azure Digital Twins, musí být v podokně dotazů Azure Data Exploreru vydán následující příkaz:

.alter table <table_name> policy streamingingestion enable 

Ujistěte se, že <table_name> je nahrazen názvem tabulky, která byla nastavena za vás. Může trvat 5 až 10 minut, než se zásada projeví.

Vizualizace historizovaných vlastností

Azure Digital Twins Explorer, vývojářský nástroj pro vizualizaci a interakci s daty Azure Digital Twins, nabízí funkci Průzkumníka historie dat pro zobrazení historizovaných vlastností v grafu nebo tabulce v průběhu času. Tato funkce je dostupná také v 3D Scenes Studio, což je imerzivní 3D prostředí pro přiblížení vizuálního kontextu 3D prostředků Azure Digital Twins.

Podrobnější informace o používání Průzkumníka historie dat najdete v tématu Ověření a prozkoumání historizovaných vlastností.

Poznámka:

Pokud při výběru vlastnosti v průzkumníku vizuálních dat narazíte na problémy, může to znamenat, že v nějakém modelu ve vaší instanci došlo k chybě. Například tato funkce vizualizace bude narušena, pokud budou mít atributy modelu nejedinečné hodnoty výčtu. Pokud k tomu dojde, zkontrolujte definice modelu a ujistěte se, že jsou všechny vlastnosti platné.

Další kroky

Jakmile se data dvojčete historizují do Azure Data Exploreru, můžete pomocí modulu plug-in dotazů Azure Digital Twins pro Azure Data Explorer spouštět dotazy napříč daty. Další informace o modulu plug-in najdete tady: Dotazování pomocí modulu plug-in Azure Data Explorer.

Nebo se ponořte hlouběji do historie dat s pokyny k vytvoření a ukázkovým scénářem: Vytvoření připojení historie dat.