Integrar dados dos Gêmeos Digitais do Azure em um mapa do interior do Azure Mapas

  • Artigo

Este artigo mostra como usar dados dos Gêmeos Digitais do Azure para atualizar as informações exibidas em um mapa do interior do Azure Mapas. Como os Gêmeos Digitais do Azure armazenam um grafo de relações entre dispositivos IoT, bem como encaminha dados telemétricos para diferentes pontos de extremidade, é um ótimo serviço para atualizar sobreposições informativas nos mapas.

Este guia aborda as seguintes informações:

  1. Como configurar a instância dos Gêmeos Digitais do Azure para enviar eventos de atualização do gêmeo a uma função do Azure Functions.
  2. Como criar uma função para atualizar um conjunto de estados do recurso do Indoor Maps do Azure Mapas.
  3. Como armazenar a ID de mapas e a ID do conjunto de estados do recurso no grafo dos Gêmeos Digitais do Azure.

Introdução

Esta seção define o contexto adicional para as informações neste artigo.

Pré-requisitos

Antes de prosseguir com este artigo, comece configurando os Gêmeos Digitais do Azure e os recursos do Azure Mapas.

  • Para os Gêmeos Digitais do Azure: siga as instruções em Conectar uma solução de ponta a ponta, para configurar uma instância dos Gêmeos Digitais do Azure com um grafo gêmeo de exemplo e um fluxo de dados simulado.
    • Neste artigo, você estenderá essa solução com outro ponto de extremidade e outra rota. Você também adicionará outra função desse tutorial ao seu aplicativo de funções.
  • Para o Azure Mapas: siga as instruções em Usar Criador para criar mapas do interior e Criar um mapa do interior do Azure Mapas com um conjunto de estados de recursos.
    • Os conjuntos de estados do recurso são coleções de propriedades dinâmicas (estados) atribuídas a recursos de um conjunto de dados, como salas ou equipamentos. Nas instruções do Azure Mapas exibido acima, o conjunto de estados do recurso armazena o status da sala que será exibida em um mapa.
    • Você precisará da sua chave de assinatura do Azure Mapas, ID do conjunto de estados do recurso e mapConfiguration.

Topologia

A imagem abaixo ilustrará em que local os elementos de Integração do Indoor Maps deste tutorial se enquadram em um cenário maior e de ponta a ponta dos Gêmeos Digitais do Azure.

Diagrama dos serviços do Azure em um cenário de ponta a ponta, realçando a parte da Integração do Indoor Maps.

Encaminhar notificações de atualização de gêmeos dos Gêmeos Digitais do Azure

As instâncias dos Gêmeos Digitais do Azure podem emitir eventos de atualização do gêmeo sempre que o estado do gêmeo for atualizado. O artigo dos Gêmeos Digitais do Azure Conectar uma solução de ponta a ponta mostrado acima descreve o cenário em que um termômetro é usado para atualizar um atributo de temperatura anexado ao gêmeo de uma sala. Este tutorial estende essa solução assinando uma função do Azure para atualizar as notificações de gêmeos e usando essa função para atualizar os mapas.

Esse padrão executa uma leitura do gêmeo da sala de modo direto, em vez de usar um dispositivo IoT. Isso fornecerá flexibilidade para alterar a fonte de dados subjacente para usar uma temperatura sem a necessidade de atualizar a lógica de mapeamento. Por exemplo, é possível adicionar vários termômetros ou definir essa sala para compartilhar um termômetro com outra sala, tudo isso sem a necessidade de atualizar a lógica do mapa.

Primeiro, será necessário criar uma rota nos Gêmeos Digitais do Azure para encaminhar todos os eventos de atualização do gêmeo para um tópico de Grade de Eventos.

  1. Crie um tópico de Grade de Eventos, que receberá eventos de sua instância dos Gêmeos Digitais do Azure, com o comando da CLI abaixo:

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

  2. Crie um ponto de extremidade para vincular o tópico de Grade de Eventos aos Gêmeos Digitais do Azure, com o comando da CLI abaixo:

    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. Crie uma rota nos Gêmeos Digitais do Azure para enviar eventos de atualização do gêmeo para o ponto de extremidade, com o comando da CLI abaixo. Para o espaço reservado para o nome da instância dos Gêmeos Digitais do Azure neste comando, você pode usar o nome amigável ou o nome do host para aumentar o desempenho.

    Observação

    Atualmente, há um problema conhecido no Cloud Shell afetando estes grupos de comandos: az dt route, az dt model e az dt twin.

    Para resolver, execute az login no Cloud Shell antes de executar o comando ou use a CLI local em vez do Cloud Shell. Para obter mais detalhes sobre isso, confira Problemas conhecidos dos Gêmeos Digitais do 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'"

Criar uma função do Azure para receber eventos e atualizar mapas

Nesta seção, você criará uma função que escuta os eventos enviados para o tópico Grade de Eventos. A função lerá essas notificações de atualização e enviará as atualizações correspondentes a um conjunto de estados do recurso do Azure Mapas para atualizar a temperatura de uma sala.

No pré-requisito do tutorial dos Gêmeos Digitais do Azure, você criou um aplicativo de funções para armazenar os Gêmeos Digitais do Azure do Azure Functions. Agora, crie uma nova função do Azure disparada pela Grade de Eventos dentro do aplicativo de funções.

Substitua o código da função pelo código a seguir. Ele vai filtrar somente as atualizações dos gêmeos do espaço, ler a temperatura atualizada, depois enviar essas informações ao Azure Mapas.

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

Será preciso definir duas variáveis de ambiente no aplicativo de funções. Uma será a chave de assinatura primária do Azure Mapas e outra será a ID do conjunto de estados do Azure Mapas.

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

Exibir atualizações ao vivo no mapa

Para conferir a temperatura de atualização dinâmica, siga as etapas abaixo:

  1. Comece enviando dados simulados de IoT executando o projeto DeviceSimulator de Conectar uma solução de ponta a ponta dos Gêmeos Digitais do Azure. As instruções para esse processo estão na seção Configurar e executar a simulação.
  2. Use o módulo Indoor Maps do Azure para renderizar mapas do interior desenvolvidos no Criador do Azure Mapas.
    1. Copie o exemplo de arquivo HTML de mapa do interior em Exemplo: Estilo Personalizado: configuração de consumo de mapa no WebSDK (versão prévia).
    2. Substitua a chave de assinatura, mapConfiguration, statesetID e região no arquivo HTML local pelos seus valores.
    3. Abra esse arquivo no navegador.

Os dois exemplos enviarão a temperatura em um intervalo compatível. Portanto, será possível conferir a cor da sala 121 atualizar no mapa a cada 30 segundos.

Captura de tela de um mapa do Office mostrando a sala 121 na cor laranja.

Armazenar informações de mapa nos Gêmeos Digitais do Azure

Agora que você tem uma solução codificada para atualizar informações de mapas, será possível usar o grafo dos Gêmeos Digitais do Azure para armazenar todas as informações necessárias para atualizar seu mapa do interior. Essas informações incluem a ID do conjunto de estados, a ID da assinatura de mapas e a ID do recurso de cada mapa e localização, respectivamente.

Uma solução para esse exemplo específico envolverá atualizar cada espaço de nível superior para obter um atributo de ID do conjunto de estados e ID da assinatura de mapas, bem como atualizar cada sala para obter uma ID do recurso. Será preciso definir esses valores uma vez durante a inicialização do grafo do gêmeo, depois consultar esses valores para cada evento de atualização do gêmeo.

De acordo com a configuração de sua topologia, será possível armazenar esses três atributos em diferentes níveis correlacionados à granularidade do mapa.

Próximas etapas

Para ler mais sobre como gerenciar, atualizar e recuperar informações do grafo dos gêmeos, confira as seguintes referências: