Integrieren von Azure Digital Twins-Daten in einen Azure Maps-Gebäudeplan

  • Artikel

Dieser Artikel veranschaulicht, wie Sie Azure Digital Twins-Daten zum Aktualisieren von Informationen verwenden, die in einem Azure Maps-Gebäudeplan angezeigt werden. Da Azure Digital Twins ein Diagramm Ihrer IoT-Gerätebeziehungen speichert und Gerätedaten an verschiedene Endpunkte weiter leitet, ist es ein guter Dienst zum Aktualisieren von Informationsüberlagerungen auf Karten.

Dieser Leitfaden enthält folgende Informationen:

  1. Konfigurieren Ihrer Azure Digital Twins-Instanz, um Aktualisierungsereignisse des Zwillings an eine Funktion in Azure Functions zu senden.
  2. Erstellen einer Funktion zur Aktualisierung eines Featurezustandssets für Azure Maps-Gebäudepläne.
  3. Speichern Ihrer Karten-ID und Featurezustandsset-ID im Azure Digital Twins-Diagramm

Erste Schritte

Dieser Abschnitt enthält zusätzlichen Kontext für die Informationen in diesem Artikel.

Voraussetzungen

Bevor Sie mit diesem Artikel fortfahren, richten Sie zunächst Ihre einzelnen Azure Digital Twins- und Azure Maps-Ressourcen ein.

  • Für Azure Digital Twins: Folgen Sie den Anweisungen unter Verbinden einer End-to-End-Lösung, um eine Azure Digital Twins-Instanz mit einem exemplarischen Zwillingsdiagramm und einem simulierten Datenfluss einzurichten.
    • In diesem Artikel erweitern Sie diese Lösung mit einem weiteren Endpunkt und einer weiteren Route. In diesem Tutorial fügen Sie Ihrer Funktions-App auch eine weitere Funktion hinzu.
  • Für Azure Maps: Folgen Sie den Anweisungen unter Verwenden von Creator zum Erstellen von Gebäudeplänen und Erstellen eines Featurezustandssets, um einen Azure Maps-Gebäudeplan mit einem Featurezustandsset zu erstellen.
    • Featurezustandssets sind Sammlungen dynamischer Eigenschaften (Zustände), die Datasetfeatures wie z. B. Räumen oder Ausstattung zugewiesen sind. In den oben aufgeführten Anweisungen zu Azure Maps wird im Featurezustandsset der Raumstatus gespeichert, den Sie auf einer Karte anzeigen.
    • Sie benötigen Ihren Azure Maps-Abonnementschlüssel, ihre Featurezustandsset-ID und mapConfiguration.

Topologie

Die Abbildung unten zeigt, wo die Integrationselemente der Gebäudepläne in diesem Tutorial in ein größeres Azure Digital Twins-End-to-End-Szenario passen.

Diagram of Azure services in an end-to-end scenario, highlighting the Indoor Maps Integration piece.

Weiterleiten von Aktualisierungsbenachrichtigungen zu Zwillingen von Azure Digital Twins

Azure Digital Twins-Instanzen können Ereignisse zur Aktualisierung von Zwillingen ausgeben, wenn der Zustand eines Zwillings aktualisiert wird. Die Azure Digital Twins-Anleitungen unter Verbinden einer End-to-End-Lösung, zu denen Sie oben einen Link finden, führen Sie durch ein Szenario, in dem ein Temperaturattribut, das an den Zwilling eines Raums angefügt ist, mit einem Thermometer aktualisiert wird. Dieses Tutorial erweitert die Lösung, indem eine Azure-Funktion abonniert wird, um Benachrichtigungen von Zwillingen zu aktualisieren, und diese Funktion zur Aktualisierung Ihrer Karten verwendet wird.

Dieses Muster liest direkt aus dem Raumzwilling und nicht vom IoT-Gerät, was Ihnen die Flexibilität bietet, die zugrunde liegende Datenquelle für die Temperatur zu ändern, ohne dass Sie Ihre Zuordnungslogik aktualisieren müssen. Sie können z. B. mehrere Thermometer hinzufügen oder diesen Raum so einrichten, dass ein Thermometer mit einem anderen Raum gemeinsam genutzt wird, ohne dass Sie Ihre Kartenlogik aktualisieren müssen.

Zunächst erstellen Sie eine Route in Azure Digital Twins, um alle Ereignisse zur Aktualisierung der Zwillinge an ein Event Grid-Thema weiterzuleiten.

  1. Erstellen Sie ein Event Grid-Thema, das Ereignisse von Ihrer Azure Digital Twins-Instanz empfängt, indem Sie den folgenden CLI-Befehl verwenden:

    az eventgrid topic create --resource-group <your-resource-group-name> --name <your-topic-name> --location <region>

  2. Erstellen Sie einen Endpunkt, um Ihr Event Grid-Thema mit Azure Digital Twins zu verknüpfen, indem Sie den folgenden CLI-Befehl verwenden:

    az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

  3. Erstellen Sie eine Route in Azure Digital Twins, um Ereignisse zur Aktualisierung von Zwillingen an Ihren obigen Endpunkt zu senden, indem Sie den folgenden CLI-Befehl verwenden. Für den Platzhalter des Azure Digital Twins-Instanznamens in diesem Befehl können Sie den Anzeigenamen oder den Hostnamen verwenden, um die Leistung zu steigern.

    Hinweis

    Zurzeit besteht ein bekanntes Problem in Cloud Shell, das sich auf die Befehlsgruppen az dt route, az dt model und az dt twin auswirkt.

    Um dieses Problem zu beheben, führen Sie vor der Ausführung des Befehls az login in Cloud Shell aus, oder verwenden Sie die lokale Befehlszeilenschnittstelle anstelle von Cloud Shell. Weitere Einzelheiten hierzu finden Sie unter „400 Clientfehler: Ungültige Anforderung“ in Cloud Shell.

    az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <Event-Grid-endpoint-name> --route-name <my-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Erstellen einer Azure-Funktion zum Empfangen von Ereignissen und Aktualisieren von Karten

In diesem Abschnitt erstellen Sie eine Funktion, die auf Ereignisse lauscht, die an das Event Grid-Thema gesendet wurden. Mit dieser Funktion werden die Aktualisierungsbenachrichtigungen gelesen und entsprechende Aktualisierungen an ein Azure Maps-Featurezustandsset gesendet, um die Temperatur eines Raums zu aktualisieren.

In den Voraussetzungen für das Azure Digital Twins-Tutorial haben Sie eine Funktions-App erstellt, um Azure-Funktionen von Azure Digital Twins zu speichern. Erstellen Sie nun eine neue Event Grid-basierte Azure-Funktion innerhalb der Funktions-App.

Ersetzen Sie den Funktionscode durch folgenden Code. Er wird nur Aktualisierungen für Raumzwillinge herausfiltern, die aktualisierte Temperatur lesen und diese Informationen an Azure Maps senden.

using System;
using System.Threading.Tasks;
using System.Net.Http;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventGrid;

namespace updateMaps
{
    public static class ProcessDTUpdatetoMaps
    {
        // Read maps credentials from application settings on function startup
        private static string statesetID = Environment.GetEnvironmentVariable("statesetID");
        private static string subscriptionKey = Environment.GetEnvironmentVariable("subscription-key");
        private static HttpClient httpClient = new HttpClient();

        [FunctionName("ProcessDTUpdatetoMaps")]
        public static async Task Run([EventGridTrigger]EventGridEvent eventGridEvent, ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(eventGridEvent.Data.ToString());
            log.LogInformation($"Reading event from twinID: {eventGridEvent.Subject}: {eventGridEvent.EventType}: {message["data"]}");

            //Parse updates to "space" twins
            if (message["data"]["modelId"].ToString() == "dtmi:contosocom:DigitalTwins:Space;1")
            {
                // Set the ID of the room to be updated in your map.
                // Replace this line with your logic for retrieving featureID.
                string featureID = "UNIT103";

                // Iterate through the properties that have changed
                foreach (var operation in message["data"]["patch"])
                {
                    if (operation["op"].ToString() == "replace" && operation["path"].ToString() == "/Temperature")
                    {
                        // Update the maps feature stateset
                        var postcontent = new JObject(
                            new JProperty(
                                "States",
                                new JArray(
                                    new JObject(
                                        new JProperty("keyName", "temperature"),
                                        new JProperty("value", operation["value"].ToString()),
                                        new JProperty("eventTimestamp", DateTime.UtcNow.ToString("s"))))));

                        var response = await httpClient.PutAsync(
                            $"https://us.atlas.microsoft.com/featurestatesets/{statesetID}/featureStates/{featureID}?api-version=2.0&subscription-key={subscriptionKey}",
                            new StringContent(postcontent.ToString()));


                        log.LogInformation(await response.Content.ReadAsStringAsync());
                    }
                }
            }
        }
    }
}

Sie müssen zwei Umgebungsvariablen in Ihrer Funktions-App festlegen. Eine Variable ist Ihr primärer Azure Maps-Abonnementschlüssel und die andere ist Ihre Azure Maps-Zustandsset-ID.

az functionapp config appsettings set --name <your-function-app-name> --resource-group <your-resource-group> --settings "subscription-key=<your-Azure-Maps-primary-subscription-key>"
az functionapp config appsettings set --name <your-function-app-name> --resource-group <your-resource-group> --settings "statesetID=<your-Azure-Maps-stateset-ID>"

Anzeigen von Liveupdates in der Karte

Führen Sie die folgenden Schritte aus, um die Liveupdate-Temperatur anzuzeigen:

  1. Beginnen Sie mit dem Senden simulierter IoT-Daten, indem Sie das DeviceSimulator-Projekt aus Azure Digital Twins-Tutorial Verbinden einer End-to-End-Lösung ausführen. Anweisungen zu diesem Prozess finden Sie im Abschnitt Konfigurieren und Ausführen der Simulation.
  2. Verwenden Sie das Modul Azure Maps Indoor, um Ihre mit Azure Maps Creator erstellten Karten für Gebäudepläne zu rendern.
    1. Kopieren Sie die HTML-Beispieldatei für den Gebäudeplan aus Beispiel: benutzerdefinierte Formatierung: Verwenden der Kartenkonfiguration im WebSDK (Vorschau).
    2. Ersetzen Sie subscription key, mapConfiguration, statesetID und region in der lokalen HTML-Datei durch Ihre Werte.
    3. Öffnen Sie diese Datei in Ihrem Browser.

Beide Beispiele senden die Temperatur in einem kompatiblen Bereich, sodass die Farbe von Raum 121 etwa alle 30 Sekunden auf der Karte aktualisiert werden sollte.

Screenshot of an office map showing room 121 colored orange.

Speichern von Karteninformationen in Azure Digital Twins

Nachdem Sie jetzt über eine hartcodierte Lösung zur Aktualisierung Ihrer Karteninformationen verfügen, können Sie den Azure Digital Twins-Graphen verwenden, um alle Informationen zu speichern, die für die Aktualisierung Ihres Gebäudeplans erforderlich sind. Diese Informationen würden die Zustandsset-ID, die Kartenabonnement-ID und die Feature-ID jeder Karte bzw. jedes Ortes umfassen.

Eine Lösung für dieses spezielle Beispiel würde die Aktualisierung jedes Raums der obersten Ebene mit einer Zustandsset-ID und einem Kartenabonnement-ID-Attribut sowie die Aktualisierung jedes Raums mit einer Feature-ID umfassen. Sie müssten diese Werte einmal bei der Initialisierung des Zwillingsgraphen festlegen und diese Werte dann für jedes Aktualisierungsereignis des Zwillings abfragen.

Abhängig von der Konfiguration Ihrer Topologie können diese drei Attribute auf verschiedenen Ebenen gespeichert werden, die der Granularität Ihrer Karte entsprechen.

Nächste Schritte

Weitere Informationen zum Verwalten, Aktualisieren und Abrufen von Informationen aus dem Zwillingsgraphen finden Sie in den folgenden Referenzen: