Tutorial: Bereitstellen von Azure Digital Twins (Vorschau) und Konfigurieren eines räumlichen Graphen

Artikel
01/10/2020

Wichtig

Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Aufgrund der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in dieser Dokumentation beschrieben) eingestellt.

Die Dokumentation für den neuen Dienst finden Sie in der aktiven Dokumentation zu Azure Digital Twins.

Mit dem Azure Digital Twins-Dienst (Vorschauversion) können Sie Personen, Orte und Geräte in einem kohärenten räumlichen System zusammenbringen. In dieser Tutorialreihe wird veranschaulicht, wie Sie mit Azure Digital Twins die Raumbelegung mit optimalen Temperatur- und Luftqualitätsbedingungen ermitteln.

In den Tutorials wird anhand einer .NET-Konsolenanwendung Schritt für Schritt erläutert, wie Sie ein Szenario für ein Bürogebäude erstellen. Das Gebäude hat mehrere Etagen und Räume auf jeder Etage. Die Räume sind mit Geräten mit angeschlossenen Sensoren zur Erkennung von Bewegungen, der Umgebungstemperatur und der Luftqualität ausgestattet.

Sie erfahren, wie Sie die physischen Bereiche und Entitäten im Gebäude mit dem Azure Digital Twins-Dienst als digitale Objekte replizieren. Mit einer weiteren Konsolenanwendung simulieren Sie Geräteereignisse. Anschließend erfahren Sie, wie Sie die Ereignisse in diesen physischen Bereichen und Entitäten nahezu in Echtzeit überwachen.

Anhand dieser Informationen kann ein Büroadministrator den im Gebäude tätigen Mitarbeitern dabei helfen, Besprechungsräume mit optimalen Bedingungen zu buchen. Ein Facility-Manager des Bürogebäudes kann mithilfe Ihres Setups Trends bei der Nutzung der Räume erkennen und Arbeitsbedingungen zu Wartungszwecken überwachen.

Im ersten Tutorial dieser Reihe lernen Sie Folgendes:

Bereitstellen von Digital Twins
Gewähren von Berechtigungen für Ihre App
Ändern einer Digital Twins-Beispiel-App
Bereitstellen Ihres Gebäudes

In diesen Tutorials werden die Beispiele aus Quickstart: Find available rooms (Schnellstart: Ermitteln von verfügbaren Räumen) verwendet und geändert, um die Konzepte ausführlicher zu erläutern.

Voraussetzungen

Ein Azure-Abonnement. Falls Sie noch kein Azure-Konto besitzen, erstellen Sie ein kostenloses Konto.
Das .NET Core SDK. Die Azure Digital Twins-Beispiele in diesen Tutorials sind in C# geschrieben. Zum Erstellen und Ausführen des Beispiels müssen Sie .NET Core SDK Version 2.1.403 oder höher auf dem Entwicklungscomputer installieren. Überprüfen Sie, ob die richtige Version auf Ihrem Computer installiert ist, indem Sie dotnet --version in einem Befehlsfenster ausführen.
Visual Studio Code zum Untersuchen des Beispielcodes.

Bereitstellen von Azure Digital Twins

Erstellen Sie anhand der Schritte in diesem Abschnitt eine neue Instanz des Azure Digital Twins-Diensts. Pro Abonnement kann nur eine Instanz erstellt werden. Fahren Sie mit dem nächsten Abschnitt fort, wenn Sie bereits über eine Instanz verfügen.

Melden Sie sich beim Azure-Portal an.
Wählen Sie die Startseitenleiste und dann + Ressource erstellen aus.
Suchen Sie nach Digital Twins, und wählen Sie Digital Twins aus.

Wählen Sie alternativ Internet der Dinge und dann Digital Twins (Vorschauversion) aus.
Wählen Sie Erstellen aus, um den Bereitstellungsprozess zu starten.
Geben Sie im Bereich Digital Twins die folgenden Informationen ein:
- Ressourcenname: Erstellen Sie einen eindeutigen Namen für Ihre Digital Twins-Instanz.
- Abonnement: Wählen Sie das Abonnement aus, das Sie zum Erstellen dieser Digital Twins-Instanz verwenden möchten.
- Ressourcengruppe: Hier können Sie eine Ressourcengruppe für die Digital Twins-Instanz auswählen oder erstellen.
- Standort: Wählen Sie den nächstgelegenen Standort zu Ihren Geräten aus.
Überprüfen Sie Ihre Informationen zu Digital Twins, und wählen Sie Erstellen aus. Die Erstellung Ihrer Digital Twins-Instanz kann einige Minuten dauern. Sie können den Fortschritt im Bereich Benachrichtigungen überwachen.
Öffnen Sie den Bereich Übersicht Ihrer Digital Twins-Instanz. Beachten Sie den Link unter Verwaltungs-API. Die URL der Verwaltungs-API ist wie folgt formatiert:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
Mit dieser URL gelangen Sie zur Dokumentation zur Azure Digital Twins-REST-API, die für Ihre Instanz gilt. Lesen Sie Verwenden von Digital Twins Swagger, um zu erfahren, wie diese API-Dokumentation zu lesen und zu verwenden ist. Kopieren und ändern Sie die URL der Verwaltungs-API in dieses Format:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
Ihre Anwendung verwendet die geänderte URL als Basis-URL für den Zugriff auf Ihre Instanz. Kopieren Sie diese geänderten URL in eine temporäre Datei. Sie wird im nächsten Abschnitt benötigt.

Gewähren von Berechtigungen für Ihre App

Digital Twins verwendet Azure Active Directory (Azure AD), um den Lese-/Schreibzugriff auf den Dienst zu steuern. Jede Anwendung, die eine Verbindung mit Ihrer Digital Twins-Instanz herstellen muss, muss in Azure AD registriert werden. In diesem Abschnitt wird erläutert, wie Sie Ihre Beispiel-App registrieren.

Falls Sie bereits über eine App-Registrierung verfügen, können Sie sie für das Beispiel wiederverwenden. Sie sollten diesen Abschnitt aber trotzdem kurz durchlesen, um sicherzustellen, dass Ihre App-Registrierung korrekt konfiguriert ist.

Hinweis

Dieser Abschnitt enthält Anweisungen für die Azure AD-App-Registrierung.

Öffnen Sie im Azure-Portal im erweiterbaren Menü auf der linken Seite Azure Active Directory und anschließend den Bereich App-Registrierungen.
Wählen Sie die Schaltfläche + Neue Registrierung aus.
Geben Sie im Feld Name einen Anzeigenamen für diese App-Registrierung ein.
1. Geben Sie im Abschnitt Umleitungs-URI (optional) den Wert https://microsoft.com ins Textfeld ein.
2. Überprüfen Sie, welche Konten und Mandanten von Ihrer Azure Active Directory-App unterstützt werden.
3. Wählen Sie Registrieren.
Auf dem Blatt Authentifizierung sind wichtige Konfigurationseinstellungen für die Authentifizierung angegeben.
1. Fügen Sie Umleitungs-URIs hinzu, und konfigurieren Sie Zugriffstoken, indem Sie + Plattform hinzufügen auswählen.
2. Wählen Sie Ja aus, um anzugeben, dass die App ein öffentlicher Client ist.
3. Überprüfen Sie, welche Konten und Mandanten von Ihrer Azure Active Directory-App unterstützt werden.
Konfigurieren Sie nach der Auswahl der geeigneten Plattform die Umleitungs-URIs und Zugriffstoken im Seitenpanel rechts auf der Benutzeroberfläche.
1. Umleitungs-URIs müssen mit der in der Authentifizierungsanforderung angegebenen Adresse übereinstimmen:
  - Wählen Sie für Anwendungen, die in einer lokalen Entwicklungsumgebung gehostet werden, Öffentlicher Client (Mobilgerät und Desktop) aus. Stellen Sie sicher, dass Öffentlicher Client auf Ja festgelegt ist.
  - Wählen Sie für in Azure App Service gehostete Einzelseiten-Apps Web aus.
2. Legen Sie fest, ob eine Abmelde-URL geeignet ist.
3. Aktivieren Sie den Ablauf für die implizite Genehmigung, indem Sie die Option Zugriffstoken oder ID-Token aktivieren.
Klicken Sie auf Konfigurieren und dann auf Speichern.
Öffnen Sie den Bereich Übersicht Ihrer registrierten App, und kopieren Sie die Werte der folgenden Entitäten in eine temporäre Datei. Mit diesen Werten konfigurieren Sie in den folgenden Abschnitten Ihre Beispielanwendung.
- Anwendungs-ID (Client)
- Verzeichnis-ID (Mandant)
Öffnen Sie den Bereich API-Berechtigungen für Ihre App-Registrierung. Wählen Sie die Schaltfläche + Berechtigung hinzufügen aus. Wählen Sie im Bereich API-Berechtigungen anfordern die Registerkarte Von meiner Organisation verwendete APIs aus, und suchen Sie nach einer der folgenden Optionen:
1. Azure Digital Twins. Wählen Sie die API Azure Digital Twins aus.
2. Oder suchen Sie nach Azure Smart Spaces Service. Wählen Sie die API Azure Smart Spaces Service aus.
Wichtig

Welcher Name und welche ID für die Azure AD-API angezeigt werden, richtet sich nach Ihrem Mandanten:
- Bei Testmandanten- und Kundenkonten sollte nach Azure Digital Twins gesucht werden.
- Bei anderen Microsoft-Konten sollte nach Azure Smart Spaces Service gesucht werden.
Die ausgewählte API wird als Azure Digital Twins im gleichen Bereich (API-Berechtigungen anfordern) angezeigt. Wählen Sie die Dropdownoption Lesen aus, und aktivieren Sie anschließend das Kontrollkästchen Read.Write. Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.
Je nach Einstellungen Ihrer Organisation müssen Sie möglicherweise zusätzliche Schritte unternehmen, um dem Administrator Zugriff auf diese API zu gewähren. Weitere Informationen erhalten Sie von Ihrem Administrator. Nach Genehmigung des Administratorzugriffs werden Ihre Berechtigungen im Bereich API-Berechtigungen in der Spalte Administratoreinwilligung erforderlich angezeigt:

Vergewissern Sie sich, dass Azure Digital Twins angezeigt wird.

Konfigurieren des Digital Twins-Beispiels

In diesem Abschnitt wird die Konfiguration einer Azure Digital Twins-Anwendung erläutert, die mit den Digital Twins-REST-APIs kommuniziert.

Herunterladen des Beispiels

Wenn Sie die Beispiele für Quickstart: Find available rooms (Schnellstart: Ermitteln verfügbarer Räume) bereits heruntergeladen haben, können Sie diese Schritte überspringen.

Laden Sie die .NET-Beispiele für Digital Twins herunter.
Extrahieren Sie den Inhalt des ZIP-Ordners auf Ihrem Computer.

Untersuchen des Beispiels

Öffnen Sie im extrahierten Ordner die Datei digital-twins-samples-csharp\digital-twins-samples.code-workspace in Visual Studio Code. Das Beispiel umfasst zwei Projekte:

Mit dem Bereitstellungsbeispiel occupancy-quickstart können Sie einen Raumintelligenzgraphen konfigurieren und bereitstellen. Bei diesem Graphen handelt es sich um das digitalisierte Abbild Ihrer physischen Gebäudebereiche und der darin enthaltenen Ressourcen. Im Beispiel wird ein Objektmodell verwendet, das Objekte für ein intelligentes Gebäude definiert. Eine vollständige Liste der Digital Twins-Objekte und -REST-APIs finden Sie in der REST-API-Dokumentation oder unter der Verwaltungs-API-URL, die für Ihre Instanz erstellt wurde.

Um die Beispielanwendung zu untersuchen und herauszufinden, wie sie mit Ihrer Digital Twins-Instanz kommuniziert, können Sie mit dem Ordner src\actions beginnen. Die Dateien in diesem Ordner implementieren die Befehle, die Sie in diesen Tutorials verwenden werden:
- Die Datei provisionSample.cs zeigt, wie Sie Ihren Raumgraphen bereitstellen.
- Die Datei getSpaces.cs ruft Informationen zu den bereitgestellten Gebäudebereichen ab.
- Die Datei getAvailableAndFreshSpaces.cs ruft die Ergebnisse einer benutzerdefinierten Funktion ab.
- Die Datei createEndpoints.cs erstellt Endpunkte für die Interaktion mit anderen Diensten.
Das Simulationsbeispiel device-connectivity simuliert Sensordaten und sendet diese an den für Ihre Digital Twins-Instanz bereitgestellten IoT-Hub. Sie verwenden dieses Beispiel im nächsten Tutorial, nachdem Sie den Raumgraphen bereitgestellt haben. Die zum Konfigurieren des Beispiels verwendeten Sensor- und Gerätebezeichner sollten mit den Bezeichnern identisch sein, die Sie zum Bereitstellen Ihres Graphen verwenden.

Konfigurieren des Bereitstellungsbeispiels

Öffnen Sie ein Befehlsfenster, und navigieren Sie zum heruntergeladenen Beispiel. Führen Sie den folgenden Befehl aus:
```
cd occupancy-quickstart/src
```
Stellen Sie die Abhängigkeiten im Beispielprojekt wieder her, indem Sie den folgenden Befehl ausführen:
```
dotnet restore
```
Öffnen Sie in Visual Studio Code die Datei appSettings.json des Projekts occupancy-quickstart. Ändern Sie die folgenden Werte:
- ClientId: Geben Sie die Anwendungs-ID Ihrer Azure AD-App-Registrierung ein. Diese ID haben Sie sich im Abschnitt zum Festlegen der App-Berechtigungen notiert.
- Tenant: Geben Sie die Verzeichnis-ID Ihres Azure AD-Mandanten ein. Diese ID haben Sie sich ebenfalls im Abschnitt zum Festlegen der App-Berechtigungen notiert.
- BaseUrl: Geben Sie die URL Ihrer Digital Twins-Instanz ein. Diese URL erhalten Sie, indem Sie die Platzhalter in der folgenden URL durch die Werte für Ihre Instanz ersetzen: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Alternativ können Sie die Verwaltungs-API-URL aus dem Abschnitt zur Bereitstellung ändern, um die URL zu erhalten. Ersetzen Sie swagger/ durch api/v1.0/.
Sehen Sie sich eine Liste der Digital Twins-Funktionen an, die Sie mithilfe des Beispiels erkunden können. Führen Sie den folgenden Befehl aus:
```
dotnet run
```

Grundlegendes zum Bereitstellungsprozess

In diesem Abschnitt wird erläutert, wie mit dem Beispiel ein Raumgraph eines Gebäudes bereitgestellt wird.

Navigieren Sie in Visual Studio Code zum Ordner occupancy-quickstart\src\actions, und öffnen Sie Datei provisionSample.cs. Beachten Sie die folgende Funktion:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Diese Funktion verwendet die Datei provisionSample.yaml im selben Ordner. Öffnen Sie diese Datei. Dort sehen Sie die Hierarchie eines Bürogebäudes: Venue (Ort), Floor (Etage), Area (Bereich) und Rooms (Räume). Jeder dieser physischen Gebäudebereiche kann devices(Geräte) und sensors (Sensoren) enthalten. Jeder Eintrag verfügt über einen vordefinierten typeEintrag, z. B. Floor, Room.

Die YAML-Beispieldatei zeigt einen Raumgraphen mit dem Digital Twins-Objektmodell Default. Dieses Modell stellt allgemeine Namen für die meisten Typen bereit. Allgemeine Namen sind für ein Gebäude ausreichend. Beispiele sind „Temperature“ für „SensorDataType“ und „Map“ für „SpaceBlobType“. Ein Beispielbereichstyp ist „Room“ mit den Untertypen „FocusRoom“, „ConferenceRoom“ usw.

Zum Erstellen eines Raumgraphen für eine andere Art von Ort (z. B. eine Fabrik) benötigen Sie möglicherweise ein anderes Objektmodell. Sie können die verfügbaren Modelle anzeigen, indem Sie den Befehl dotnet run GetOntologies in der Befehlszeile für das Bereitstellungsbeispiel ausführen.

Weitere Informationen zu Raumgraphen und den Objektmodellen finden Sie unter Grundlegendes zum Digital Twins-Objektmodell und zum Raumintelligenzgraphen.

Ändern des Beispielraumgraphen

Die Datei provisionSample.yaml enthält die folgenden Knoten:

resources: Der Knoten resources erstellt eine Azure IoT Hub-Ressource für die Kommunikation mit den Geräten in Ihrem Setup. Ein IoT-Hub im Stammknoten des Graphen kann mit allen Geräten und Sensoren in Ihrem Graphen kommunizieren.
spaces: Im Digital Twins-Objektmodell stellen spaces (Gebäudebereiche) die physischen Orte dar. Jeder Raum verfügt über eine Type- z. B. Region, Veranstaltungsort oder Kunde - und einen benutzerfreundlichen Name. Gebäudebereiche können zu anderen Gebäudebereichen gehören, sodass eine hierarchische Struktur entsteht. Die Datei „provisionSample.yaml“ enthält einen Raumgraphen für ein imaginäres Gebäude. Beachten Sie die logische Schachtelung von Gebäudebereichen des Typs Floor innerhalb von Venue, von Area innerhalb einer Etage und von Room-Knoten in einem Bereich.
devices: Gebäudebereiche können devices (Geräte) enthalten. Dies sind physische oder virtuelle Entitäten, die eine Reihe von Sensoren verwalten. Ein Gerät kann beispielsweise das Telefon eines Benutzers, ein Raspberry Pi-Sensorpod oder ein Gateway sein. Im imaginären Gebäude im Beispiel enthält der Raum namens Focus Room ein Gerät Raspberry Pi 3 A1. Jeder Geräteknoten wird durch eine eindeutige hardwareId identifiziert, die in diesem Beispiel hartcodiert ist. Ersetzen Sie diese Werte durch die Werte aus Ihrem Setup, um das Beispiel für eine reale Produktionsumgebung zu konfigurieren.
sensors: Ein Gerät kann mehrere sensors (Sensoren) enthalten. Sie können physische Änderungen wie Temperatur, Bewegung und Akkustand erkennen und aufzeichnen. Jeder Sensorknoten wird durch eine hardwareId eindeutig identifiziert, die hier hartcodiert ist. Ersetzen Sie diese IDs für eine reale Anwendung durch die eindeutigen Bezeichner der Sensoren in Ihrem Setup. Die Datei „provisionSample.yaml“ enthält zwei Sensoren zum Aufzeichnen von Motion (Bewegung) und CarbonDioxide (Kohlendioxid). Fügen Sie einen weiteren Sensor zum Aufzeichnen der Temperature (Temperatur) hinzu, indem Sie die folgenden Zeilen unterhalb der Zeilen für den CarbonDioxide-Sensor hinzufügen. Diese werden in der Datei „provisionSample.yaml“ als auskommentierte Zeilen angegeben. Sie können ihre Kommentierung aufheben, indem Sie jeweils das Zeichen # am Zeilenanfang entfernen.
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
Hinweis

Stellen Sie sicher, dass die Schlüssel dataType und hardwareId den Anweisungen über diesem Codeausschnitt entsprechen. Vergewissern Sie sich außerdem, dass Ihr Editor Leerzeichen nicht durch Tabstopps ersetzt.

Speichern und schließen Sie die Datei „provisionSample.yaml“. Im nächsten Tutorial fügen Sie dieser Datei weitere Informationen hinzu, und anschließend stellen Sie Ihr Azure Digital Twins-Beispielgebäude bereit.

Tipp

Sie können Ihren Raumgraphen mithilfe des Azure Digital Twins Graph Viewer anzeigen und ändern.

Bereinigen von Ressourcen

Falls Sie sich nicht weiter mit Azure Digital Twins befassen möchten, können Sie die in diesem Tutorial erstellten Ressourcen löschen:

Wählen Sie im Azure-Portal im Menü auf der linken Seite Alle Ressourcen und Ihre Digital Twins-Ressourcengruppe aus, und klicken Sie auf Löschen.

Tipp

Für den Fall, dass bei Ihnen Probleme beim Löschen der Digital Twins-Instanz aufgetreten sind, wurde ein Dienstupdate mit einer entsprechenden Korrektur bereitgestellt. Versuchen Sie erneut, die Instanz zu löschen.
Löschen Sie ggf. die Beispielanwendung auf Ihrem Arbeitscomputer.

Nächste Schritte

Im nächsten Tutorial dieser Reihe erfahren Sie, wie Sie eine benutzerdefinierte Logik zum Überwachen von Bedingungen in Ihrem Beispielgebäude implementieren.

Tutorial: Bereitstellen des Gebäudes und Überwachen der Arbeitsbedingungen