Vytvoření připojení historie dat pro Azure Digital Twins

Historie dat je funkce Azure Digital Twins pro automatické historizaci aktualizací grafu v Azure Data Exploreru. Tato data se dají dotazovat pomocí modulu plug-in dotazů Azure Digital Twins pro Azure Data Explorer , abyste získali přehled o vašem prostředí v průběhu času.

Tento článek ukazuje, jak nastavit pracovní připojení historie dat mezi Službou Azure Digital Twins a Azure Data Explorerem. Používá Azure CLI a Azure Portal k nastavení a připojení požadovaných prostředků historie dat, mezi které patří:

• instance Azure Digital Twins
• Obor názvů služby Event Hubs obsahující centrum událostí
• Cluster Azure Data Exploreru obsahující databázi

Obsahuje také ukázkový graf dvojčete, který můžete použít k zobrazení aktualizací historizovaných grafů v Azure Data Exploreru.

Požadavky

Příprava prostředí pro rozhraní příkazového řádku Azure

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Nastavení relace rozhraní příkazového řádku

Pokud chcete začít pracovat s Azure Digital Twins v rozhraní příkazového řádku, je první věc, kterou je potřeba udělat, přihlásit se a nastavit kontext rozhraní příkazového řádku pro vaše předplatné pro tuto relaci. V okně rozhraní příkazového řádku spusťte tyto příkazy:

az login
az account set --subscription "<your-Azure-subscription-ID>"

Pokud jste toto předplatné použili s Azure Digital Twins poprvé, spusťte tento příkaz a zaregistrujte se v oboru názvů Azure Digital Twins. (Pokud si nejste jistí, můžete ho znovu spustit, i když jste to někdy udělali v minulosti.)

az provider register --namespace 'Microsoft.DigitalTwins'

Dále přidáte rozšíření Microsoft Azure IoT pro Azure CLI, které povolí příkazy pro interakci se službou Azure Digital Twins a dalšími službami IoT. Spuštěním tohoto příkazu se ujistěte, že máte nejnovější verzi rozšíření:

az extension add --upgrade --name azure-iot

Teď jste připraveni pracovat s Azure Digital Twins v Azure CLI.

Můžete to ověřit spuštěním az dt --help kdykoli a zobrazit seznam příkazů Azure Digital Twins nejvyšší úrovně, které jsou k dispozici.

Nastavení místních proměnných pro relaci rozhraní příkazového řádku

Tento článek obsahuje příkazy rozhraní příkazového řádku, které můžete použít k vytvoření prostředků historie dat. Abyste mohli tyto příkazy později snadno zkopírovat a spustit, můžete teď nastavit místní proměnné v relaci rozhraní příkazového řádku a pak tyto proměnné při vytváření prostředků odkazovat na tyto proměnné později. V následujících příkazech aktualizujte zástupné symboly (označené hranatými <...> závorkami) a spuštěním těchto příkazů vytvořte proměnné. Nezapomeňte dodržovat pravidla pojmenování popsaná v komentářích. Tyto hodnoty budou použity později při vytváření nových prostředků.

## General Setup
location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events will be stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events will be stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates will be stored. If not provided, the table will be named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

Vytvoření instance Azure Digital Twins se spravovanou identitou

Pokud už máte instanci Azure Digital Twins, ujistěte se, že jste pro ni povolili spravovanou identitu přiřazenou systémem.

Pokud nemáte instanci Azure Digital Twins, postupujte podle pokynů v tématu Vytvoření instance se spravovanou identitou a vytvořte instanci Azure Digital Twins s spravovanou identitou přiřazenou systémem poprvé.

Pak se ujistěte, že máte v instanci roli Vlastník dat Služby Azure Digital Twins. Pokyny najdete v tématu Nastavení uživatelských přístupových oprávnění.

Pokud chcete přidat název instance do místních proměnných rozhraní příkazového řádku, aby se automaticky připojil k pozdějším příkazům zkopírovaným z tohoto článku, uložte ho do proměnné dtname takto:

dtname="<name-of-your-instance>"

Vytvoření oboru názvů služby Event Hubs a centra událostí

Dalším krokem je vytvoření oboru názvů služby Event Hubs a centra událostí. Toto centrum obdrží oznámení o životním cyklu grafu a aktualizaci vlastností z instance Služby Azure Digital Twins a pak zprávy přepošla do cílového clusteru Azure Data Exploreru.

V rámci nastavení připojení historie dat později udělíte instanci Služby Azure Digital Twins roli Vlastník dat služby Azure Event Hubs pro prostředek centra událostí.

Další informace o službě Event Hubs a jejich možnostech najdete v dokumentaci ke službě Event Hubs.

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --location $location

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

Vytvoření clusteru a databáze Kusto (Azure Data Explorer)

Dále vytvořte cluster a databázi Kusto (Azure Data Explorer) pro příjem dat z Azure Digital Twins.

V rámci nastavení připojení historie dat později udělíte instanci Azure Digital Twins roli Přispěvatel alespoň pro databázi (může být také vymezena na cluster) a roli Správa v databázi.

az extension add --name kusto

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --location $location --type SystemAssigned

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D location=$location

Nastavení připojení historie dat

Teď, když jste vytvořili požadované prostředky, pomocí příkazu v této části vytvořte připojení historie dat mezi instancí služby Azure Digital Twins, centrem událostí a clusterem Azure Data Exploreru.

Tento příkaz také vytvoří ve vaší databázi Azure Data Exploreru tři tabulky pro ukládání aktualizací vlastností dvojčat, událostí životního cyklu dvojčat a událostí životního cyklu relací. Další informace o těchto typech historizovaných dat a jejich odpovídajících tabulkách Azure Data Exploreru najdete v tématu Datové typy a schémata.

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

Po nastavení připojení historie dat můžete volitelně odebrat role udělené vaší instanci služby Azure Digital Twins pro přístup k prostředkům služby Event Hubs a Azure Data Exploreru. Aby bylo možné používat historii dat, jedinou rolí, kterou instance potřebuje v budoucnu, je odesílatel dat služby Azure Event Hubs (nebo vyšší role, která zahrnuje tato oprávnění, například vlastník dat služby Azure Event Hubs) u prostředku služby Event Hubs.

Omezení síťového přístupu k prostředkům historie dat

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. To zahrnuje zakázání místního přístupu k vašim prostředkům, mimo jiné k omezení síťového přístupu.

Aby prostředky historie dat mohly vzájemně komunikovat, měli byste také upravit datové připojení pro databázi Azure Data Exploreru tak, aby používaly spravovanou identitu přiřazenou systémem.

Postupujte podle pokynů níže a ujistěte se, že je správně nastavené připojení historie dat, když vaše prostředky potřebují omezený síťový přístup.

1. Ujistěte se, že je pro prostředky historie dat povolená místní autorizace (instance služby Azure Digital Twins, centrum událostí a cluster Azure Data Exploreru).
2. Vytvoření připojení historie dat
3. Aktualizujte datové připojení pro databázi Azure Data Exploreru tak, aby používala spravovanou identitu přiřazenou systémem. Na webu Azure Portal to můžete udělat tak, že přejdete do clusteru Azure Data Exploreru a pomocí databází v nabídce přejdete do databáze historie dat. V nabídce databáze vyberte Datová připojení. V položce tabulky pro vaše připojení historie dat by se měla zobrazit možnost Přiřadit spravovanou identitu, kde můžete zvolit Systém přiřazený.
4. Teď můžete zakázat místní autorizaci nebo nastavit jiná omezení sítě pro požadované prostředky tak, že změníte nastavení přístupu v instanci služby Azure Digital Twins, centru událostí nebo clusteru Azure Data Explorer.

Řešení potíží s nastavením připojení

Tady je několik běžných chyb, se kterými se můžete setkat při nastavování připojení historie dat a jejich řešení.

• Pokud máte pro cluster Azure Data Exploreru zakázaný přístup k veřejné síti, dojde k chybě, že se službě nepodařilo vytvořit připojení historie dat, a zobrazí se zpráva "Prostředek se kvůli vnitřní chybě serveru nepodařilo act". Nastavení historie dat selže, pokud má cluster Azure Data Exploreru zakázaný přístup k veřejné síti, protože Azure Digital Twins nebude moct konfigurovat tabulky a další požadované artefakty.
• (uživatelé rozhraní příkazového řádku) Pokud dojde k chybě Nepodařilo se vytvořit připojení instance služby Azure Digital Twins. V databázi se nepodařilo vytvořit tabulku a pravidlo mapování. Zkontrolujte svá oprávnění pro Průzkumníka služby Azure Database a spusťte az login aktualizaci přihlašovacích údajů," vyřešte chybu tak, že se přidáte jako AllDatabases Správa v části Oprávnění v clusteru Azure Data Exploreru.
• (Uživatelé Cloud Shellu) Pokud používáte Cloud Shell a narazíte na chybu Nepovedlo se připojit k MSI. Ujistěte se, že je msi správně nakonfigurovaná," zkuste místo toho spustit příkaz s místní instalací Azure CLI.

Ověření pomocí ukázkového grafu dvojčete

Teď, když je nastavené připojení k historii dat, můžete ho otestovat pomocí dat z digitálních dvojčat.

Pokud už ve své instanci Služby Azure Digital Twins máte dvojčata, která aktivně přijímají aktualizace grafu (včetně aktualizací vlastností dvojčete nebo aktualizací od změny struktury grafu vytvořením nebo odstraněním prvků), můžete tuto část přeskočit a vizualizovat výsledky pomocí vlastních prostředků.

V opačném případě pokračujte v této části a nastavte ukázkový graf, který projde událostmi životního cyklu dvojčat a vztahů a vygeneruje aktualizace vlastností dvojčete.

Ukázkový graf pro tento scénář můžete nastavit pomocí simulátoru dat Azure Digital Twins. Simulátor dat Azure Digital Twins vytvoří dvojčata a vztahy v instanci služby Azure Digital Twins a průběžně odesílá aktualizace vlastností do dvojčat.

Vytvoření ukázkového grafu

Pomocí simulátoru dat Azure Digital Twins můžete zřídit ukázkový graf dvojčete a do něj odeslat aktualizace vlastností. Graf dvojčat vytvořený zde modeluje procesy pasterizace pro mlékárnou společnost.

Začněte otevřením datového simulátoru Azure Digital Twins v prohlížeči. Nastavte tato pole:

• Adresa URL instance: Zadejte název hostitele vaší instance Azure Digital Twins. Název hostitele najdete na stránce portálu pro vaši instanci a má formát, jako <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.netje .
• Typ simulace: V rozevírací nabídce vyberte mléčné zařízení .

Vyberte Generovat prostředí.

Na obrazovce se zobrazí potvrzovací zprávy jako modely, dvojčata a relace vytvořené ve vašem prostředí. Tím se také vygenerují události vytvoření dvojčete a vztahu, které budou historizovány do Azure Data Exploreru jako události životního cyklu dvojčat a vztahů.

Až bude simulace připravená, aktivuje se tlačítko Spustit simulaci . Posuňte se dolů a vyberte Spustit simulaci a nasdílejte simulovaná data do instance služby Azure Digital Twins. Pokud chcete nepřetržitě aktualizovat dvojčata v instanci služby Azure Digital Twins, nechte toto okno prohlížeče na popředí na ploše a proveďte další akce prohlížeče v samostatném okně. Tím se průběžně generují události aktualizace vlastností dvojčete, které se budou historizovat do Azure Data Exploreru.

Zobrazení historizovaných aktualizací v Azure Data Exploreru

V této části se dozvíte, jak zobrazit všechny tři typy historizovaných aktualizací vygenerovaných simulátorem a uložené v tabulkách Azure Data Exploreru.

Začněte na webu Azure Portal a přejděte do clusteru Azure Data Exploreru, který jste vytvořili dříve. Výběrem podokna Databáze v nabídce vlevo otevřete zobrazení databáze. Vyhledejte databázi, kterou jste vytvořili pro tento článek, a zaškrtněte políčko vedle ní a pak vyberte Dotaz.

Dále rozbalte cluster a databázi v levém podokně a zobrazte název tabulek historie dat. Měly by existovat tři: jedna pro události životního cyklu vztahu, jedna pro události životního cyklu dvojčete a jedna pro události aktualizace vlastností dvojčete. Tyto názvy tabulek použijete ke spouštění dotazů na tabulky k ověření a zobrazení historizovaných dat.

Ověření položek tabulky

Pokud chcete ověřit, že události jsou historizovány do databáze, začněte zkopírováním následujícího příkazu. Má zástupný symbol pro název tabulky událostí životního cyklu relace a změní příjem dat tabulky do dávkového režimu , aby ingestoval data z živé simulace každých 10 sekund.

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

Vložte příkaz do okna dotazu a nahraďte zástupný text názvem tabulky událostí relace. Výběrem tlačítka Spustit spusťte příkaz.

Opakujte tento příkaz ještě dvakrát pomocí názvu tabulky událostí životního cyklu dvojčete a potom aktualizujte tabulku vlastností, aby se aktualizoval režim příjmu dat ostatních tabulek.

Dále do okna dotazu přidejte následující příkazy a spusťte je. Každý příkaz obsahuje zástupný symbol pro název jedné z tabulek a příkazy vypíše počet položek v tabulkách.

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

<twin-property-updates-table-name>
| count

Ve výsledcích byste měli vidět, že počet položek v každé tabulce je něco větší než 0, což znamená, že události aktualizace vlastností, životního cyklu dvojčat a relací jsou historizovány do příslušných tabulek.

Prozkoumání tabulky aktualizací vlastností dvojčete

V této části provedete další průzkum pomocí vlastnosti dvojčete, která aktualizují data, která jsou v tabulce.

Nejprve spuštěním následujícího příkazu zobrazte 100 záznamů v tabulce:

<twin-property-updates-table-name>
| limit 100

Potom spusťte dotaz založený na datech dvojčat, abyste viděli kontextová data časových řad.

Pomocí následujícího dotazu namapujte odtok všech dvojčat solných strojů v ukázkové mléčné továrně Oslo. Tento dotaz Kusto používá modul plug-in Azure Digital Twins k výběru dvojčat, která jsou zajímají, připojí tato dvojčata k časovým řadám historie dat v Azure Data Exploreru a pak zobrazí grafy výsledků. Nezapomeňte zástupný text nahradit <ADT-instance-host-name> názvem hostitele vaší instance a <table-name> zástupným symbolem názvem tabulky událostí vlastnosti dvojčete.

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

Výsledky by měly zobrazovat čísla odtoku, která se v průběhu času mění.

Řešit potíže s připojením

Pokud v Azure Data Exploreru nevidíte data, tok dat historizace nefunguje správně. Problém můžete prozkoumat zobrazením oboru názvů služby Event Hubs na webu Azure Portal, který zobrazuje grafy znázorňující tok zpráv do oboru názvů a mimo obor názvů. To vám umožní ověřit tok příchozích zpráv z Azure Digital Twins i odchozích zpráv do Azure Data Exploreru, abyste mohli zjistit, která část toku nefunguje.

Další kroky

Pokud chcete pokračovat ve zkoumání scénáře mléka, můžete na GitHubu zobrazit další ukázkové dotazy, které ukazují, jak můžete monitorovat výkon operace mléka na základě typu stroje, továrny, technika údržby a různých kombinací těchto parametrů.

Pokud chcete vytvořit řídicí panely Grafana, které vizualizují výkon mléčné operace, přečtěte si téma Vytváření řídicích panelů pomocí azure Digital Twins, Azure Data Exploreru a Grafany.

Další informace o použití modulu plug-in dotazů Azure Digital Twins pro Azure Data Explorer najdete v tématu Dotazování pomocí modulu plug-in Azure Data Explorer a tohoto blogového příspěvku. Další informace o modulu plug-in najdete tady: Dotazování pomocí modulu plug-in Azure Data Explorer.