Skapa en datahistorikanslutning för Azure Digital Twins

Datahistorik är en Azure Digital Twins-funktion för att automatiskt historisera grafuppdateringar till Azure Data Explorer. Dessa data kan efterfrågas med hjälp av Azure Digital Twins-frågeprogrammet för Azure Data Explorer för att få insikter om din miljö över tid.

Den här artikeln visar hur du konfigurerar en fungerande datahistorikanslutning mellan Azure Digital Twins och Azure Data Explorer. Den använder Azure CLI och Azure-portalen för att konfigurera och ansluta nödvändiga datahistorikresurser, inklusive:

• en Azure Digital Twins-instans
• ett Event Hubs-namnområde som innehåller en händelsehubb
• ett Azure Data Explorer-kluster som innehåller en databas

Den innehåller också ett exempeltvillingdiagram som du kan använda för att se historiserade grafuppdateringar i Azure Data Explorer.

Förutsättningar

Förbereda din miljö för Azure CLI

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Kom igång med Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du överväga att köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Autentisera till Azure med Azure CLI.

  • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda och hantera tillägg med Azure CLI.

  • Kör az version för att hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Konfigurera CLI-session

För att börja arbeta med Azure Digital Twins i CLI är det första du behöver göra att logga in och ange CLI-kontexten till din prenumeration för den här sessionen. Kör följande kommandon i CLI-fönstret:

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

Om du använder den här prenumerationen med Azure Digital Twins för första gången kör du följande kommando för att registrera dig med Azure Digital Twins-namnområdet. (Om du inte är säker är det ok att köra den igen även om du körde den någon gång tidigare.)

az provider register --namespace 'Microsoft.DigitalTwins'

Sedan lägger du till Microsoft Azure IoT Extension för Azure CLI för att möjliggöra kommandon som interagerar med Azure Digital Twins och andra IoT-tjänster. Kör det här kommandot för att kontrollera att du har den senaste versionen av tillägget:

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

Nu är du redo att arbeta med Azure Digital Twins i Azure CLI.

Du kan verifiera den här statusen genom att köra az dt --help när som helst för att se en lista över de Azure Digital Twins-kommandon på toppen som är tillgängliga.

Konfigurera lokala variabler för CLI-session

Den här artikeln innehåller CLI-kommandon som du kan använda för att skapa datahistorikresurser. För att göra det enkelt att kopiera och köra dessa kommandon senare kan du konfigurera lokala variabler i CLI-sessionen nu och sedan referera till dessa variabler senare i CLI-kommandona när du skapar dina resurser. Om du vill skapa variablerna uppdaterar du platshållarna (identifieras med <...> hakparenteser) i följande kommandon och kör sedan kommandona. Se till att följa namngivningsreglerna som beskrivs i kommentarerna. Dessa värden används senare när du skapar de nya resurserna.

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

Skapa en Azure Digital Twins-instans med en hanterad identitet

Om du redan har en Azure Digital Twins-instans kontrollerar du att du aktiverar en systemtilldelad hanterad identitet för den.

Om du inte har någon Azure Digital Twins-instans följer du anvisningarna i Skapa instansen med en hanterad identitet för att skapa en Azure Digital Twins-instans med en systemtilldelad hanterad identitet för första gången.

Kontrollera sedan att du har Azure Digital Twins Data Owner-rollen på instansen. Du hittar instruktioner i Konfigurera behörigheter för användaråtkomst.

Om du vill lägga till namnet på din instans i dina lokala CLI-variabler, så att den automatiskt kan anslutas till senare kommandon som kopieras från den här artikeln, lagrar du den i variabeln dtname så här:

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

Skapa ett Event Hubs-namnområde och en händelsehubb

Nästa steg är att skapa ett Event Hubs-namnområde och en händelsehubb. Den här hubben tar emot meddelanden om diagramlivscykel och egenskapsuppdatering från Azure Digital Twins-instansen och vidarebefordrar sedan meddelandena till Azure Data Explorer-målklustret.

Som en del av konfigurationen av datahistorikanslutningen senare beviljar du Azure Digital Twins-instansen rollen Azure Event Hubs-dataägare på händelsehubbens resurs.

Mer information om Event Hubs och deras funktioner finns i dokumentationen för 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

Skapa ett Kusto-kluster (Azure Data Explorer) och en databas

Skapa sedan ett Kusto-kluster (Azure Data Explorer) och en databas för att ta emot data från Azure Digital Twins.

Som en del av konfigurationen av datahistorikanslutningen senare ger du Azure Digital Twins-instansen rollen Deltagare på åtminstone databasen (den kan också begränsas till klustret) och administratörsrollen i databasen.

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

Konfigurera datahistorikanslutning

Nu när du har skapat de resurser som krävs använder du kommandot i det här avsnittet för att skapa en datahistorikanslutning mellan Azure Digital Twins-instansen, händelsehubben och Azure Data Explorer-klustret.

Det här kommandot skapar också tre tabeller i Azure Data Explorer-databasen för att lagra uppdateringar av tvillingegenskaper, livscykelhändelser för relationer och livscykelhändelser för tvillingar. Mer information om dessa typer av historiserade data och deras motsvarande Azure Data Explorer-tabeller finns i Datatyper och scheman.

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

När du har konfigurerat anslutningen till datahistoriken kan du ta bort de roller som beviljats din Azure Digital Twins-instans för åtkomst till Event Hubs- och Azure Data Explorer-resurser. För att kunna använda datahistorik är den enda roll som instansen behöver Azure Event Hubs Data Sender (eller en högre roll som innehåller dessa behörigheter, till exempel Azure Event Hubs Data Owner) på Event Hubs-resursen.

Begränsa nätverksåtkomsten till datahistorikresurser

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. Dessa begränsningar omfattar inaktivering av lokal åtkomst för dina resurser, bland annat åtgärder för att minska nätverksåtkomsten.

För att säkerställa att dina datahistorikresurser kan kommunicera med varandra bör du också ändra dataanslutningen för Azure Data Explorer-databasen så att den använder en systemtilldelad hanterad identitet.

Utför följande steg för att se till att anslutningen till datahistoriken är korrekt konfigurerad när dina resurser behöver begränsad nätverksåtkomst:

1. Kontrollera att lokal auktorisering är aktiverad för dina datahistorikresurser (din Azure Digital Twins-instans, händelsehubb och Azure Data Explorer-kluster)
2. Skapa datahistorikanslutningen
3. Uppdatera dataanslutningen för Azure Data Explorer-databasen så att den använder en systemtilldelad hanterad identitet. I Azure-portalen kan du uppdatera dataanslutningen genom att navigera till Azure Data Explorer-klustret och använda Databaser på menyn för att navigera till datahistorikdatabasen. I databasmenyn väljer du Dataanslutningar. I tabellposten för datahistorikanslutningen bör du se alternativet Tilldela hanterad identitet, där du kan välja Systemtilldelad.
4. Du kan nu inaktivera lokal auktorisering eller ange andra nätverksbegränsningar för dina önskade resurser genom att ändra åtkomstinställningarna för din Azure Digital Twins-instans, händelsehubb eller Azure Data Explorer-kluster.

Felsöka konfiguration av anslutning

Här följer några vanliga fel som kan uppstå när du konfigurerar en datahistorikanslutning och hur du löser dem.

• Om du har inaktiverat åtkomsten till det offentliga nätverket för ditt Azure Data Explorer-kluster uppstår ett fel om att tjänsten inte kunde skapa datahistorikanslutningen med meddelandet "Resursen kunde inte AGERA på grund av ett internt serverfel". Det går inte att konfigurera datahistorik om Azure Data Explorer-klustret har inaktiverad åtkomst till det offentliga nätverket, eftersom Azure Digital Twins inte kan konfigurera tabellerna och andra artefakter som krävs.
• (CLI-användare) Om du stöter på felet "Det gick inte att skapa Azure Digital Twins-instansanslutning. Det går inte att skapa en tabell- och mappningsregel i databasen. Kontrollera dina behörigheter för Azure Database Explorer och kör az login för att uppdatera dina autentiseringsuppgifter", lösa felet genom att lägga till dig själv som en AllDatabasesAdmin under Behörigheter i ditt Azure Data Explorer-kluster.
• (Cloud Shell-användare) Om du använder Cloud Shell och får felet "Det gick inte att ansluta till MSI. Kontrollera att MSI är korrekt konfigurerat", prova att köra kommandot med en lokal Azure CLI-installation i stället.

Verifiera med ett exempeltvillingdiagram

Nu när din datahistorikanslutning har konfigurerats kan du testa den med data från dina digitala tvillingar.

Om du redan har tvillingar i din Azure Digital Twins-instans som aktivt tar emot grafuppdateringar (inklusive uppdateringar av tvillingegenskap eller uppdateringar från att ändra strukturen i diagrammet genom att skapa eller ta bort element) kan du hoppa över det här avsnittet och visualisera resultaten med dina egna resurser.

Annars kan du fortsätta med det här avsnittet för att konfigurera ett exempeldiagram som genomgår livscykelhändelser för tvillingar och relationer och genererar uppdateringar av tvillingegenskaper.

Du kan konfigurera ett exempeldiagram för det här scenariot med hjälp av Azure Digital Twins Data Simulator. Azure Digital Twins Data Simulator skapar tvillingar och relationer i din Azure Digital Twins-instans och push-överför kontinuerligt egenskapsuppdateringar till tvillingarna.

Skapa ett exempeldiagram

Du kan använda Azure Digital Twins Data Simulator för att etablera ett exempeltvillingdiagram och skicka egenskapsuppdateringar till den. Tvillingdiagrammet som skapas här modellerar pastöriseringsprocesser för ett mejeriföretag.

Börja med att öppna Azure Digital Twins Data Simulator i webbläsaren. Ange följande fält:

• Instans-URL: Ange värdnamnet för din Azure Digital Twins-instans. Värdnamnet finns på portalsidan för din instans och har ett format som <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net.
• Simuleringstyp: Välj Mejerianläggning i den nedrullningsbara menyn.

