Integrar dados do Azure Digital Twins num mapa interior do Azure Maps
Este artigo mostra como usar os dados do Azure Digital Twins para atualizar as informações exibidas em um mapa interno do Azure Maps. Como o Azure Digital Twins armazena um gráfico de seus relacionamentos de dispositivo IoT e roteia dados do dispositivo para diferentes pontos de extremidade, é um ótimo serviço para atualizar sobreposições informativas em mapas.
Este guia abrange as seguintes informações:
- Configurar sua instância do Azure Digital Twins para enviar eventos de atualização gêmeos para uma função no Azure Functions.
- Criar uma função para atualizar um conjunto de estados de recursos de mapas internos do Azure Maps.
- Armazenar a ID dos mapas e a ID do conjunto de estados do recurso no gráfico dos Gêmeos Digitais do Azure.
Começar agora
Esta seção define o contexto adicional para as informações neste artigo.
Pré-requisitos
Antes de prosseguir com este artigo, comece configurando seus recursos individuais do Azure Digital Twins e do Azure Maps.
- Para Gêmeos Digitais do Azure: Siga as instruções em Conectar uma solução de ponta a ponta para configurar uma instância de Gêmeos Digitais do Azure com um gráfico de gêmeos de exemplo e fluxo de dados simulado.
- Neste artigo, você estenderá essa solução com outro ponto de extremidade e rota. Você também adicionará outra função ao aplicativo de função a partir desse tutorial.
- Para o Azure Maps: siga as instruções em Usar o Creator para criar mapas internos e criar um mapa interno do Azure Maps com um conjunto de estados de recursos.
- Os conjuntos de estados de recursos são coleções de propriedades dinâmicas (estados) atribuídas a recursos de conjunto de dados, como salas ou equipamentos. Nas instruções do Azure Maps acima, o conjunto de estados do recurso armazena o status da sala que você exibirá em um mapa.
- Você precisará de sua chave de assinatura do Azure Maps, ID do conjunto de estados do recurso e mapConfiguration.
Topologia
A imagem abaixo ilustra onde os elementos de integração de mapas internos neste tutorial se encaixam em um cenário maior e completo de Gêmeos Digitais do Azure.
Notificações de atualização de gêmeos de rota dos Gêmeos Digitais do Azure
As instâncias do Azure Digital Twins podem emitir eventos de atualização de gêmeos sempre que o estado de um gêmeo é atualizado. O Azure Digital Twins Connect, uma solução de ponta a ponta vinculada acima, percorre um cenário em que um termômetro é usado para atualizar um atributo de temperatura anexado ao gêmeo de um quarto. Este tutorial estende essa solução assinando uma função do Azure para atualizar notificações de gêmeos e usando essa função para atualizar seus mapas.
Esse padrão lê diretamente do gêmeo da sala, em vez do dispositivo IoT, o que lhe dá a flexibilidade de alterar a fonte de dados subjacente para a temperatura sem a necessidade de atualizar sua lógica de mapeamento. Por exemplo, você pode adicionar vários termômetros ou definir esta sala para compartilhar um termômetro com outra sala, tudo sem precisar atualizar a lógica do mapa.
Primeiro, você criará uma rota nos Gêmeos Digitais do Azure para encaminhar todos os eventos de atualização de gêmeos para um tópico da Grade de Eventos.
Crie um tópico de Grade de Eventos, que receberá eventos de sua instância do Azure Digital Twins, usando o comando CLI abaixo:
az eventgrid topic create --resource-group <your-resource-group-name> --name <your-topic-name> --location <region>Crie um ponto de extremidade para vincular seu tópico de Grade de Eventos aos Gêmeos Digitais do Azure, usando o comando 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>Crie uma rota no Azure Digital Twins para enviar eventos de atualização de gêmeos para seu ponto de extremidade, usando o comando CLI abaixo. Para o espaço reservado de nome de instância do Azure Digital Twins neste comando, você pode usar o nome amigável ou o nome do host para um aumento no desempenho.
Nota
Atualmente, há um problema conhecido no Cloud Shell que afeta esses grupos de comandos:
az dt route,az dt model,az dt twin.Para resolver, execute
az loginno Cloud Shell antes de executar o comando ou utilize a CLI local em vez do Cloud Shell. Para obter mais detalhes sobre isso, consulte 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 para um conjunto de estados de recursos do Azure Maps, para atualizar a temperatura de uma sala.
No pré-requisito do tutorial Gêmeos Digitais do Azure, você criou um aplicativo de função para armazenar funções do Azure Gêmeos Digitais do Azure. Agora, crie uma nova função do Azure acionada pela Grade de Eventos dentro do aplicativo de função.
Substitua o código da função pelo código a seguir. Ele filtrará apenas atualizações para gêmeos espaciais, lerá a temperatura atualizada e enviará essas informações para o 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());
}
}
}
}
}
}
Você precisará definir duas variáveis de ambiente em seu aplicativo de função. Uma é a chave de subscrição principal do Azure Maps e outra é o ID do conjunto de estados do 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>"
Ver atualizações em tempo real no mapa
Para ver a temperatura de atualização ao vivo, siga as etapas abaixo:
- Comece a enviar dados de IoT simulados executando o projeto DeviceSimulator a partir do Azure Digital Twins Connect, uma solução de ponta a ponta. As instruções para esse processo estão na seção Configurar e executar a simulação .
- Use o módulo Azure Maps Indoor para renderizar seus mapas internos criados no Azure Maps Creator.
- Copie o exemplo de arquivo HTML de mapa interno de Exemplo: Estilo personalizado: consumir configuração de mapa no WebSDK (Visualização).
- Substitua a chave de assinatura, mapConfiguration, statesetID e região no arquivo HTML local por seus valores.
- Abra esse arquivo no seu navegador.
Ambas as amostras enviam a temperatura em uma faixa compatível, então você deve ver a cor da sala 121 atualizar no mapa a cada 30 segundos.
Armazenar informações de mapa no Azure Digital Twins
Agora que você tem uma solução codificada para atualizar suas informações de mapas, você pode usar o gráfico de Gêmeos Digitais do Azure para armazenar todas as informações necessárias para atualizar seu mapa interno. Essas informações incluiriam o ID do conjunto de estados, o ID da assinatura dos mapas e o ID do recurso de cada mapa e local, respectivamente.
Uma solução para este exemplo específico envolveria a atualização de cada espaço de nível superior para ter um atributo de ID de conjunto de estados e ID de assinatura de mapas e a atualização de cada sala para ter um ID de recurso. Você precisaria definir esses valores uma vez ao inicializar o gráfico gêmeo e, em seguida, consultar esses valores para cada evento de atualização gêmea.
Dependendo da configuração da topologia, será possível armazenar esses três atributos em diferentes níveis correlacionados à granularidade do mapa.
Próximos passos
Para ler mais sobre como gerenciar, atualizar e recuperar informações do gráfico de gêmeos, consulte as seguintes referências: