Integración de datos de Azure Digital Twins en un mapa de interiores de Azure Maps

Artículo
03/23/2023

En este artículo se muestra cómo usar los datos de Azure Digital Twins para actualizar la información que se muestra en un mapa interior de Azure Maps. Dado que Azure Digital Twins almacena un gráfico de las relaciones de dispositivo IoT y enruta los datos del dispositivo a distintos puntos de conexión, es un excelente servicio para actualizar superposiciones informativas en mapas.

Esta guía contiene la información siguiente:

Configurar la instancia de Azure Digital Twins para enviar eventos de actualización de gemelos a una función en Azure Functions.
Crear una función para actualizar un conjunto de estados de características de planos interiores de Azure Maps.
Almacenamiento del identificador de los mapas y de los conjuntos de estados de características en el grafo de Azure Digital Twins.

Introducción

En esta sección se establece más contexto para la información de este artículo.

Requisitos previos

Antes de continuar con este artículo, empiece por configurar los recursos individuales de Azure Digital Twins y Azure Maps.

Para Azure Digital Twins: siga las instrucciones de Conexión de una solución de principio a fin para configurar una instancia de Azure Digital Twins con un grafo de gemelo de ejemplo y un flujo de datos simulado.
- En este artículo ampliará esa solución con otro punto de conexión y otra ruta. En el tutorial también se incorporará otra función a la aplicación de funciones.
Para Azure Maps: siga las instrucciones de Uso de Creator para crear planos interiores y Creación de un conjunto de estados de características para crear un mapa de interiores de Azure Maps con un conjunto de estados de características.
- Los conjuntos de estados de características son colecciones de propiedades dinámicas (estados) asignadas a las características del conjunto de datos, como salas o equipamiento. En las instrucciones de Azure Maps anteriores, el conjunto de estados de características almacena el estado de la sala que se mostrará en un mapa.
- Necesitará la clave de suscripción de Azure Maps, el identificador del conjunto de estados de características y mapConfiguration.

Topología

En la imagen siguiente se muestra dónde encajan los elementos de integración de planos interiores en este tutorial en un escenario de mayor tamaño de Azure Digital Twins de un extremo a otro.

Enrutamiento de las notificaciones de actualización de los gemelos desde Azure Digital Twins

Las instancias de Azure Digital Twins pueden emitir eventos de actualización de gemelos cada vez que se actualiza el estado de uno de estos elementos. El tutorial de Azure Digital Twins Conexión de una solución de un extremo a otro vinculado anteriormente le guiará a través de un escenario en el que se usa un termómetro para actualizar un atributo de temperatura conectado al gemelo de una sala. En este tutorial se amplía esa solución mediante la suscripción de una función de Azure para actualizar las notificaciones de los gemelos y el uso de esa función para actualizar los mapas.

Este patrón realiza la lectura directamente desde el gemelo de la sala, en lugar de desde el dispositivo IoT, lo que ofrece la flexibilidad de cambiar el origen de datos subyacente para la temperatura sin necesidad de actualizar la lógica de asignación. Por ejemplo, puede agregar varios termómetros o establecer que esta sala comparta un termómetro con otra, todo ello sin necesidad de actualizar la lógica de asignación.

En primer lugar, creará una ruta en Azure Digital Twins para reenviar todos los eventos de actualización de gemelos a un tema de Event Grid.

Cree un tema de Event Grid, que recibirá eventos de la instancia de Azure Digital Twins, mediante el siguiente comando de la CLI:
```
az eventgrid topic create --resource-group <your-resource-group-name> --name <your-topic-name> --location <region>
```

Cree un punto de conexión para enlazar su tema de Event Grid con Azure Digital Twins, con el comando CLI que se indica a continuación:

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>

Cree una ruta en Azure Digital Twins para enviar eventos de actualización de gemelos al punto de conexión, mediante el siguiente comando de la CLI. Para el marcador de posición de nombre de instancia de Azure Digital Twins en este comando, puede usar el nombre descriptivo o el nombre de host para aumentar el rendimiento.

Nota:

Actualmente hay un problema conocido en Cloud Shell que afecta a estos grupos de comandos: az dt route, az dt model y az dt twin.

Para resolverlo, ejecute az login en Cloud Shell antes de ejecutar el comando, o bien use la CLI local en lugar de Cloud Shell. Para obtener más información, consulte Solución de problemas conocidos de Azure Digital Twins.
```
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'"
```

Creación de una función de Azure para recibir eventos y actualizar mapas

En esta sección creará una función que escucha los eventos enviados al tema de Event Grid. Esta función leerá esas notificaciones de actualización y enviará las actualizaciones correspondientes a un conjunto de estados de características de Azure Maps para actualizar la temperatura de una sala.

En el requisito previo del tutorial de Azure Digital Twins ha creado una aplicación de funciones para almacenar las funciones de Azure de Azure Digital Twins. Ahora, cree una nueva función de Azure desencadenada por Event Grid dentro de la aplicación de funciones.

Reemplace el código de la función por el siguiente. Solo filtrará las actualizaciones de los gemelos de los espacios, leerá la temperatura actualizada y enviará esa información a Azure Maps.

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

Tendrá que establecer dos variables de entorno en la aplicación de funciones. Una es la clave de suscripción principal de Azure Maps, y la otra, el id. del conjunto de estados de Azure Maps.

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

Visualización de las actualizaciones directas en el mapa

Para ver las actualizaciones directas de la temperatura, siga estos pasos:

Comience a enviar datos de IoT simulados ejecutando el proyecto DeviceSimulator desde el tutorial de Azure Digital Twins Conexión de una solución de un extremo a otro. Las instrucciones de este proceso están disponibles en la sección Configuración y ejecución de la simulación.
Use el módulo Indoor de Azure Maps para representar los mapas de interiores creados en Azure Maps Creator.
1. Copie el archivo HTML del mapa de interiores de Ejemplo: estilo personalizado: consumir la configuración de mapa en WebSDK (versión preliminar).
2. Reemplace la clave de suscripción y los elementos mapConfiguration, statesetID y región del archivo HTML local por sus valores.
3. Abra ese archivo en el explorador.

Ambos ejemplos envían la temperatura en un rango compatible, por lo que debería ver el color de la actualización de la sala 121 en el plano aproximadamente cada 30 segundos.

Screenshot of an office map showing room 121 colored orange.

Almacenamiento de la información de los mapas en Azure Digital Twins

Ahora que tiene una solución codificada de forma rígida para actualizar la información de los planos, puede usar el grafo de Azure Digital Twins para almacenar toda la información necesaria a fin de actualizar el plano interior. Esta información incluiría el id. de conjuntos de estados, el id. de suscripción de los planos y el id. de característica de cada plano y ubicación, respectivamente.

Una solución para este ejemplo específico implicaría actualizar cada espacio de nivel superior para que tuviera un id. de conjunto de estados y un atributo de id. de suscripción de planos, así como actualizar cada sala para que tuviera un id. de característica. Tendría que establecer estos valores una vez al inicializar el grafo de gemelos y, después, consultar esos valores para cada evento de actualización de gemelos.

En función de la configuración de su topología, podrá almacenar estos tres atributos en diferentes niveles según la granularidad del plano.

Pasos siguientes

Para obtener más información sobre cómo administrar, actualizar y recuperar información del grafo de gemelos, vea las referencias siguientes: