Condividi tramite

Integrare i dati di Azure Digital Twins in una mappa interna di Azure Maps

  • Articolo

Questo articolo illustra come usare i dati di Azure Digital Twins per aggiornare le informazioni visualizzate su una mappa interna di Azure Maps. Poiché Gemelli digitali di Azure archivia un grafico delle relazioni tra i dispositivi IoT e instrada i dati dei dispositivi a endpoint diversi, è un ottimo servizio per aggiornare le sovrimpressioni informative sulle mappe.

In questa guida vengono illustrate le informazioni seguenti:

  1. Configurare l'istanza di Azure Digital Twins per inviare eventi di aggiornamento dei gemelli a una funzione in Funzioni di Azure.
  2. Creazione di una funzione per aggiornare uno stato delle mappe interne di Mappe di Azure.
  3. Archiviazione dell'ID delle mappe e dell'ID degli stati delle funzionalità nel grafico di Azure Digital Twins.

Inizia subito

In questa sezione viene impostato un contesto aggiuntivo per le informazioni contenute in questo articolo.

Prerequisiti

Prima di procedere con questo articolo, iniziare configurando le singole risorse di Gemelli digitali di Azure e Mappe di Azure.

  • Per Gemelli digitali di Azure: seguire le istruzioni riportate in Connettere una soluzione end-to-end per configurare un'istanza di Gemelli digitali di Azure con un grafico gemello di esempio e un flusso di dati simulato.
    • In questo articolo si estenderà la soluzione con un altro endpoint e un altro percorso. Aggiungerai anche un'altra funzione all'app per le funzioni in questa esercitazione.
  • Per Azure Maps: seguire le istruzioni in Usare Creator per creare mappe interne e creare una mappa interna di Azure Maps con un statiset delle funzionalità.
    • I set di stati della funzionalità sono raccolte di proprietà dinamiche (stati) assegnate alle funzionalità del set di dati, ad esempio locali o attrezzature. Nelle istruzioni precedenti di Azure Maps, lo stateset di funzionalità archivia lo stato della stanza che sarà visualizzato su una mappa.
    • Sarà necessaria la chiave di sottoscrizione di Mappe di Azure, l'ID del set di stati e mapConfiguration.

Topologia

L'immagine seguente illustra dove gli elementi di integrazione delle mappe indoor di questa esercitazione rientrano in uno scenario di Azure Digital Twins completo e end-to-end.

Diagramma dei servizi di Azure in uno scenario end-to-end, evidenziando il componente di integrazione di mappe interne.

Instradare le notifiche di aggiornamento dei gemelli digitali da Azure Digital Twins.

Le istanze di Azure Digital Twins possono emettere eventi di aggiornamento dei gemelli ogni volta che viene aggiornato lo stato di un gemello. Nella soluzione end-to-end collegata sopra Azure Digital Twins Connect viene illustrato uno scenario in cui un termometro viene utilizzato per aggiornare un attributo di temperatura associato al gemello di una stanza. Questa esercitazione estende la soluzione sottoscrivendo una funzione di Azure per aggiornare le notifiche dai dispositivi gemelli e usando tale funzione per aggiornare le mappe.

Questo modello legge direttamente dal gemello della stanza, anziché dal dispositivo IoT, il che offre la flessibilità necessaria per modificare la fonte dati sottostante per la temperatura senza la necessità di aggiornare la logica di mappatura. Ad esempio, è possibile aggiungere più termometri o impostare questa stanza per condividere un termometro con un'altra stanza, tutto senza dover aggiornare la logica della mappa.

Prima di tutto, creerai una route in Azure Digital Twins per inoltrare tutti gli eventi di aggiornamento dei gemelli a un argomento di Event Grid.

  1. Crea un argomento Event Grid, che riceverà eventi dall'istanza di Azure Digital Twins, usando il seguente comando CLI:

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

  2. Creare un endpoint per collegare il topic di Event Grid ad Azure Digital Twins usando il comando CLI seguente:

    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. Creare una route in Azure Digital Twins per inviare dati di aggiornamento di un gemello al tuo endpoint, usando il comando CLI seguente. Per il nome dell'istanza segnaposto di Azure Digital Twins in questo comando, puoi usare il nome amichevole o il nome host per migliorare le prestazioni.

    Nota

    Esiste attualmente un problema noto in Cloud Shell che interessa questi gruppi di comandi: az dt route, az dt model, az dt twin.

    Per risolverlo, eseguire az login in Cloud Shell prima di eseguire il comando oppure usare l'interfaccia della riga di comando locale anziché Cloud Shell. Per altri dettagli su questo argomento, vedere Problemi noti di Gemelli digitali di Azure.

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

Creare una funzione di Azure per ricevere eventi e aggiornare le mappe

In questa sezione si creerà una funzione in ascolto degli eventi inviati all'argomento Griglia di eventi. La funzione leggerà le notifiche di aggiornamento e invierà gli aggiornamenti corrispondenti a un set di stati delle funzionalità di Mappe di Azure per aggiornare la temperatura di una stanza.

Nell'esercitazione sui Gemelli digitali di Azure menzionata nel prerequisito, hai creato un'app per le funzioni per archiviare le funzioni Azure Digital Twins. Creare ora una nuova funzione di Azure attivata da Griglia di eventi all'interno dell'app per le funzioni.

Sostituire il codice della funzione con il codice seguente. Filtra solo gli aggiornamenti per i gemelli spaziali, legge la temperatura aggiornata e invia tali informazioni a Mappe di Azure.

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());
                    }
                }
            }
        }
    }
}

È necessario impostare due variabili di ambiente nell'app per le funzioni. Una è la chiave di sottoscrizione primaria di Mappe di Azure e una è l'ID del set di stati di Mappe di Azure.

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

Visualizzare gli aggiornamenti live nella mappa

Per visualizzare la temperatura ad aggiornamento in tempo reale, seguire questa procedura:

  1. Inizia a inviare dati IoT simulati eseguendo il progetto DeviceSimulator dall'hub Azure Digital Twins "Connetti una soluzione end-to-end". Le istruzioni per questo processo sono disponibili nella sezione Configurare ed eseguire la simulazione.
  2. Usare il modulo Azure Maps Indoor per visualizzare le mappe degli interni create con Azure Maps Creator.
    1. Copiare il file HTML della mappa interna di esempio da Esempio: Applicazione di stili personalizzati: Utilizzare la configurazione della mappa in WebSDK (anteprima).
    2. Sostituire la chiave di sottoscrizione, mapConfiguration, statesetID e l'area nel file HTML locale con i valori specificati.
    3. Aprire il file nel browser.

Entrambi i campioni inviano temperatura in un intervallo compatibile, quindi dovrebbe essere visualizzato il colore dell'aggiornamento della stanza 121 sulla mappa circa ogni 30 secondi.

Screenshot di una mappa dell'ufficio che mostra la sala 121 arancione.

Archiviare le informazioni sulla mappa in Gemelli digitali di Azure

Ora che è disponibile una soluzione hardcoded per aggiornare le informazioni sulle mappe, è possibile usare il grafico di Gemelli digitali di Azure per archiviare tutte le informazioni necessarie per aggiornare la mappa interna. Queste informazioni includono rispettivamente l'ID del set di stati, l'ID di sottoscrizione delle mappe e l'ID della funzionalità (rispettivamente per ogni mappa e posizione).

Una soluzione per questo esempio specifico comporta l'aggiornamento di ogni spazio di primo livello con un attributo ID set di stati e ID di sottoscrizione mappa, e l'aggiornamento di ogni stanza per essere dotata di un ID funzionalità. È necessario impostare questi valori una volta durante l'inizializzazione del grafico gemello, quindi eseguire una query su tali valori per ogni evento di aggiornamento del gemello.

A seconda della configurazione della topologia, sarà possibile archiviare questi tre attributi a livelli diversi correlati alla granularità della mappa.

Passaggi successivi

Per altre informazioni sulla gestione, l'aggiornamento e il recupero di informazioni dal grafico dei gemelli, vedere i riferimenti seguenti: