Erstellen einer Datenverlaufsverbindung für Azure Digital Twins

Der Datenverlauf ist ein Azure Digital Twins-Feature zum automatischen Historisieren von Diagrammupdates für Azure Data Explorer. Diese Daten können mithilfe des Azure Digital Twins-Abfrage-Plug-Ins für Azure Data Explorer abgefragt werden, um Erkenntnisse über Ihre Umgebung im Laufe der Zeit zu erhalten.

In diesem Artikel wird gezeigt, wie Sie eine funktionierende Datenhistorienverbindung zwischen Azure Digital Twins und Azure Data Explorer einrichten. Es verwendet die Azure CLI und das Azure-Portal , um die erforderlichen Datenverlaufsressourcen einzurichten und zu verbinden, einschließlich:

• eine Azure Digital Twins-Instanz
• ein Event Hubs-Namespace mit einem Event Hub
• Ein Azure Data Explorer-Cluster, der eine Datenbank enthält

Es enthält auch ein Beispiel-Twin-Diagramm, mit dem Sie die historisierten Diagrammaktualisierungen im Azure-Daten-Explorer anzeigen können.

Voraussetzungen

Vorbereiten der Umgebung für die Azure CLI

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Erste Schritte mit Azure Cloud Shell.

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie mit Windows oder macOS arbeiten, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

  • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Um den Authentifizierungsprozess abzuschließen, führen Sie die schritte aus, die in Ihrem Terminal angezeigt werden. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe der Azure CLI.

  • Wenn Sie dazu aufgefordert werden, installieren Sie die Azure CLI-Erweiterung bei der ersten Verwendung. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden und Verwalten von Erweiterungen mit der Azure CLI.

  • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um auf die neueste Version zu aktualisieren.

Einrichten einer CLI-Sitzung

Um mit Azure Digital Twins in der CLI zu arbeiten, müssen Sie sich zunächst anmelden und den CLI-Kontext für diese Sitzung auf Ihr Abonnement festlegen. Führen Sie diese Befehle in Ihrem CLI-Fenster aus:

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

Wenn Sie dieses Abonnement zum ersten Mal mit Azure Digital Twins verwenden, führen Sie den folgenden Befehl aus, um sich beim Azure Digital Twins-Namespace zu registrieren. (Wenn Sie nicht sicher sind, ist es in Ordnung, es erneut auszuführen, auch wenn Sie es in der Vergangenheit irgendwann ausgeführt haben.)

az provider register --namespace 'Microsoft.DigitalTwins'

Als Nächstes fügen Sie die Microsoft Azure IoT-Erweiterung für Azure CLI hinzu, um Befehle für die Interaktion mit Azure Digital Twins und anderen IoT-Diensten zu aktivieren. Führen Sie den folgenden Befehl aus, um sicherzustellen, dass Sie über die neueste Version der Erweiterung verfügen:

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

Jetzt können Sie mit Azure Digital Twins in der Azure CLI arbeiten.

Sie können diesen Status überprüfen, indem Sie jederzeit az dt --help ausführen, um eine Liste der verfügbaren Azure Digital Twins-Befehle auf höchster Ebene zu sehen.

Einrichten lokaler Variablen für CLI-Sitzung

Dieser Artikel enthält CLI-Befehle, mit denen Sie die Datenverlaufsressourcen erstellen können. Um später ein einfaches Kopieren und Ausführen dieser Befehle zu ermöglichen, können Sie jetzt lokale Variablen in Ihrer CLI-Sitzung einrichten und später dann in den CLI-Befehlen auf diese Variablen verweisen, wenn Sie Ihre Ressourcen erstellen. Um die Variablen zu erstellen, aktualisieren Sie die Platzhalter (identifiziert mit <...> Klammern) in den folgenden Befehlen, und führen Sie dann die Befehle aus. Achten Sie darauf, die in den Kommentaren beschriebenen Benennungsregeln zu befolgen. Diese Werte werden später beim Erstellen der neuen Ressourcen verwendet.

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

Erstellen einer Azure Digital Twins-Instanz mit einer verwalteten Identität

Wenn Sie bereits über eine Azure Digital Twins-Instanz verfügen, stellen Sie sicher, dass Sie dafür eine vom System zugewiesene verwaltete Identität aktivieren.

Wenn Sie nicht über eine Azure Digital Twins-Instanz verfügen, befolgen Sie die Anweisungen unter Erstellen der Instanz mit einer verwalteten Identität , um eine Azure Digital Twins-Instanz mit einer vom System zugewiesenen verwalteten Identität zum ersten Mal zu erstellen.

Stellen Sie dann sicher, dass Sie über die Rolle "Azure Digital Twins Data Owner " in der Instanz verfügen. Anweisungen finden Sie unter Einrichten von Benutzerzugriffsberechtigungen.

Wenn Sie ihren lokalen CLI-Variablen den Namen Ihrer Instanz hinzufügen möchten, damit sie automatisch an spätere Befehle angeschlossen werden kann, die aus diesem Artikel kopiert wurden, speichern Sie sie wie folgt in der Variablen dtname :

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

Erstellen eines Event Hubs-Namespaces und eines Event Hubs

Der nächste Schritt besteht darin, einen Event Hubs-Namespace und einen Event Hub zu erstellen. Dieser Hub empfängt Graph-Lebenszyklus- und Eigenschaftsaktualisierungsbenachrichtigungen von der Azure Digital Twins-Instanz und leitet dann die Nachrichten an den Ziel-Azure Data Explorer-Cluster weiter.

Im Rahmen der späteren Einrichtung der Datenverlaufverbindung gewähren Sie der Azure-Digital-Twins-Instanz die Rolle Azure Event Hubs Data Owner auf der Event-Hub-Ressource.

Weitere Informationen zu Event Hubs und deren Funktionen finden Sie in der Dokumentation zu 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

Erstellen eines Kusto-Clusters und einer Datenbank (Azure Data Explorer)

Erstellen Sie als Nächstes einen Kusto(Azure Data Explorer)-Cluster und eine Datenbank, um die Daten von Azure Digital Twins zu empfangen.

Im Rahmen der späteren Einrichtung der Datenverlaufsverbindung gewähren Sie der Azure Digital Twins-Instanz mindestens die Rolle Mitwirkender (kann auch für den Cluster festgelegt werden) und die Rolle Admin für die Datenbank.

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

Einrichtung einer Datenhistorieverbindung

Nachdem Sie nun die erforderlichen Ressourcen erstellt haben, verwenden Sie den Befehl in diesem Abschnitt, um eine Datenverlaufsverbindung zwischen der Azure Digital Twins-Instanz, dem Event Hub und dem Azure Data Explorer-Cluster zu erstellen.

Mit diesem Befehl werden auch drei Tabellen in Ihrer Azure Data Explorer-Datenbank erstellt, um Eigenschaftenupdates von Zwillingen, Beziehungslebenszyklusereignisse und Ereignisse des Zwillingslebenszyklus zu speichern. Weitere Informationen zu diesen Arten von historisierten Daten und den entsprechenden Azure Data Explorer-Tabellen finden Sie unter Datentypen und Schemas.

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

Nach dem Einrichten der Datenverlaufsverbindung können Sie optional die Rollen entfernen, die Ihrer Azure Digital Twins-Instanz für den Zugriff auf die Event Hubs- und Azure Data Explorer-Ressourcen gewährt wurden. Um den Datenverlauf zu verwenden, ist die einzige Rolle, die die Instanz benötigt, Azure Event Hubs Data Sender (oder eine höhere Rolle, die diese Berechtigungen beinhaltet, wie z. B. Azure Event Hubs Data Owner) auf der Event Hubs-Ressource.

Einschränken des Netzwerkzugriffs auf Datenverlaufsressourcen

Wenn Sie den Netzwerkzugriff auf die ressourcen einschränken möchten, die im Datenverlauf beteiligt sind (Ihre Azure Digital Twins-Instanz, Event Hub oder Azure Data Explorer-Cluster), sollten Sie diese Einschränkungen festlegen, nachdem Sie die Datenverlaufsverbindung eingerichtet haben. Diese Einschränkungen umfassen das Deaktivieren des lokalen Zugriffs für Ihre Ressourcen unter anderem zur Verringerung des Netzwerkzugriffs.

Um sicherzustellen, dass Ihre Datenverlaufsressourcen miteinander kommunizieren können, sollten Sie auch die Datenverbindung für die Azure Data Explorer-Datenbank so ändern, dass eine vom System zugewiesene verwaltete Identität verwendet wird.

Führen Sie die folgenden Schritte aus, um sicherzustellen, dass ihre Datenverlaufsverbindung ordnungsgemäß eingerichtet ist, wenn Ihre Ressourcen einen reduzierten Netzwerkzugriff benötigen:

1. Stellen Sie sicher, dass die lokale Autorisierung für Ihre Datenverlaufsressourcen aktiviert ist (Ihre Azure Digital Twins-Instanz, Event Hub und Azure Data Explorer-Cluster)
2. Erstellen einer Datenverlaufsverbindung
3. Aktualisieren Sie die Datenverbindung für die Azure Data Explorer-Datenbank, um eine vom System zugewiesene verwaltete Identität zu verwenden. Im Azure-Portal können Sie die Datenverbindung aktualisieren, indem Sie zum Azure Data Explorer-Cluster navigieren und Datenbanken im Menü verwenden, um zur Datenverlaufsdatenbank zu navigieren. Wählen Sie im Datenbankmenü "Datenverbindungen" aus. Im Tabelleneintrag für Ihre Datenverlaufsverbindung sollte die Option zum Zuweisen verwalteter Identität angezeigt werden, in der Sie "System zugewiesen" auswählen können.
4. Sie können jetzt die lokale Autorisierung deaktivieren oder andere Netzwerkeinschränkungen für Ihre gewünschten Ressourcen festlegen, indem Sie die Zugriffseinstellungen für Ihre Azure Digital Twins-Instanz, den Event Hub oder den Azure Data Explorer-Cluster ändern.

Problembehandlung bei der Verbindungseinrichtung

Im Folgenden finden Sie einige häufige Fehler, die beim Einrichten einer Datenverlaufsverbindung auftreten können, und wie Sie diese beheben.

• Wenn Sie den öffentlichen Netzwerkzugriff für Ihren Azure Data Explorer-Cluster deaktiviert haben, tritt ein Fehler auf: Der Dienst konnte die Datenverlaufsverbindung nicht erstellen. Es erscheint die Meldung "Die Ressource konnte aufgrund eines internen Serverfehlers nicht ACT." Bei deaktiviertem öffentlichen Netzwerkzugriff des Azure Data Explorer-Clusters schlägt das Einrichten des Datenverlaufs fehl, da Azure Digital Twins die Tabellen und andere erforderliche Artefakte nicht konfigurieren kann.
• (CLI-Benutzer) Wenn Sie auf den Fehler "Azure Digital Twins-Instanzverbindungsaufbau konnte nicht erstellt werden" stoßen. In der Datenbank können Tabelle und Zuordnungsregel nicht erstellt werden. Überprüfen Sie Ihre Berechtigungen für den Azure Database Explorer und führen Sie az login aus, um Ihre Anmeldeinformationen zu aktualisieren, beheben Sie den Fehler, indem Sie sich selbst als AllDatabasesAdmin unter "Berechtigungen" in Ihrem Azure Data Explorer-Cluster hinzufügen.
• (Cloud Shell-Benutzer) Wenn Sie die Cloud Shell verwenden und auf den Fehler "Fehler beim Herstellen einer Verbindung mit MSI" stoßen... Stellen Sie sicher, dass MSI ordnungsgemäß konfiguriert ist", versuchen Sie stattdessen, den Befehl mit einer lokalen Azure CLI-Installation auszuführen.

Überprüfen mit einem Beispielzwillingsgraphen

Nachdem Ihre Datenverlaufsverbindung eingerichtet wurde, können Sie sie mit Daten aus Ihren digitalen Zwillingen testen.

Wenn Sie bereits über Zwillinge in Ihrer Azure Digital Twins-Instanz verfügen, die aktiv Graphupdates erhalten (einschließlich Twin-Eigenschaftsaktualisierungen oder Aktualisierungen vom Ändern der Struktur des Diagramms durch Erstellen oder Löschen von Elementen), können Sie diesen Abschnitt überspringen und die Ergebnisse mithilfe Ihrer eigenen Ressourcen visualisieren.

Fahren Sie andernfalls mit diesem Abschnitt fort, um ein Beispieldiagramm einzurichten, das Lebenszyklusereignissen von Zwillings- und Beziehungsmodellen unterzogen wird und Aktualisierungen von Zwillingseigenschaften generiert.

Sie können ein Beispieldiagramm für dieses Szenario mit dem Azure Digital Twins Data Simulator einrichten. Der Azure Digital Twins Data Simulator erstellt Zwillinge und Beziehungen in Ihrer Azure Digital Twins-Instanz und verschiebt kontinuierlich Eigenschaftenaktualisierungen an die Zwillinge.

Erstellen eines Beispieldiagramms

Sie können den Azure Digital Twins Data Simulator verwenden, um ein Beispiel für Twin Graph bereitzustellen und Eigenschaftenupdates darauf zu übertragen. Das hier erstellte Zwillingsdiagramm modelliert Pasteurisierungsprozesse für ein Milchunternehmen.

Öffnen Sie zunächst den Azure Digital Twins Data Simulator in Ihrem Browser. Legen Sie diese Felder fest:

• Instanz-URL: Geben Sie den Hostnamen Ihrer Azure Digital Twins-Instanz ein. Der Hostname befindet sich auf der Portalseite für Ihre Instanz und hat ein Format wie <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net.
• Simulationstyp: Wählen Sie "Milchanlage" aus dem Dropdownmenü aus.

Wählen Sie "Umgebung generieren" aus.

Auf dem Bildschirm werden Bestätigungsmeldungen angezeigt, wenn Modelle, Zwillinge und Beziehungen in Ihrer Umgebung erstellt werden. Dieser Prozess generiert auch Twin- und Relationship Creation-Ereignisse, die für Azure Data Explorer als Twin- bzw. Relationship-Lifecycle-Ereignisse historisiert werden.

Wenn die Simulation bereit ist, wird die Schaltfläche " Simulation starten " aktiviert. Scrollen Sie nach unten, und wählen Sie "Simulation starten " aus, um simulierte Daten an Ihre Azure Digital Twins-Instanz zu übertragen. Um die Zwillinge in Ihrer Azure Digital Twins-Instanz kontinuierlich zu aktualisieren, behalten Sie dieses Browserfenster im Vordergrund auf Dem Desktop und führen Sie andere Browseraktionen in einem separaten Fenster aus. Dieses Fenster erzeugt dauerhaft Ereignisse zur Aktualisierung von Zwillingsmerkmale, die historisch im Azure Data Explorer gespeichert werden.

Anzeigen der historisierten Updates im Azure Data Explorer

In diesem Abschnitt erfahren Sie, wie Sie alle drei Arten von historisierten Updates anzeigen, die vom Simulator generiert und in Azure Data Explorer-Tabellen gespeichert sind.

Starten Sie im Azure-Portal , und navigieren Sie zum Azure Data Explorer-Cluster, den Sie zuvor erstellt haben. Wählen Sie im linken Menü unter "Daten" den Bereich "Abfrage" aus, um die Abfrageansicht zu öffnen.

Erweitern Sie als Nächstes den Cluster und die Datenbank im linken Bereich, um den Namen der Datenverlaufstabellen anzuzeigen. Es sollte drei geben: eines für Twin Property Update-Ereignisse, eines für Beziehungslebenszyklusereignisse und eines für Twin-Lifecycle-Ereignisse. Sie verwenden diese Tabellennamen, um Abfragen für die Tabellen auszuführen, um die historisierten Daten zu überprüfen und anzuzeigen.

Überprüfen von Tabelleneinträgen

Um zu überprüfen, ob Ereignisse in der Datenbank historisiert werden, kopieren Sie zunächst den folgenden Befehl. Es verfügt über einen Platzhalter für den Namen der Tabelle für Beziehungslebenszyklusereignisse und ändert die Aufnahme der Tabelle in den Batchmodus, sodass Daten aus der Livesimulation alle 10 Sekunden aufgenommen werden.

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

Fügen Sie den Befehl in das Abfragefenster ein, und ersetzen Sie den Platzhalter durch den Namen der Beziehungsereignissetabelle. Wählen Sie die Schaltfläche "Ausführen " aus, um den Befehl auszuführen.

Wiederholen Sie den Befehl zweimal, indem Sie den Namen der Tabelle mit den Twin-Lifecycle-Ereignissen verwenden, und aktualisieren Sie dann die Eigenschaftsaktualisierungstabelle , um den Aufnahmemodus der anderen Tabellen zu aktualisieren.

Fügen Sie als Nächstes die folgenden Befehle zum Abfragefenster hinzu, und führen Sie sie aus. Jeder Befehl enthält einen Platzhalter für den Namen einer der Tabellen, und die Befehle geben die Anzahl der Elemente in den Tabellen aus.

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

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

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

Sie sollten in den Ergebnissen sehen, dass die Anzahl der Elemente in jeder Tabelle größer als Null ist. Dies weist darauf hin, dass Aktualisierungen von Eigenschaften, Ereignisse des Beziehungslebenszyklus und des Zwillingslebenszyklus in ihren jeweiligen Tabellen historisiert werden.

Untersuchen Sie die Tabelle der Twin-Eigenschaftsaktualisierungen

In diesem Abschnitt führen Sie einige weitere Erkundungen mit den Eigenschaften-Updates für Zwillinge durch, die in der Tabelle angegeben sind.

Führen Sie zunächst den folgenden Befehl aus, um 100 Datensätze in der Tabelle anzuzeigen:

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

Führen Sie als Nächstes eine Abfrage basierend auf den Daten Ihrer Zwillinge aus, um die kontextbezogenen Datenreihen anzuzeigen.

Verwenden Sie die folgende Abfrage, um den Abfluss aller Salzmaschinen-Zwillinge in der Beispiel-Oslo-Milchfabrik zu erstellen. Diese Kusto-Abfrage verwendet das Azure Digital Twins-Plug-In, um die Zwillinge auszuwählen, verknüpft diese Zwillinge mit der Datenverlaufszeitreihe im Azure Data Explorer und diagrammt dann die Ergebnisse. Ersetzen Sie den <ADT-instance-host-name> Platzhalter unbedingt durch den Hostnamen Ihrer Instanz, und den <table-name> Platzhalter durch den Namen der Tabelle "Twin Property Updates".

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)

Die Ergebnisse sollten die Abflusszahlen darstellen, die sich im Laufe der Zeit ändern.

Verbindungsprobleme beheben

Wenn Im Azure-Daten-Explorer keine Daten angezeigt werden, funktioniert der Historisierungsdatenfluss nicht ordnungsgemäß. Sie können das Problem untersuchen, indem Sie den Event Hubs-Namespace im Azure-Portal anzeigen, in dem Diagramme mit dem Nachrichtenfluss in den Und aus dem Namespace angezeigt werden. Mit dieser Anzeige können Sie sowohl den Fluss eingehender Nachrichten von Azure Digital Twins als auch die ausgehenden Nachrichten an Azure Data Explorer überprüfen, um zu ermitteln, welcher Teil des Flusses nicht funktioniert.

Nächste Schritte

Um das Milchszenario weiterhin zu erkunden, können Sie weitere Beispielabfragen auf GitHub anzeigen, die zeigen, wie Sie die Leistung des Milchbetriebs basierend auf Maschinentyp, Fabrik, Wartungstechniker und verschiedenen Kombinationen dieser Parameter überwachen können.

Um Grafana-Dashboards zu erstellen, die die Leistung des Milchbetriebs visualisieren, lesen Sie das Erstellen von Dashboards mit Azure Digital Twins, Azure Data Explorer und Grafana.

Weitere Informationen zur Verwendung des Azure Digital Twins-Abfrage-Plug-Ins für Azure Data Explorer finden Sie unter Abfragen mit dem Azure Data Explorer-Plug-In und diesem Blogbeitrag. Weitere Informationen zum Plug-In finden Sie hier: Abfragen mit dem Azure Data Explorer-Plug-In.