Tutorial: Erstellen eines Azure Digital Twins-Graphen unter Verwendung Beispielclient-App

In diesem Tutorial wird in Azure Digital Twins ein Graph mit Modellen, Zwillingen und Beziehungen erstellt. Als Tool wird in diesem Tutorial eine exemplarische Befehlszeilenclientanwendung für die Interaktion mit einer Azure Digital Twins-Instanz verwendet. Die Client-App ähnelt der App die in Kodieren einer Client-Appgeschrieben wurde.

Sie können dieses Beispiel verwenden, um grundlegende Azure Digital Twins-Aktionen auszuführen, etwa Hochladen von Modellen, Erstellen und Ändern von Zwillingen und Erstellen von Beziehungen. Sie können sich auch den Code des Beispiels ansehen, um mehr über die Azure Digital Twins-APIs zu erfahren, und die Implementierung eigener Befehle üben, indem Sie das Beispielprojekt wunschgemäß anpassen.

In diesem Tutorial lernen Sie Folgendes:

Voraussetzungen

Vergewissern Sie sich vor Beginn dieses Tutorials zuerst, ob folgende Voraussetzungen erfüllt sind:

• Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
• In diesem Tutorial wird .NET verwendet. Sie können die aktuelle Version des .NET Core SDK für verschiedene Plattformen unter Download .NET herunterladen.

Fahren Sie dann mit dem Rest dieses Abschnitts fort, um die verbleibenden Voraussetzungen einzurichten.

Abrufen von Beispielressourcen

Grundlage des Tutorials ist ein in C# geschriebenes Beispielprojekt End-to-End-Beispielprojekt für Azure Digital Twins. Laden Sie das Beispielprojekt auf Ihren Computer herunter, indem Sie zum Beispiellink navigieren und unter dem Titel die Schaltfläche Code durchsuchen auswählen.

Dadurch gelangen Sie zum GitHub-Repository für die Beispiele, die Sie als ZIP-Datei herunterladen können. Wählen Sie hierzu die Schaltfläche Code und anschließend ZIP herunterladen aus.

Dadurch wird ein ZIP-Ordner (digital-twins-samples-main.zip) auf Ihren Computer heruntergeladen. Entpacken Sie den Ordner, und extrahieren Sie die Dateien.

Vorbereiten einer Azure Digital Twins-Instanz

Damit Sie in diesem Artikel mit Azure Digital Twins arbeiten können, benötigen Sie eine Azure Digital Twins-Instanz und die erforderlichen Berechtigungen, um sie zu verwenden. Wenn Sie über eine bereits eingerichtete Azure Digital Twins-Instanz verfügen, können Sie diese nutzen und zum nächsten Abschnitt springen. Befolgen Sie andernfalls die Anleitung unter Einrichten einer Instanz und der Authentifizierung. Die Anweisungen enthalten Informationen, mit denen Sie überprüfen können, ob jeder Schritt erfolgreich abgeschlossen wurde.

Notieren Sie sich nach dem Einrichten Ihrer Instanz den Hostnamen der Instanz. Sie finden den Hostnamen im Azure-Portal.

Konfigurieren des Beispielprojekts

Richten Sie als Nächstes eine Beispielclient-Anwendung ein, die mit Ihrer Azure Digital Twins-Instanz interagiert.

Navigieren Sie auf Ihrem Computer zum Ordner, den Sie zuvor von Azure Digital Twins-End-to-End-Beispiele heruntergeladen haben (und entpacken Sie ihn, sofern noch nicht geschehen).

Sobald Sie sich im Ordner befinden, navigieren Sie zu digital-twins-samples-main\AdtSampleApp\SampleClientApp und öffnen die Datei appsettings.json. Diese JSON-Datei enthält eine Konfigurationsvariable, die zum Ausführen des Projekts erforderlich ist.

Ändern Sie im Dateitext die instanceUrl in die Hostnamen-URL der Azure Digital Twins-Instanz (indem Sie https:// vor dem Hostnamen einfügen, wie nachfolgend gezeigt).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Speichern und schließen Sie die Datei.

Einrichten lokaler Azure-Anmeldeinformationen

Dieses Beispiel verwendet DefaultAzureCredential (Teil der Azure.Identity-Bibliothek) zur Authentifizierung von Benutzern mit der Azure Digital Twins-Instanz, wenn Sie diese auf Ihrem lokalen Computer ausführen. Weitere Informationen zu den verschiedenen Möglichkeiten, wie sich eine Client-App bei Azure Digital Twins authentifizieren kann, finden Sie unter Schreiben von App-Authentifizierungscode.

Mit DefaultAzureCredential sucht das Beispiel nach Anmeldeinformationen in Ihrer lokalen Umgebung, wie eine Azure-Anmeldung in einer lokalen DefaultAzureCredential oder in Visual Studio oder Visual Studio Code. Aus diesem Grund sollten Sie sich lokal über einen dieser Mechanismen bei Azure anmelden, um Anmeldeinformationen für das Beispiel einzurichten.

Wenn Sie Visual Studio oder Visual Studio Code zum Ausführen von Codebeispielen verwenden, stellen Sie sicher, dass Sie bei diesem Editor mit denselben Anmeldeinformationen für Azure angemeldet sind, die Sie für den Zugriff auf Ihre Instanz von Azure Digital Twins verwenden möchten. Wenn Sie ein lokales CLI-Fenster verwenden, führen Sie den Befehl az login aus, um sich bei Ihrem Azure-Konto anzumelden. Wenn Sie danach Ihr Codebeispiel ausführen, sollten Sie automatisch authentifiziert werden.

Ausführen des Beispielprojekts

Nachdem die App und die Authentifizierung festgelegt sind, öffnen Sie ein lokales Konsolenfenster, das Sie zum Ausführen des Projekts verwenden werden. Navigieren Sie in der Konsole zum Ordner digital-twins-samples-main\AdtSampleApp\SampleClientApp, und führen Sie das Projekt mit diesem dotnet-Befehl aus:

dotnet run

Das Projekt wird ausgeführt, führt eine Authentifizierung durch und wartet auf einen Befehl.

Hier sehen Sie einen Screenshot der Projektkonsole:

Nachdem Sie sich vergewissert haben, dass die App erfolgreich ausgeführt wird, können Sie die Ausführung des Projekts beenden. Sie werden es später in diesem Tutorial erneut ausführen.

Modellieren einer physischen Umgebung mit DTDL

Nachdem die Azure Digital Twins-Instanz und die Beispiel-App eingerichtet sind, können Sie mit der Erstellung eines Szenariographen beginnen.

Beim Erstellen einer Azure Digital Twins-Lösung werden zunächst Zwillingsmodelle für Ihre Umgebung definiert.

Modelle sind vergleichbar mit Klassen in objektorientierten Programmiersprachen. Es handelt sich um benutzerdefinierte Vorlagen, die Sie instanziieren können, um digitale Zwillinge zu erstellen. Modelle für Azure Digital Twins werden in einer JSON-ähnlichen Sprache namens Digital Twins Definition Language (DTDL) geschrieben und definieren einen Zwillingstyp in Bezug auf seine Eigenschaften, Beziehungen und Komponenten.

Navigieren Sie im Ordner des Beispielprojekts, den Sie zuvor heruntergeladen haben, in den Ordner digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models. Dieser Ordner enthält Beispielmodelle.

Öffnen Sie Room.json zur Bearbeitung, und nehmen Sie die folgenden Änderungen am Code vor:

1. Aktualisieren Sie die Versionsnummer, um anzugeben, dass Sie eine aktualisierte Version dieses Modells bereitstellen. Ändern Sie hierzu 1 am Ende des Werts @id in 2. Jede Zahl, die größer als die aktuelle Versionsnummer ist, funktioniert ebenfalls.

2. Bearbeiten Sie eine Eigenschaft. Ändern Sie den Namen der Humidity-Eigenschaft in HumidityLevel (oder einen anderen gewünschten Namen). Wenn Sie einen anderen Namen als HumidityLevel verwenden, merken Sie diesen, und verwenden Sie ihn im gesamten weiteren Tutorial anstelle von HumidityLevel.

3. Fügen Sie eine Eigenschaft hinzu. Fügen Sie unterhalb der Eigenschaft HumidityLevel, die in Zeile 15 endet, den folgenden Code ein, um dem Raum eine Eigenschaft vom Typ RoomName hinzuzufügen:

   ,{
     "@type": "Property",
     "name": "RoomName",
     "schema": "string"
   }
   

4. Fügen Sie eine Beziehung hinzu. Fügen Sie unterhalb der soeben hinzugefügten Eigenschaft RoomName den folgenden Code ein, um dieser Art von Zwilling die Möglichkeit zu geben, Beziehungen vom Typ contains mit anderen Zwillingen zu erstellen:

   ,{
     "@type": "Relationship",
     "name": "contains"
   }
   

Wenn Sie fertig sind, sollte das aktualisierte Modell wie folgt aussehen:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Achten Sie darauf, die Datei vor dem Fortfahren zu speichern.

Hochladen von Modellen in Azure Digital Twins

Nach dem Entwerfen von Modellen müssen Sie diese in Ihre Azure Digital Twins-Instanz hochladen. Dadurch wird die Azure Digital Twins-Dienstinstanz mit Ihrem eigenen benutzerdefinierten Domänenvokabular konfiguriert. Nach dem Hochladen der Modelle können Sie Zwillingsinstanzen erstellen, die diese verwenden.

1. Kehren Sie zu Ihrem Konsolenfenster zurück, indem der Ordner digital-twins-samples-main\AdtSampleApp\SampleClientApp geöffnet ist, und führen Sie die Konsolen-App erneut mit dotnet run aus.

2. Führen Sie im Projektkonsolenfenster den folgenden Befehl aus, um das aktualisierte Room-Modell zusammen mit einem Floor-Modell hochzuladen, das Sie auch im nächsten Abschnitt verwenden, um unterschiedliche Arten von Zwillingen zu erstellen.

   CreateModels Room Floor
   

   In der Ausgabe sollte die erfolgreiche Erstellung der Modelle angegeben sein.

3. Vergewissern Sie sich, dass die Modelle erstellt wurden, indem Sie den Befehl GetModels true ausführen. Dieser Befehl gibt die vollständigen Informationen für alle Modelle aus, die in Ihre Azure Digital Twins-Instanz hochgeladen wurden. Suchen Sie in den Ergebnissen nach dem bearbeiteten Room-Modell:

   

Lassen Sie die Konsolen-App für die nächsten Schritte ausgeführt.

Errors

Die Beispielanwendung verarbeitet auch Fehler des Diensts.

Um dies zu testen, führen Sie den Befehl CreateModels erneut aus und versuchen Sie, das bereits hochgeladene Room-Modell erneut hochzuladen:

CreateModels Room

Da Modelle nicht überschrieben werden können, gibt dieser Befehl jetzt einen Dienstfehler zurück, der angibt, dass einige der Modell-IDs, die Sie erstellen möchten, bereits vorhanden sind.

Ausführliche Informationen zum Löschen von vorhandenen Modellen finden Sie unter Verwalten von DTDL-Modellen.

Erstellen digitaler Zwillinge

Sie haben einige Modelle in Ihre Azure Digital Twins-Instanz hochgeladen und können nun basierend auf den Modelldefinitionen digitale Zwillinge erstellen. Digitale Zwillinge stellen die Entitäten in Ihrer Geschäftsumgebung dar, etwa Sensoren in einer Farm, Räume in einem Gebäude oder Beleuchtung in einem Fahrzeug.

Zum Erstellen eines digitalen Zwillings verwenden Sie den Befehl CreateDigitalTwin. Sie müssen auf das Modell verweisen, auf dem der Zwilling basiert, und können optional Anfangswerte für Eigenschaften im Modell definieren. Sie müssen in dieser Phase keine Beziehungsinformationen übergeben.

1. Führen Sie diesen Code in der ausgeführten Projektkonsole aus, um mehrere Zwillinge basierend auf dem zuvor aktualisierten Room-Modell und dem Floor-Modell zu erstellen. Denken Sie daran, dass „Room“ drei Eigenschaften hat, sodass Sie Argumente mit den Anfangswerten für diese Eigenschaften angeben können. (Die Initialisierung von Eigenschaftswerten ist grundsätzlich optional, für dieses Tutorial werden sie allerdings benötigt.)

   CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
   CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
   CreateDigitalTwin dtmi:example:Floor;1 floor0
   CreateDigitalTwin dtmi:example:Floor;1 floor1
   

   In der Ausgabe dieser Befehle sollte die erfolgreiche Erstellung der Zwillinge angegeben sein.

   

2. Führen Sie den Befehl Query aus, um sich zu vergewissern, dass die Zwillinge erstellt wurden. Mit diesem Befehl werden alle digitalen Zwillinge der Azure Digital Twins-Instanz abgefragt. Suchen Sie in den Ergebnissen nach den Zwillingen room0, room1, floor0 und floor1.

Ändern eines digitalen Zwillings

Sie können auch die Eigenschaften eines von Ihnen erstellten Zwillings ändern.

1. Führen Sie den folgenden Befehl aus, um den RoomName-Wert für „room0“ von „Room0“ in „PresidentialSuite“ zu ändern:

   UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
   

   In der Ausgabe sollte die erfolgreiche Aktualisierung des Zwillings angegeben sein.

2. Sie können den folgenden Befehl ausführen, um die Informationen zu room0 anzuzeigen und sich zu vergewissern, dass die Aktualisierung erfolgreich war:

   GetDigitalTwin room0
   

   In der Ausgabe sollte der aktualisierte Name angezeigt werden.

Erstellen eines Graphen durch Hinzufügen von Beziehungen

Im nächsten Schritt können Sie einige Beziehungen zwischen diesen Zwillingen erstellen, um Sie in einem Zwillingsgraphen zu verbinden. Zwillingsgraphen werden verwendet, um eine gesamte Umgebung darzustellen.

Die Arten von Beziehungen, die Sie zwischen Zwillingen erstellen können, werden in den zuvor hochgeladenen Modellen definiert. In der Modelldefinition für „Floor“ ist angegeben, dass Etagen eine Beziehung vom Typ contains haben können. Dies ermöglicht die Erstellung einer Beziehung vom Typ contains zwischen jedem Etagenzwilling (Floor) und dem entsprechenden enthaltenen Raum.

Verwenden Sie zum Hinzufügen einer Beziehung den Befehl CreateRelationship. Geben Sie den Zwilling, von dem die Beziehung ausgeht, die Art der Beziehung sowie den Zwilling an, mit dem die Beziehung hergestellt wird. Geben Sie abschließend eine eindeutige ID für die Beziehung an.

1. Führen Sie die folgenden Befehle aus, um eine Beziehung vom Typ contains von jedem der zuvor erstellten Etagenzwillinge zu einem entsprechenden Raumzwilling hinzuzufügen. Die Beziehungen heißen relationship0 und relationship1.

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Tipp

   Da die Beziehung vom Typ contains im Modell „Floor“ mit zwei Zeichenfolgeneigenschaften (ownershipUser und ownershipDepartment) definiert wurde, können Sie beim Erstellen der Beziehungen auch Argumente mit den Anfangswerten für diese Eigenschaften angeben. Hier sehen Sie eine alternative Version des obigen Befehls zum Erstellen von relationship0, bei der auch Anfangswerte für diese Eigenschaften angegeben werden:

   CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
   

   Die Ausgabe dieser Befehle bestätigt, dass die Beziehungen erfolgreich erstellt wurden:

   

2. Sie können die Beziehungen mithilfe einer der folgenden Befehle zum Ausgeben der Beziehungen in der Azure Digital Twins-Instanz überprüfen.

   • So zeigen Sie alle Beziehungen an, die von den einzelnen Etagen ausgehen (Anzeige der Beziehungen von einer Seite):

     GetRelationships floor0
     GetRelationships floor1
     

   • So zeigen Sie alle Beziehungen an, die bei jedem Raum ankommen (Anzeige der Beziehungen von der anderen Seite):

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • So können Sie sich diese Beziehungen einzeln (nach ID) ansehen:

     GetRelationship floor0 relationship0
     GetRelationship floor1 relationship1
     

Die Zwillinge und Beziehungen, die Sie in diesem Tutorial eingerichtet haben, bilden den folgenden konzeptionellen Graphen:

Abfragen des Zwillingsgraphen zum Beantworten von Umgebungsfragen

Eine Hauptfunktion von Azure Digital Twins ist das einfache Abfragen des Zwillingsgraphen und das effiziente Beantworten von Fragen zur Umgebung.

Führen Sie in der ausgeführten Projektkonsole die folgenden Befehle aus, um einige Fragen zur Beispielumgebung zu beantworten.

1. Welche Entitäten aus meiner Umgebung werden in Azure Digital Twins dargestellt? (Abfrage aller Elemente)

   Query
   

   Mit diesem Befehl können Sie schnell eine Bestandsaufnahme Ihrer Umgebung machen und sicherstellen, dass in Azure Digital Twins alles wunschgemäß dargestellt wird. Das Ergebnis dieses Befehls ist eine Ausgabe, die jeden digitalen Zwilling mit seinen Details enthält. Auszug:

   

   Tipp

   Im Beispielprojekt entspricht der Befehl Query ohne zusätzliche Argumente Query SELECT * FROM DIGITALTWINS. Wenn Sie alle Zwillinge in Ihrer Instanz mithilfe der Abfrage-APIs oder der CLI-Befehle abfragen möchten, verwenden Sie die längere (vollständige) Abfrage.

2. Welche Räume sind in meiner Umgebung vorhanden? (Abfrage nach Modell)

   Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
   

   Sie können Ihre Abfrage auf Zwillinge eines bestimmten Typs beschränken, um spezifischere Informationen zu den dargestellten Elementen zu erhalten. Im Ergebnis werden „room0“ und „room1“, aber nicht „floor0“ oder „floor1“ angezeigt (da es sich dabei um Etagen und nicht um Räume handelt).

   

3. Welche Räume befinden sich auf floor0? (Abfrage nach Beziehung)

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
   

   Sie können Abfragen basierend auf den Beziehungen in Ihrem Graphen durchführen, um Informationen zu den Beziehungen zwischen Zwillingen zu erhalten oder um die Abfrage auf einen bestimmten Bereich zu beschränken. Auf floor0 befindet sich nur room0, daher ist dies der einzige Raum im Ergebnis.

   

4. Welche Zwillinge in meiner Umgebung haben eine Temperatur über 75? (Abfrage nach Eigenschaft)

   Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
   

   Sie können den Graphen auf der Grundlage von Eigenschaften abfragen, um eine Vielzahl von Fragen zu beantworten. Dazu zählt auch das Auffinden von Ausreißern in Ihrer Umgebung, die möglicherweise Ihre Aufmerksamkeit erfordern. Andere Vergleichsoperatoren (<, >, = oder !=) werden ebenfalls unterstützt. room1 wird hier in den Ergebnissen angezeigt, da die Temperatur 80 beträgt.

   

5. Welche Räume auf floor0 haben eine Temperatur über 75? (Verbundabfrage)

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
   

   Sie können die Abfragen oben auch wie in SQL mithilfe von Kombinationsoperatoren (etwa AND, OR, NOT) kombinieren. Diese Abfrage verwendet AND, um die vorherige Abfrage der Zwillingstemperatur spezifischer zu gestalten. Das Ergebnis enthält jetzt nur noch Räume mit einer Temperatur von über 75, die sich auf floor0 befinden – in diesem Fall kein Raum. Das Resultset ist leer.

   

Nachdem Sie mehrere Abfragen zu dem von Ihnen festgelegten Szenario ausgeführt haben, ist das Tutorial abgeschlossen. Beenden Sie die Ausführung des Projekts, und schließen Sie das Konsolenfenster.

Bereinigen von Ressourcen

Nach Abschluss dieses Tutorials können Sie die zu entfernenden Ressourcen auswählen, abhängig davon, wie Sie weiter vorgehen möchten.

• Wenn Sie mit dem nächsten Tutorial fortfahren möchten, können Sie die hier eingerichteten Ressourcen behalten, um diese Azure Digital Twins-Instanz und die konfigurierte Beispiel-App für das nächste Tutorial zu verwenden.

• Wenn Sie die Azure Digital Twins-Instanz weiterhin verwenden, aber alle ihre Modelle, Zwillinge und Beziehungen entfernen möchten, können Sie die Befehle DeleteAllTwins und DeleteAllModels der Beispiel-App verwenden, um die Zwillinge und Modelle in Ihrer Instanz zu löschen.

• Wenn Sie die in diesem Tutorial erstellten Ressourcen nicht benötigen, können Sie die Azure Digital Twins-Instanz und alle anderen Ressourcen in diesem Artikel mithilfe des CLI-Befehls az group delete löschen. Dadurch werden alle Azure-Ressourcen in einer Ressourcengruppe sowie die Ressourcengruppe selbst gelöscht.

  Wichtig

  Das Löschen einer Ressourcengruppe kann nicht rückgängig gemacht werden. Die Ressourcengruppe und alle darin enthaltenen Ressourcen werden unwiderruflich gelöscht. Achten Sie daher darauf, dass Sie nicht versehentlich die falsche Ressourcengruppe oder die falschen Ressourcen löschen.

  Öffnen Sie Azure Cloud Shell oder ein lokales CLI-Fenster, und führen Sie den folgenden Befehl aus, um die Ressourcengruppe und alle darin enthaltenen Elemente zu löschen.

  az group delete --name <your-resource-group>
  

Möglicherweise möchten Sie auch den Ordner des heruntergeladenen Projekts von Ihrem lokalen Computer löschen.

Nächste Schritte

In diesem Tutorial haben Sie die ersten Schritte mit Azure Digital Twins durchgeführt, indem Sie unter Verwendung einer Beispielclientanwendung einen Graphen in Ihrer Instanz erstellt haben. Sie haben Modelle, digitale Zwillinge und Beziehungen erstellt, um einen Graphen zu erstellen. Darüber hinaus haben Sie einige Abfragen für den Graphen ausgeführt, um eine Vorstellung davon zu erhalten, welche Arten von Fragen Azure Digital Twins zu einer Umgebung beantworten kann.

Im nächsten Tutorial wird eine Kombination aus Azure Digital Twins und anderen Azure-Diensten in einem datengesteuerten End-to-End-Szenario verwendet: