Schnellstart: Suchen nach verfügbaren Räumen mithilfe von Azure Digital Twins

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 können Sie Ihre physische Umgebung digital abbilden. Anschließend können Sie durch Ereignisse in Ihrer Umgebung benachrichtigt werden und Ihre Reaktionen anpassen.

In diesem Schnellstart wird ein .NET-Beispielpaar verwendet, um ein imaginäres Bürogebäude zu digitalisieren. Er veranschaulicht die Suche nach verfügbaren Räumen in diesem Gebäude. Mit Digital Twins können Sie mehrere Sensoren mit Ihrer Umgebung verknüpfen. Dank eines simulierten CO2-Sensors können Sie auch ermitteln, ob die Luftqualität des verfügbaren Raums gut genug ist. Eine der Beispielanwendungen generiert willkürliche Sensordaten, damit Sie sich das Szenario besser vorstellen können.

Im folgenden Video wird die Schnellstarteinrichtung zusammengefasst:

Voraussetzungen

Sollten Sie kein Azure-Konto haben, erstellen Sie zunächst ein kostenloses Konto.
Die beiden in dieser Schnellstartanleitung ausgeführten Konsolenanwendungen sind in C# geschrieben. Installieren Sie .NET Core SDK Version 2.1.403 oder höher auf dem Entwicklungscomputer. Wenn das .NET Core SDK bereits installiert ist, überprüfen Sie, ob auf Ihrem Entwicklungscomputer die aktuelle Version von C# ausgeführt wird. Führen Sie dotnet --version an einer Eingabeaufforderung aus.
Laden Sie das C#-Beispielprojekt herunter. Extrahieren Sie das ZIP-Archiv „digital-twins-samples-csharp-master.zip“.

Erstellen einer Digital Twins-Instanz

Erstellen Sie im Portal mithilfe der Schritte in diesem Abschnitt eine neue Instanz von Digital Twins.

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.

Festlegen von Berechtigungen für Ihre App

In diesem Abschnitt wird Ihre Beispielanwendung bei Azure Active Directory (Azure AD) registriert, damit sie auf Ihre Digital Twins-Instanz zugreifen kann. Falls Sie bereits über eine Azure AD-App-Registrierung verfügen, verwenden Sie diese für das Beispiel wieder. Stellen Sie sicher, dass sie gemäß der Beschreibung in diesem Abschnitt 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.

Erstellen der Anwendung

Führen Sie diese Schritte aus, um die Belegungsanwendung zu erstellen.

Öffnen Sie eine Eingabeaufforderung. Wechseln Sie zu dem Ordner, in dem die Dateien aus digital-twins-samples-csharp-master.zip extrahiert wurden.
Führen Sie cd occupancy-quickstart/src aus.
Führen Sie dotnet restore aus.
Bearbeiten Sie appSettings.json, um folgende Variablen zu aktualisieren:
- ClientId: Geben Sie die Anwendungs-ID Ihrer Azure AD-App-Registrierung ein, die Sie sich im vorherigen Abschnitt notiert haben.
- Tenant: Geben Sie die Verzeichnis-ID Ihres Azure AD-Mandanten ein, die Sie sich ebenfalls im vorherigen Abschnitt notiert haben.
- BaseUrl: Die URL der Verwaltungs-API Ihrer Digital Twins-Instanz im Format https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Ersetzen Sie die Platzhalter in dieser URL durch die Werte für Ihre Instanz aus dem vorherigen Abschnitt.
Speichern Sie die aktualisierte Datei.

Bereitstellen des Graphen

Mit diesem Schritt wird Ihr Digital Twins-Raumgraph bereitgestellt, der Folgendes enthält:

Mehrere Bereiche
Ein Gerät
Zwei Sensoren
Eine benutzerdefinierte Funktion
Eine Rollenzuweisung

Der Raumgraph wird mithilfe der Datei provisionSample.yaml bereitgestellt.

Führen Sie dotnet run ProvisionSample aus.

Hinweis

Das Azure CLI-Tool für die Geräteanmeldung wird verwendet, um den Benutzer bei Azure AD zu authentifizieren. Der Benutzer muss einen bestimmten Code eingeben, um sich über die Microsoft-Anmeldeseite zu authentifizieren. Führen Sie nach der Codeeingabe die Schritte für die Authentifizierung aus. Wenn das Tool ausgeführt wird, muss sich der Benutzer authentifizieren.

Tipp

Stellen Sie beim Ausführen dieses Schritts sicher, dass Ihre Variablen ordnungsgemäß kopiert wurden, wenn die folgende Fehlermeldung angezeigt wird: EXIT: Unexpected error: The input is not a valid Base-64 string ...
Der Bereitstellungsschritt kann einige Minuten dauern. Dabei wird auch ein IoT Hub in Ihrer Digital Twins-Instanz bereitgestellt. Er durchläuft eine Schleife, bis der IoT Hub „Status=Running“ anzeigt.
Kopieren Sie am Ende der Ausführung die Verbindungszeichenfolge (ConnectionString) des Geräts, um sie im Gerätesimulatorbeispiel verwenden zu können. Kopieren Sie nur die in dieser Abbildung markierte Zeichenfolge.

Tipp

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

Lassen Sie das Konsolenfenster für später geöffnet.

Senden von Sensordaten

Gehen Sie wie folgt vor, um die Sensorsimulator-Geräteanwendung zu erstellen und auszuführen:

Öffnen Sie eine neue Eingabeaufforderung. Navigieren Sie zu dem Projekt, das Sie in den Ordner digital-twins-samples-csharp-master heruntergeladen haben.
Führen Sie cd device-connectivity aus.
Führen Sie dotnet restore aus.
Bearbeiten Sie appsettings.json, um DeviceConnectionString mit der vorherigen Verbindungszeichenfolge (ConnectionString) zu aktualisieren. Speichern Sie die aktualisierte Datei.
Führen Sie dotnet run aus, um das Senden von Sensordaten zu starten. Die Daten werden wie in der folgenden Abbildung gezeigt an Azure Digital Twins gesendet:
Führen Sie diesen Simulator weiter aus, um Ergebnisse parallel zur Aktion des nächsten Schritts anzeigen zu können. Dieses Fenster zeigt die simulierten Sensordaten, die an Digital Twins gesendet werden. Im nächsten Schritt werden anhand von Abfragen in Echtzeit verfügbare Räume frischer Luft ermittelt.

Tipp

Stellen Sie beim Ausführen dieses Schritts sicher, dass DeviceConnectionString ordnungsgemäß kopiert wurde, wenn die folgende Fehlermeldung angezeigt wird: EXIT: Unexpected error: The input is not a valid Base-64 string ...

Suchen nach verfügbaren Bereichen mit frischer Luft

Das Sensorbeispiel simuliert zufällige Datenwerte für zwei Sensoren. Es handelt sich um Bewegungs- und CO2-Daten. Verfügbare Bereiche mit frischer Luft sind im Beispiel als Räume definiert, in denen sich niemand aufhält, und deren CO2-Wert unter 1.000 ppm liegt. Ist die Bedingung nicht erfüllt, ist der Bereich nicht verfügbar oder die Luftqualität zu schlecht.

Öffnen Sie die Eingabeaufforderung, die Sie zuvor zum Ausführen des Bereitstellungsschritts verwendet haben.
dotnet run GetAvailableAndFreshSpaces ausführen.
Sehen Sie sich diese Eingabeaufforderung und die Eingabeaufforderung für die Sensordaten nebeneinander an.

Die Sensordaten-Eingabeaufforderung sendet alle fünf Sekunden simulierte Bewegungs- und CO2-Daten an Digital Twins. Der andere Eingabeaufforderung liest den Graphen in Echtzeit, um auf der Grundlage willkürlich simulierter Daten verfügbare Räume mit frischer Luft zu ermitteln. Abhängig von den zuletzt übermittelten Sensordaten wird nahezu in Echtzeit eine dieser Bedingungen angezeigt:
- Room is available and air is fresh
- Room is not available or air quality is poor

Öffnen Sie Visual Studio Code mit dem Codearbeitsbereich-Projekt in digital-twins-samples-csharp, um die Vorgänge in dieser Schnellstartanleitung und die aufgerufenen APIs nachzuvollziehen. Verwenden Sie den folgenden Befehl:

<path>\occupancy-quickstart\src>code ..\..\digital-twins-samples.code-workspace

Die Tutorials enthalten detaillierte Informationen zum Code. Sie erfahren, wie Konfigurationsdaten geändert und wie APIs aufgerufen werden. Weitere Informationen zu Verwaltungs-APIs auf Ihrer Digital Twins Swagger-Seite:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Name	Ersetzen durch
YOUR_INSTANCE_NAME	Den Namen Ihrer Digital Twins-Instanz
YOUR_LOCATION	Die Serverregion, in der Ihre Instanz gehostet wird

Oder navigieren Sie der Einfachheit halber zu Digital Twins Swagger.

Bereinigen von Ressourcen

In den Tutorials wird Folgendes ausführlich behandelt:

Erstellen einer Anwendung für Facility-Manager zum Steigern der Produktivität von Personen
Effizientere Nutzung des Gebäudes

Wenn Sie mit den Tutorials fortfahren möchten, bereinigen Sie die in diesem Schnellstart erstellten Ressourcen nicht. Wenn Sie nicht fortfahren möchten, löschen Sie alle von diesem Schnellstart erstellten Ressourcen.

Löschen Sie den Ordner, der beim Herunterladen des Beispielrepositorys erstellt wurde.
Wählen Sie im Azure-Portal im Menü auf der linken Seite die Option Alle Ressourcen aus. Wählen Sie dann Ihre Digital Twins-Ressource aus. Wählen Sie oben im Bereich Alle Ressourcen die Option Löschen aus.

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.

Nächste Schritte

In dieser Schnellstartanleitung wurde anhand eines einfachen Szenarios sowie anhand von Beispielanwendungen gezeigt, wie sich mithilfe von Digital Twins Räume mit guten Arbeitsbedingungen finden lassen. Eine ausführliche Analyse dieses Szenarios finden Sie in diesem Tutorial:

Tutorial: Bereitstellen von Azure Digital Twins und Konfigurieren eines Raumgraphen

Freigeben über