Gegevensgeschiedenis van Azure Digital Twins (met Azure Data Explorer)

Gegevensgeschiedenis is een integratiefunctie van Azure Digital Twins. Hiermee kunt u een Azure Digital Twins-exemplaar verbinden met een Azure Data Explorer-cluster , zodat grafiekupdates automatisch worden historiseerd naar Azure Data Explorer. Deze historized updates omvatten updates van dubbele eigenschappen, levenscyclusgebeurtenissen van dubbels en levenscyclusgebeurtenissen voor relaties.

Zodra grafiekupdates zijn historiseerd naar Azure Data Explorer, kunt u gezamenlijke query's uitvoeren met behulp van de Azure Digital Twins-invoegtoepassing voor Azure Data Explorer om redeneren over digitale dubbels, hun relaties en tijdreeksgegevens. Dit kan worden gebruikt om terug te kijken naar wat de status van de grafiek was of om inzicht te krijgen in het gedrag van gemodelleerde omgevingen. Je kunt deze query's ook gebruiken om operationele dashboards aan te sturen, 2D- en 3D-webtoepassingen te verrijken en augmented/mixed reality-ervaringen te realiseren om de huidige en historische status van assets, processen en personen die zijn gemodelleerd in Azure Digital Twins over te brengen.

Bekijk de volgende IoT-showvideo voor meer informatie over gegevensgeschiedenis, inclusief een korte demo:

Berichten die door de gegevensgeschiedenis worden verzonden, worden gemeten onder de dimensie Berichtprijzen.

Vereisten: Resources en machtigingen

Voor gegevensgeschiedenis zijn de volgende resources vereist:

Deze resources zijn verbonden met de volgende stroom:

Diagram showing the flow of device telemetry data into Azure Digital Twins, through an event hub, to Azure Data Explorer.

Wanneer de digitale dubbelgrafiek wordt bijgewerkt, wordt de informatie via de Event Hub doorgegeven aan het Azure Data Explorer-doelcluster, waarbij Azure Data Explorer de gegevens opslaat als een tijdstempelrecord in de bijbehorende tabel.

Wanneer u met gegevensgeschiedenis werkt, is het raadzaam om de versie 2023-01-31 of hoger van de API's te gebruiken. Met de versie 2022-05-31 kunnen alleen dubbeleigenschappen (niet de levenscyclus van dubbels of levenscyclusgebeurtenissen van relaties) worden historized. Met eerdere versies is de gegevensgeschiedenis niet beschikbaar.

Vereiste machtigingen

Als u een gegevensgeschiedenisverbinding wilt instellen, moet uw Azure Digital Twins-exemplaar over de volgende machtigingen beschikken om toegang te krijgen tot de Event Hubs- en Azure Data Explorer-resources. Met deze rollen kan Azure Digital Twins namens u de Event Hub en de Azure Data Explorer-database configureren (bijvoorbeeld het maken van een tabel in de database). Deze machtigingen kunnen eventueel worden verwijderd nadat de gegevensgeschiedenis is ingesteld.

  • Event Hubs-resource: Azure Event Hubs-gegevenseigenaar
  • Azure Data Explorer-cluster: Inzender (beperkt tot het hele cluster of de specifieke database)
  • Toewijzing van azure Data Explorer-database-principal: Beheer (gericht op de database die wordt gebruikt)

Later moet uw Azure Digital Twins-exemplaar de volgende machtiging hebben voor de Event Hubs-resource terwijl de gegevensgeschiedenis wordt gebruikt: Azure Event Hubs-gegevenszender (u kunt er ook voor kiezen om azure Event Hubs-gegevenseigenaar te houden uit de installatie van de gegevensgeschiedenis).

Deze machtigingen kunnen worden toegewezen met behulp van de Azure CLI of Azure Portal.

Als u de netwerktoegang wilt beperken tot de resources die betrokken zijn bij de gegevensgeschiedenis (uw Azure Digital Twins-exemplaar, Event Hub of Azure Data Explorer-cluster), moet u deze beperkingen instellen nadat u de gegevensgeschiedenisverbinding hebt ingesteld. Zie Netwerktoegang tot gegevensgeschiedenisresources beperken voor meer informatie over dit proces.

Gegevensgeschiedenisverbinding maken en beheren

Deze sectie bevat informatie voor het maken, bijwerken en verwijderen van een gegevensgeschiedenisverbinding.

Een gegevensgeschiedenisverbinding maken

Zodra alle resources en machtigingen zijn ingesteld, kunt u de Azure CLI, Azure Portal of de Azure Digital Twins SDK gebruiken om de gegevensgeschiedenisverbinding tussen deze resources te maken. De CLI-opdrachtenset is az dt data-history.

Met de opdracht wordt altijd een tabel gemaakt voor gebeurtenissen van historized twin-eigenschappen, die de standaardnaam of een aangepaste naam kunnen gebruiken die u opgeeft. Verwijderingen van dubbele eigenschappen kunnen eventueel worden opgenomen in deze tabel. U kunt ook tabelnamen opgeven voor levenscyclus-gebeurtenissen van relaties en levenscyclus-gebeurtenissen van dubbels. Met de opdracht worden tabellen met deze namen gemaakt om deze gebeurtenistypen te historiseren.

Zie Een gegevensgeschiedenisverbinding maken voor stapsgewijze instructies voor het instellen van een gegevensgeschiedenisverbinding.

Geschiedenis van meerdere Azure Digital Twins-exemplaren

Als u wilt, kunt u meerdere Azure Digital Twins-exemplaren hebben die updates historiseren voor hetzelfde Azure Data Explorer-cluster.

Elk Azure Digital Twins-exemplaar heeft een eigen gegevensgeschiedenisverbinding die gericht is op hetzelfde Azure Data Explorer-cluster. In het cluster kunnen exemplaren hun dubbelgegevens verzenden naar een van beide...

  • een afzonderlijke set tabellen in het Azure Data Explorer-cluster.
  • dezelfde set tabellen in het Azure Data Explorer-cluster. Hiervoor geeft u dezelfde Azure Data Explorer-tabelnamen op tijdens het maken van de gegevensgeschiedenisverbindingen. In de schema's van de gegevensgeschiedenistabel bevat de ServiceId kolom in elke tabel de URL van het Azure Digital Twins-bronexemplaren, zodat u dit veld kunt gebruiken om op te lossen welke Azure Digital Twins-instantie elke record in gedeelde tabellen heeft verzonden.

Een verbinding met alleen-eigenschappen voor gegevensgeschiedenis bijwerken

Vóór februari 2023 wordt de gegevensgeschiedenisfunctie alleen bijgewerkt met historized twin-eigenschappen. Als u vanaf dat moment een verbinding met alleen-eigenschappen voor gegevensgeschiedenis hebt, kunt u deze bijwerken om alle grafiekupdates te historiseren naar Azure Data Explorer (inclusief dubbele eigenschappen, levenscyclusgebeurtenissen van dubbels en levenscyclusgebeurtenissen van relaties).

Hiervoor moet u nieuwe tabellen maken in uw Azure Data Explorer-cluster voor de nieuwe typen historized updates (levenscyclusgebeurtenissen van dubbels en levenscyclusgebeurtenissen voor relaties). Voor gebeurtenissen van dubbele eigenschappen kunt u bepalen of u wilt dat de nieuwe verbinding dezelfde tabel van de oorspronkelijke gegevensgeschiedenisverbinding blijft gebruiken om updates van de eigenschappen van dubbels in de toekomst op te slaan, of als u wilt dat de nieuwe verbinding een volledig nieuwe set tabellen gebruikt. Volg vervolgens de onderstaande instructies voor uw voorkeur.

Als u de bestaande tabel wilt blijven gebruiken voor updates van eigenschappen van dubbels: gebruik de instructies in Een gegevensgeschiedenisverbinding maken om een nieuwe gegevensgeschiedenisverbinding te maken met de nieuwe mogelijkheden. De naam van de verbinding met de gegevensgeschiedenis kan hetzelfde zijn als de oorspronkelijke naam of een andere naam. Gebruik de parameteropties om nieuwe namen op te geven voor de twee nieuwe gebeurtenistypetabellen en om de oorspronkelijke tabelnaam door te geven voor de tabel met updates van de tweelingeigenschap. De nieuwe verbinding overschrijft de oude en blijft de oorspronkelijke tabel gebruiken voor toekomstige updates van historized twin-eigenschappen.

Als u alle nieuwe tabellen wilt gebruiken: verwijder eerst de oorspronkelijke gegevensgeschiedenisverbinding. Gebruik vervolgens de instructies in Een gegevensgeschiedenisverbinding maken om een nieuwe gegevensgeschiedenisverbinding te maken met de nieuwe mogelijkheden. De naam van de verbinding met de gegevensgeschiedenis kan hetzelfde zijn als de oorspronkelijke naam of een andere naam. Gebruik de parameteropties om nieuwe namen op te geven voor alle drie de gebeurtenistypetabellen.

Een gegevensgeschiedenisverbinding verwijderen

U kunt de Azure CLI, Azure Portal of Azure Digital Twins-API's en SDK's gebruiken om een gegevensgeschiedenisverbinding te verwijderen. De CLI-opdracht is az dt data-history connection delete.

Als u een verbinding verwijdert, kunt u ook resources opschonen die zijn gekoppeld aan de verbinding met de gegevensgeschiedenis (voor de CLI-opdracht is de optionele parameter die u wilt toevoegen --clean true). Als u deze optie gebruikt, worden met de opdracht de resources in Azure Data Explorer verwijderd die worden gebruikt om uw cluster te koppelen aan uw Event Hub, inclusief gegevensverbindingen voor de database en de opnametoewijzingen die aan uw tabel zijn gekoppeld. Met de optie Resources opschonen worden de werkelijke Event Hub en het Azure Data Explorer-cluster dat wordt gebruikt voor de verbinding met de gegevensgeschiedenis niet verwijderd.

Het opschonen is een best effort-poging en vereist dat het account waarop de opdracht wordt uitgevoerd, machtigingen voor verwijderen heeft voor deze resources.

Notitie

Als u meerdere gegevensgeschiedenisverbindingen hebt die hetzelfde Event Hub- of Azure Data Explorer-cluster delen, kan het verwijderen van een van deze verbindingen uw andere gegevensgeschiedenisverbindingen verstoren die afhankelijk zijn van deze resources.

Gegevenstypen en schema's

Gegevensgeschiedenis historiseert drie soorten gebeurtenissen van uw Azure Digital Twins-exemplaar in Azure Data Explorer: levenscyclusgebeurtenissen van relaties, levenscyclusgebeurtenissen van dubbels en updates van dubbele eigenschappen (die eventueel verwijderingen van dubbele eigenschappen kunnen bevatten). Elk van deze gebeurtenistypen wordt opgeslagen in een eigen tabel in de Azure Data Explorer-database, wat betekent dat de gegevensgeschiedenis drie tabellen in totaal bewaart. U kunt aangepaste namen voor de tabellen opgeven wanneer u de verbinding met de gegevensgeschiedenis instelt.

In de rest van deze sectie worden de drie Azure Data Explorer-tabellen gedetailleerd beschreven, inclusief het gegevensschema voor elke tabel.

Updates van eigenschappen van dubbels

De Azure Data Explorer-tabel voor updates van dubbeleigenschappen heeft een standaardnaam van AdtPropertyEvents. U kunt de standaardnaam laten staan wanneer u de verbinding maakt of een aangepaste tabelnaam opgeven.

De tijdreeksgegevens voor updates van eigenschappen van dubbels worden opgeslagen met het volgende schema:

Kenmerk Type Description
TimeStamp Datum en tijd De datum/tijd waarop het bericht over het bijwerken van de eigenschap is verwerkt door Azure Digital Twins. Dit veld wordt ingesteld door het systeem en kan niet worden geschreven door gebruikers.
SourceTimeStamp Datum en tijd Een optionele, beschrijfbare eigenschap die de tijdstempel aangeeft toen de eigenschapsupdate werd waargenomen in de echte wereld. Deze eigenschap kan alleen worden geschreven met de versie 2022-05-31 van de Azure Digital Twins-API's/SDK's en de waarde moet voldoen aan de iso 8601-datum- en tijdnotatie. Zie De brontijd van een eigenschap bijwerken voor meer informatie over het bijwerken van deze eigenschap.
ServiceId String De service-exemplaar-id van de Azure IoT-service die de record registreert
Id String De tweeling-id
ModelId String De DTDL-model-id (DTMI)
Key String De naam van de bijgewerkte eigenschap
Value Dynamisch De waarde van de bijgewerkte eigenschap
RelationshipId String Wanneer een eigenschap die is gedefinieerd voor een relatie (in tegenstelling tot tweelingen of apparaten) wordt bijgewerkt, wordt dit veld gevuld met de id van de relatie. Wanneer een eigenschap van een dubbel wordt bijgewerkt, is dit veld leeg.
RelationshipTarget String Wanneer een eigenschap die is gedefinieerd voor een relatie (in tegenstelling tot tweelingen of apparaten) wordt bijgewerkt, wordt dit veld gevuld met de dubbel-id van de dubbel waarop de relatie is gericht. Wanneer een eigenschap van een dubbel wordt bijgewerkt, is dit veld leeg.
Action String Deze kolom bestaat alleen als u ervoor kiest om gebeurtenissen voor het verwijderen van eigenschappen te historiseren. Als dit het geval is, bevat deze kolom het type eigenschapsevenement van de dubbel (bijwerken of verwijderen)

Hieronder ziet u een voorbeeldtabel met updates van dubbeleigenschappen die zijn opgeslagen in 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 Uitvoer 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 Uitvoer 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 Uitvoer 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 Uitvoer 123

Eigenschappen weergeven met meerdere velden

Mogelijk moet u een eigenschap met meerdere velden opslaan. Deze eigenschappen worden weergegeven met een JSON-object in het Value kenmerk van het schema.

Als u bijvoorbeeld een eigenschap vertegenwoordigt met drie velden voor roll, pitch en yaw, worden in de gegevensgeschiedenis het volgende JSON-object opgeslagen als : Value. {"roll": 20, "pitch": 15, "yaw": 45}

Levenscyclus-gebeurtenissen van dubbels

De Azure Data Explorer-tabel voor levenscyclusgebeurtenissen van dubbels heeft een aangepaste naam die u opgeeft bij het maken van de gegevensgeschiedenisverbinding.

De tijdreeksgegevens voor levenscyclus-gebeurtenissen van dubbels worden opgeslagen met het volgende schema:

Kenmerk Type Omschrijving
TwinId String De tweeling-id
Action String Het type levenscyclus van dubbels (maken of verwijderen)
TimeStamp Datum en tijd De datum/tijd waarop de levenscyclusgebeurtenis van de dubbel is verwerkt door Azure Digital Twins. Dit veld wordt ingesteld door het systeem en kan niet worden geschreven door gebruikers.
ServiceId String De service-exemplaar-id van de Azure IoT-service die de record registreert
ModelId String De DTDL-model-id (DTMI)

Hieronder ziet u een voorbeeldtabel met updates voor de levenscyclus van dubbels die zijn opgeslagen in Azure Data Explorer.

TwinId Action TimeStamp ServiceId ModelId
PasteurizationMachine_A01 Create 2022-12-15 07:14:12.4160 dairyadtinstance.api.wcus.digitaltwins.azure.net dtmi:assetGen:PasteurizationMachine;1
PasteurizationMachine_A02 Create 2022-12-15 07:14:12.4210 dairyadtinstance.api.wcus.digitaltwins.azure.net dtmi:assetGen:PasteurizationMachine;1
SaltMachine_C0 Create 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

Levenscyclus-gebeurtenissen voor relaties

De Azure Data Explorer-tabel voor levenscyclusgebeurtenissen van relaties heeft een aangepaste naam die u opgeeft bij het maken van de gegevensgeschiedenisverbinding.

De tijdreeksgegevens voor levenscyclus-gebeurtenissen voor relaties worden opgeslagen met het volgende schema:

Kenmerk Type Omschrijving
RelationshipId String De relatie-id. Dit veld wordt ingesteld door het systeem en kan niet worden geschreven door gebruikers.
Name String De naam van de relatie
Action Het type levenscyclus van relaties (maken of verwijderen)
TimeStamp Datum en tijd De datum/tijd waarop de levenscyclusgebeurtenis van de relatie is verwerkt door Azure Digital Twins. Dit veld wordt ingesteld door het systeem en kan niet worden geschreven door gebruikers.
ServiceId De service-exemplaar-id van de Azure IoT-service die de record registreert
Source De id van de brondubbel. Dit is de id van de tweeling waar de relatie vandaan komt.
Target De id van de doeldubbel. Dit is de id van de tweeling waar de relatie binnenkomt.

Hieronder ziet u een voorbeeldtabel met updates voor de levenscyclus van relaties die zijn opgeslagen in Azure Data Explorer.

RelationshipId Name Action TimeStamp ServiceId Source Target
PasteurizationMachine_A01_feeds_Relationship0 Feeds Create 2022-12-15 07:16:12.7120 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A01 SaltMachine_C0
PasteurizationMachine_A02_feeds_Relationship0 Feeds Create 2022-12-15 07:16:12.7160 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A02 SaltMachine_C0
PasteurizationMachine_A03_feeds_Relationship0 Feeds Create 2022-12-15 07:16:12.7250 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A03 SaltMachine_C1
OsloFactory_contains_Relationship0 bevat Delete 2022-12-15 07:16:13.1780 dairyadtinstance.api.wcus.digitaltwins.azure.net OsloFactory SaltMachine_C0

End-to-end opnamelatentie

De gegevensgeschiedenis van Azure Digital Twins is gebaseerd op het bestaande opnamemechanisme van Azure Data Explorer. Azure Digital Twins zorgt ervoor dat gebeurtenissen voor het bijwerken van grafieken binnen twee seconden beschikbaar worden gesteld aan Azure Data Explorer. Er kan extra latentie worden geïntroduceerd door Azure Data Explorer die de gegevens opneemt.

Er zijn twee methoden in Azure Data Explorer voor het opnemen van gegevens: batchopname en streamingopname. U kunt deze opnamemethoden configureren voor afzonderlijke tabellen op basis van uw behoeften en het specifieke scenario voor gegevensopname.

Streamingopname heeft de laagste latentie. Vanwege de verwerkingsoverhead mag deze modus echter alleen worden gebruikt als er elk uur minder dan 4 GB aan gegevens wordt opgenomen. Batchopname werkt het beste als er hoge opnamegegevenssnelheden worden verwacht. Azure Data Explorer maakt standaard gebruik van batchopname. De volgende tabel bevat een overzicht van de verwachte slechtste end-to-end latentie:

Configuratie van Azure Data Explorer Verwachte end-to-endlatentie Aanbevolen gegevenssnelheid
Stroomopname <12 sec (<standaard 3 sec) <4 GB per uur
Batchopname Varieert (12 sec-15 m, afhankelijk van de configuratie) >4 GB per uur

De rest van deze sectie bevat details voor het inschakelen van elk type opname.

