Share via


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:

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

Dricks

Även om den här artikeln använder Azure-portalen kan du även arbeta med datahistorik med hjälp av 2022-05-31-versionen av de övriga API:erna.

Förutsättningar

Förbereda din miljö för Azure CLI

Kommentar

Du kan också använda Azure Cloud Shell i PowerShell-miljön i stället för Bash-miljön om du vill. Kommandona på den här sidan är skrivna för Bash-miljön, så de kan kräva att vissa små justeringar körs i PowerShell.

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>"

Dricks

Du kan också använda ditt prenumerationsnamn i stället för ID:t i kommandot ovan.

Om det är första gången du använder den här prenumerationen med Azure Digital Twins kör du det här kommandot 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 har gjort det någon gång tidigare.)

az provider register --namespace 'Microsoft.DigitalTwins'

Därefter lägger du till Microsoft Azure IoT-tillägget för Azure CLI för att aktivera kommandon för att interagera 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 kontrollera detta genom att köra az dt --help när som helst för att se en lista över de högsta Azure Digital Twins-kommandona 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. Uppdatera platshållarna (identifieras med <...> hakparenteser) i kommandona nedan och kör dessa kommandon för att skapa variablerna. Se till att följa namngivningsreglerna som beskrivs i kommentarerna. Dessa värden används senare när du skapar de nya resurserna.

Kommentar

Dessa kommandon är skrivna för Bash-miljön. De kan justeras för PowerShell om du föredrar att använda en PowerShell CLI-miljö.

## 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>"

Skapa en Azure Digital Twins-instans med en hanterad identitet

Om du redan har en Azure Digital Twins-instans kontrollerar du att du har aktiverat 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 rollen Som Azure Digital Twins-dataägare 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 ansluts 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 får 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.

Kommentar

När du konfigurerar datahistorik måste lokal auktorisering aktiveras på händelsehubben. Om du slutligen vill inaktivera lokal auktorisering på din händelsehubb inaktiverar du auktoriseringen när du har konfigurerat anslutningen. Du måste också justera vissa behörigheter, som beskrivs i Begränsa nätverksåtkomst till datahistorikresurser senare i den här artikeln.

Använd följande CLI-kommandon för att skapa de resurser som krävs. Kommandona använder flera lokala variabler (, , och $eventhub) som skapades tidigare i Konfigurera lokala variabler för CLI-sessionen. $eventhubnamespace$resourcegroup$location

Skapa ett Event Hubs-namnområde:

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

Skapa en händelsehubb i ditt namnområde:

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 beviljar du Azure Digital Twins-instansen rollen Deltagare på åtminstone databasen (den kan också begränsas till klustret) och administratörsrollen i databasen.

Viktigt!

Kontrollera att klustret har offentlig nätverksåtkomst aktiverad. Om Azure Data Explorer-klustret har inaktiverat åtkomsten till det offentliga nätverket kan Azure Digital Twins inte konfigurera tabellerna och andra nödvändiga artefakter, och konfigurationen av datahistoriken misslyckas.

Använd följande CLI-kommandon för att skapa de resurser som krävs. Kommandona använder flera lokala variabler (, , och $databasename) som skapades tidigare i Konfigurera lokala variabler för CLI-sessionen. $clustername$resourcegroup$location

Börja med att lägga till Kusto-tillägget i CLI-sessionen, om du inte redan har det.

az extension add --name kusto

Skapa sedan Kusto-klustret. Kommandot nedan kräver 5–10 minuter att köra och skapar ett E2a v4-kluster på utvecklarnivån. Den här typen av kluster har en enda nod för motorn och datahanteringsklustret och gäller för utvecklings- och testscenarier. Mer information om nivåerna i Azure Data Explorer och hur du väljer rätt alternativ för din produktionsarbetsbelastning finns i Välj rätt beräknings-SKU för ditt Azure Data Explorer-kluster och Prissättning för Azure Data Explorer.

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

Skapa en databas i det nya Kusto-klustret (med hjälp av klusternamnet ovan och på samma plats). Den här databasen används för att lagra kontextualiserade Azure Digital Twins-data. Kommandot nedan skapar en databas med en mjuk borttagningsperiod på 365 dagar och en frekvent cacheperiod på 31 dagar. Mer information om tillgängliga alternativ för det här kommandot finns i az kusto database create.

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 tvillingegenskap, händelser för tvillinglivscykel respektive relationslivscykelhändelser. Mer information om dessa typer av historiserade data och deras motsvarande Azure Data Explorer-tabeller finns i Datatyper och scheman.

Använd kommandot i det här avsnittet för att skapa en datahistorikanslutning och tabellerna i Azure Data Explorer. Kommandot skapar alltid en tabell för historiserade tvillingegenskapshändelser och innehåller parametrar för att skapa tabellerna för relationslivscykel- och tvillinglivscykelhändelser.

Kommentar

Som standard förutsätter det här kommandot att alla resurser finns i samma resursgrupp som Azure Digital Twins-instansen. Du kan ange resurser som finns i olika resursgrupper med hjälp av parameteralternativen för det här kommandot.

Kommandot nedan använder lokala variabler som skapades tidigare i Konfigurera lokala variabler för CLI-session och har flera parametrar, inklusive...

  • Namnen på tabellerna relationslivscykel och tvillinglivscykel i Azure Data Explorer (dessa parametrar är valfria om du inte vill historisera dessa händelsetyper, men krävs om du vill historisera dessa händelsetyper)
  • En valfri parameter för att ange namnet på händelsetabellen för tvillingegenskapen (om det här värdet inte anges får den här tabellen namnet AdtPropertyEvents som standard). Om du inte vill ange ett annat namn tar du bort parametern --adx-property-events-table från kommandot innan du kör den.
  • Den valfria parametern --adx-record-removals för att aktivera historisering för borttagningar av tvillingegenskaper (händelser som tar bort egenskaper helt)
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 kör kommandot ovan får du möjlighet att tilldela de behörigheter som krävs för att konfigurera din datahistorikanslutning åt dig (om du redan har tilldelat de behörigheter som krävs kan du hoppa över de här anvisningarna). Dessa behörigheter beviljas till den hanterade identiteten för din Azure Digital Twins-instans. De minsta nödvändiga rollerna är:

  • Azure Event Hubs-dataägare på händelsehubben
  • Deltagare som är begränsad till minst den angivna databasen (den kan också begränsas till klustret)
  • Databashuvudnamnstilldelning med rolladministratör (för tabellskapande/hantering) som är begränsad till den angivna databasen

För regelbunden dataplansåtgärd kan dessa roller reduceras till en enda Azure Event Hubs Data Sender-roll, om så önskas.

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 framö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.

Kommentar

När anslutningen har konfigurerats resulterar standardinställningarna i Azure Data Explorer-klustret i en svarstid på cirka 10 minuter eller mindre. Du kan minska den här svarstiden genom att aktivera strömningsinmatning (mindre än 10 sekunders svarstid) eller en inmatningsbatchprincip. Mer information om svarstid för inmatning i Azure Data Explorer finns i Svarstid för inmatning från slutpunkt till slutpunkt.

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. Detta inkluderar 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.

Följ anvisningarna nedan för att se till att din datahistorikanslutning ä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 göra detta 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. Screenshot of the option to assign a managed identity to a data connection in the Azure portal.
  4. Nu kan du 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 Azure Data Explorer-klustret får du ett felmeddelande om att tjänsten inte kunde skapa datahistorikanslutningen med meddelandet "Resursen kunde inte AGERA på grund av ett internt serverfel". Datahistorikkonfigurationen misslyckas 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 ska genomgå händelser för tvilling- och relationslivscykel och generera 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ö.

Screenshot of the Azure Digital Twins Data simulator.

Du ser bekräftelsemeddelanden på skärmen när modeller, tvillingar och relationer skapas i din miljö. Detta 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. Detta genererar kontinuerligt uppdateringar av tvillingegenskap som historiseras till 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 genererades 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 Databaser på den vänstra menyn för att öppna databasvyn. Leta reda på databasen som du skapade för den här artikeln och markera kryssrutan bredvid den och välj sedan Fråga.

Screenshot of the Azure portal showing a database in an Azure Data Explorer cluster.

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 relationslivscykelhändelser, en för tvillinglivscykelhändelser och en för uppdateringshändelser för tvillingegenskap. Du använder dessa tabellnamn för att köra frågor i tabellerna för att verifiera och visa historiserade data.

Screenshot of the Azure portal showing the query view for the database. The name of the data history table is highlighted.

Verifiera tabellposter

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 på tabellen relationslivscykelhändelser och ändrar inmatningen för tabellen till batchläge så att den matar in data från livesimuleringen var 10:e 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 ersätt platshållaren med namnet på relationshändelsetabellen. Välj knappen Kör för att köra kommandot.

Screenshot of the Azure portal showing the query view for the database. The Run button is highlighted.

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.

Kommentar

Det kan ta upp till 5 minuter innan den första batchen med inmatade data visas.

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

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

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

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

Utforska uppdateringstabellen för tvillingegenskap

I det här avsnittet ska du göra 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 frågan nedan för att kartlägga utflödet av alla saltmaskintvillingar i Oslo-exempelfabriken. 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 <ADT-instance-host-name> platshållaren med värdnamnet för din instans och <table-name> platshållaren med namnet på tabellen för tvillingegenskapshändelser.

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.

Screenshot of the Azure portal showing the query view for the database.

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. På så sätt 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.

Screenshot of the Azure portal showing an Event Hubs namespace for the simulated environment.

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.