Välj Generera miljö.

Du ser bekräftelsemeddelanden på skärmen när modeller, tvillingar och relationer skapas i din miljö. Den här processen genererar även händelser för tvilling- och relationsskapande, som historiseras till Azure Data Explorer som tvilling- respektive relationslivscykelhändelser.

När simuleringen är klar aktiveras knappen Starta simulering . Rulla nedåt och välj Starta simulering för att skicka simulerade data till din Azure Digital Twins-instans. Om du vill uppdatera tvillingarna kontinuerligt i din Azure Digital Twins-instans håller du det här webbläsarfönstret i förgrunden på skrivbordet och utför andra webbläsaråtgärder i ett separat fönster. Det här fönstret genererar kontinuerligt uppdateringar av tvillingegenskaper som lagras historiskt i Azure Data Explorer.

Visa historiserade uppdateringar i Azure Data Explorer

Det här avsnittet visar hur du visar alla tre typer av historiserade uppdateringar som genereras av simulatorn och lagras i Azure Data Explorer-tabeller.

Börja i Azure-portalen och gå till Azure Data Explorer-klustret som du skapade tidigare. Välj fönstret Fråga under Data på den vänstra menyn för att öppna frågevyn.

Expandera sedan klustret och databasen i den vänstra rutan för att se namnet på datahistoriktabellerna. Det bör finnas tre: en för uppdateringshändelser för tvillingegenskap, en för relationslivscykelhändelser och en för tvillinglivscykelhändelser. Du använder dessa tabellnamn för att köra frågor i tabellerna för att verifiera och visa historiserade data.

Verifiera tabellinnehåll

Om du vill kontrollera att händelserna historiseras till databasen börjar du med att kopiera följande kommando. Den har en platshållare för namnet för tabellen relationslivscykelhändelser och ändrar tabellens datainmatningsläge till batchläge så att den bearbetar data från livesimuleringen var tionde sekund.

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

Klistra in kommandot i frågefönstret och byt ut platshållaren mot namnet på tabellen för dina relationshändelser. Välj knappen Kör för att köra kommandot.

Upprepa kommandot två gånger till med namnet på tabellen för tvillinglivscykelhändelser och sedan tabellen för egenskapsuppdatering för att uppdatera inmatningsläget för de andra tabellerna också.

Lägg sedan till följande kommandon i frågefönstret och kör dem. Varje kommando innehåller en platshållare för namnet på en av tabellerna och kommandona matar ut antalet objekt i tabellerna.

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

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

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

I resultatet bör du se att antalet objekt i varje tabell är något större än noll, vilket indikerar att egenskapsuppdatering, relationslivscykel och tvillinglivscykelhändelser historiseras till respektive tabeller.

Utforska tabellen över uppdateringar för egenskaper för tvillingar

I det här avsnittet gör du lite mer utforskning med tvillingegenskapens uppdateringsdata som finns i tabellen.

Kör först följande kommando för att visa 100 poster i tabellen:

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

Kör sedan en fråga baserat på dina tvillingars data för att se kontextualiserade tidsseriedata.

Använd följande fråga för att kartlägga utflödet av alla tvillingmaskiner för salt i mejerifabriken i Oslo. Den här Kusto-frågan använder Plugin-programmet Azure Digital Twins för att välja tvillingar av intresse, kopplar tvillingarna mot tidsserien för datahistorik i Azure Data Explorer och kartlägger sedan resultaten. Ersätt platshållaren <ADT-instance-host-name> med värdnamnet för din instans och platshållaren <table-name> med namnet på din tabell för tvillingegenskapsuppdateringar.

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)

Resultatet bör visa att utflödesnumren ändras över tid.

Felsöka anslutning

Om du inte ser data i Azure Data Explorer fungerar inte historiseringsdataflödet korrekt. Du kan undersöka problemet genom att visa event hubs-namnområdet i Azure-portalen, som visar diagram som visar flödet av meddelanden till och från namnområdet. Med den här skärmen kan du verifiera både flödet av inkommande meddelanden från Azure Digital Twins och utgående meddelanden till Azure Data Explorer, så att du kan identifiera vilken del av flödet som inte fungerar.

Nästa steg

Om du vill fortsätta utforska mejeriscenariot kan du visa fler exempelfrågor på GitHub som visar hur du kan övervaka prestanda för mejeriverksamheten baserat på maskintyp, fabrik, underhållstekniker och olika kombinationer av dessa parametrar.

Om du vill skapa Grafana-instrumentpaneler som visualiserar prestanda för mejeriåtgärden läser du Skapa instrumentpaneler med Azure Digital Twins, Azure Data Explorer och Grafana.

Mer information om hur du använder Azure Digital Twins-frågeprogrammet för Azure Data Explorer finns i Fråga med plugin-programmet Azure Data Explorer och det här blogginlägget. Du kan också läsa mer om plugin-programmet här: Fråga med plugin-programmet Azure Data Explorer.