Batchopname (standaard)

Als dit niet zo is geconfigureerd, gebruikt Azure Data Explorer batchopname. De standaardinstellingen kunnen ertoe leiden dat gegevens slechts 5-10 minuten na het uitvoeren van een update naar een digitale dubbel beschikbaar zijn voor query's. Het opnamebeleid kan worden gewijzigd, zodat de batchverwerking maximaal om de 10 seconden plaatsvindt (minimaal of maximaal 15 minuten). Als u het opnamebeleid wilt wijzigen, moet de volgende opdracht worden uitgegeven in de Azure Data Explorer-queryweergave:

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

Zorg ervoor dat deze <table_name> wordt vervangen door de naam van de tabel die voor u is ingesteld. MaximumBatchingTimeSpan moet worden ingesteld op het voorkeursinterval voor batchverwerking. Het kan 5-10 minuten duren voordat het beleid van kracht wordt. Meer informatie over opnamebatches vindt u op de volgende koppeling: Kusto IngestionBatching-beleidsbeheeropdracht.

Stroomopname

Het inschakelen van streamingopname is een proces in twee stappen:

  1. Streamingopname inschakelen voor uw cluster. Deze actie hoeft slechts eenmaal te worden uitgevoerd. (Waarschuwing: Dit heeft gevolgen voor de hoeveelheid opslagruimte die beschikbaar is voor hot cache en kan extra beperkingen veroorzaken). Zie Streaming-opname configureren in uw Azure Data Explorer-cluster voor instructies.
  2. Voeg een streamingopnamebeleid toe voor de gewenste tabel. Meer informatie over het inschakelen van streaming-opname voor uw cluster vindt u in de documentatie van Azure Data Explorer: opdracht Kusto IngestionBatching-beleidsbeheer.

Als u streamingopname voor uw Azure Digital Twins-gegevensgeschiedenistabel wilt inschakelen, moet de volgende opdracht worden uitgegeven in het queryvenster van Azure Data Explorer:

.alter table <table_name> policy streamingingestion enable 

Zorg ervoor dat deze <table_name> wordt vervangen door de naam van de tabel die voor u is ingesteld. Het kan 5-10 minuten duren voordat het beleid van kracht wordt.

Historized eigenschappen visualiseren

Azure Digital Twins Explorer, een hulpprogramma voor ontwikkelaars voor het visualiseren en gebruiken van Azure Digital Twins-gegevens, biedt een functie voor gegevensgeschiedenisverkenner voor het bekijken van historized eigenschappen in een grafiek of een tabel. Deze functie is ook beschikbaar in 3D Scenes Studio, een meeslepende 3D-omgeving voor het geven van Azure Digital Twins de visuele context van 3D-assets.

Screenshot of data history explorer for 3D Scenes Studio.

Zie Historized eigenschappen valideren en verkennen voor meer informatie over het gebruik van de gegevensgeschiedenisverkenner.

Notitie

Als u problemen ondervindt bij het selecteren van een eigenschap in de ervaring van visual data history Explorer, kan dit betekenen dat er een fout optreedt in een bepaald model in uw exemplaar. Als u bijvoorbeeld niet-unieke enumwaarden in de kenmerken van een model hebt, wordt deze visualisatiefunctie verbroken. Als dit gebeurt, controleert u de modeldefinities en controleert u of alle eigenschappen geldig zijn.

Volgende stappen

Zodra dubbelgegevens zijn ge historiseerd naar Azure Data Explorer, kunt u de Azure Digital Twins-queryinvoegtoepassing voor Azure Data Explorer gebruiken om query's uit te voeren op de gegevens. Lees hier meer over de invoegtoepassing: Query's uitvoeren met de Azure Data Explorer-invoegtoepassing.

U kunt ook dieper ingaan op de gegevensgeschiedenis met instructies voor het maken en een voorbeeldscenario: Een gegevensgeschiedenisverbinding maken.