Sincronização de modelos entre o Azure Digital Twins e o Time Series Insights Gen2
Nota
O serviço Time Series Insights será desativado em 7 de julho de 2024. Considere migrar os ambientes existentes para soluções alternativas o mais rápido possível. Para obter mais informações sobre a substituição e migração, visite nossa documentação.
Este artigo explica as práticas recomendadas e as ferramentas usadas para traduzir o modelo de ativo no Azure Digital Twins (ADT) para o modelo de ativo no Azure Time Series Insights (TSI). Este artigo é a segunda parte de uma série de tutoriais de duas partes que explicam a integração dos Gêmeos Digitais do Azure com o Azure Time Series Insights. A integração dos Gêmeos Digitais do Azure com o Time Series Insights permite arquivar e rastrear o histórico de telemetrias e propriedades calculadas de Gêmeos Digitais. Esta série de tutoriais destina-se a programadores que trabalham para integrar o Time Series Insights com os Azure Digital Twins. A Parte 1 explica o Estabelecimento de pipeline de dados que traz os dados reais da série temporal dos Gêmeos Digitais do Azure para o Time Series Insights e esta, a segunda parte da série de tutoriais explica a sincronização do modelo de ativos entre os Gêmeos Digitais do Azure e o Time Series Insights. Este tutorial explica as práticas recomendadas na escolha e estabelecimento de convenções de nomenclatura para ID de Série Temporal (ID TS) e no estabelecimento manual de hierarquias no Modelo de Série Temporal (TSM).
Escolher um ID de Série Temporal
O ID de Série Temporal é um identificador exclusivo usado para identificar ativos no Time Series Insights. Os dados de séries temporais (telemetrias do campo, que são pares tempo-valor) são representados usando variáveis listadas em TSID. Nos Gêmeos Digitais do Azure, as propriedades e telemetrias do gêmeo são usadas para representar o estado de um gêmeo e as medidas produzidas pelo gêmeo, respectivamente. A partir do design atual do TSM, os TSIDs precisam ser exclusivos. Usar IDs gêmeos dos gêmeos no Azure Digital Twins ou combinado com nome de propriedade ou telemetria sempre tornará a ID TS exclusiva no TSM. Em um caso típico, o será o <Twin ID> TSID, e os nomes de propriedade e telemetria serão as variáveis no TSM. No entanto, há casos de uso em que é preferível que as hierarquias de ativos no Time Series Insights sejam niveladas usando o formato de chaves compostas, como <Twin ID>+ <Delimiter of Choice> + <Name of the Property or Telemetry>. Vamos dar um exemplo para explicar o caso posterior. Considere um quarto em um edifício modelado como um gêmeo e tem quarto de identificação duplo22. Sua propriedade de ajuste de temperatura deve ser traduzida como Room22_TempSetting TSID e medição de temperatura deve ser traduzida para Room22_TempMea em TSM.
Contextualizando séries temporais
A contextualização de dados (principalmente de natureza espacial) no Time Series Insights é obtida através de hierarquias de ativos e o mesmo é usado para facilitar a navegação de dados através de uma visualização em árvore no explorador Time Series Insights. Os tipos de séries temporais e as hierarquias são definidos usando o Modelo de Série Temporal (TSM) no Time Series Insights. Os tipos no TSM ajudam a definir variáveis, enquanto os níveis de hierarquia e os valores de campo de instância são usados para construir a exibição em árvore no explorador do Time Series Insights. Para obter mais informações sobre o TSM, consulte a documentação on-line do Time Series Insights.
Nos Gêmeos Digitais do Azure, a conexão entre ativos é expressa usando relações de gêmeos. As relações gêmeas são simplesmente um gráfico de ativos conectados. No entanto, no Time Series Insight, as relações entre ativos são de natureza hierárquica. Ou seja, os ativos compartilham um tipo de relação pai-filho e são representados usando uma estrutura de árvore. Para traduzir informações de relacionamento dos Gêmeos Digitais do Azure em hierarquias do Time Series Insights, precisamos escolher relações hierárquicas relevantes dos Gêmeos Digitais do Azure. Os Gêmeos Digitais do Azure usam uma linguagem de modelagem de padrão aberto chamada DTDL (Digital Twin Definition Language). Em DTDL, os modelos são descritos usando uma variante do JSON chamada JSON-LD. Consulte a documentação da DTDL para obter detalhes completos sobre a especificação.
Traduzindo a representação de gráficos no Azure Digital Twins para a estrutura em árvore no Time Series Insights
As seções a seguir do tutorial capturam alguns cenários principais de tradução manual da estrutura do gráfico nos Gêmeos Digitais do Azure para a estrutura em árvore no Time Series Insights.
Sistema de exemplo: Este tutorial usa o exemplo a seguir para explicar os conceitos discutidos abaixo. É um sistema de gestão de edifícios simples e fictício, com um andar e duas salas. Tem três termostatos, um em cada um dos quartos e outro comum ao chão. Além disso, também possui um medidor de fluxo de água que mede o fluxo de água da Sala 21 para a Sala 22 através de uma conexão de tubulação entre as salas. Olhando para a relação espacial entre gémeos, tem ambos os tipos de relações.
Relação hierárquica mais comum. Por exemplo, Building40 -> Floor01 -> FloorTS* -> Temperatura
Relação circular não tão comum. Por exemplo, a partir do Building40, o FlowMtr pode ser rastreado através de dois caminhos diferentes.
- Edifício40 -> Andar01 -> Sala21 -> FlowMtr* -> Fluxo
- Edifício40 -> Andar01 -> Sala22 -> FlowMtr* -> Fluxo
Onde "Fluxo" é a telemetria real que mede o fluxo de água entre a Sala21 e a Sala22
Nota
* FloorTS significa FloorThermoStat e FlowMtr significa Flow Meter e normalmente escolhido como TSID. Temperatura e Fluxo são as telemetrias brutas referidas como variáveis no Time Series Insights.
Dada a limitação atual no Time Series Insights de que um ativo não pode ser representado em várias ramificações, as seções a seguir explicam a modelagem de relações hierárquicas e circulares no Time Series Insights.
Caso 1: Relação hierárquica (pais-filhos)
É o tipo mais comum de relacionamento entre os gêmeos. A modelagem da relação pai e filho pura é explicada na ilustração a seguir. Os campos de instância e TSID são derivados de ids gêmeas, conforme mostrado abaixo. Embora os campos de instância possam ser atualizados manualmente usando o explorador de Insights de Série Temporal, a seção abaixo chamada "Atualizando campos de instância usando APIs" explica a escuta de alterações de modelo nos Gêmeos Digitais do Azure e a atualização de campos de instância no Time Series Insights usando funções do Azure.
Caso 2: Relação circular
Relação circular nos Gêmeos Digitais do Azure para relação de hierarquia única no Time Series Insights
Dado que a TSID deve ser única e só pode ser representada numa hierarquia, este caso representa o «FlowMtr» com uma telemetria denominada «Flow» logo abaixo da dupla «Room21». No futuro, quando o Time Series Insights puder suportar a representação múltipla de séries temporais no TSM, a telemetria 'Flow' será representada em 'Sala 21' e 'Sala 22'
A captura de tela a seguir mostra o mapeamento manual de IDs gêmeos no campo Gêmeos Digitais do Azure para Instância no TSM e a hierarquia resultante no Time Series Insights.
Relação circular nos Gêmeos Digitais do Azure com várias hierarquias no Time Series Insights, usando duplicatas
A Parte 1 do tutorial explica como um programa cliente (uma função do Azure) ajuda a transferir dados de telemetria do Hub IoT ou de outras fontes de eventos para os Gêmeos Digitais do Azure. Essa abordagem sugere o uso do mesmo programa cliente para fazer atualizações nas propriedades relevantes dos gêmeos pais. No exemplo dado, ao ler a telemetria FlowMtr do Hub IoT e atualizar a propriedade "Flow" no gêmeo FlowMtr, o programa também pode atualizar as propriedades correspondentes em todos os possíveis gêmeos pai da fonte. No nosso exemplo, seria a propriedade "outflowmea" (identificada usando a relação "outflow") da Room21 e a propriedade "inflowmea" da Room22. A captura de tela abaixo mostra a experiência final do usuário no explorador do Time Series Insights. Deve notar-se que, ao adotar esta abordagem, temos duplicados de dados.
O trecho de código abaixo mostra como o aplicativo cliente foi capaz de navegar na relação de gêmeos usando APIs de Gêmeos Digitais do Azure.
Nota
Este exemplo de trecho de código pressupõe que os leitores estejam familiarizados com a Parte 01 do tutorial e essa alteração de código foi feita dentro da função "ProcessHubToDTEvents".
if (propertyPath.Equals("/Flow"))
{
//Update the flow value property of the flow meter
await AdtUtilities.UpdateTwinProperty(client, twinId, "replace",
propertyPath, "double", propertyValue, log);
//also update the sending end flow
string parentIdOutflow = await AdtUtilities.FindParent(client, twinId,
"outflow", log);
if (parentIdOutflow != null)
await AdtUtilities.UpdateTwinProperty(client, parentIdOutflow, "replace", "outflow", "double", propertyValue, log);
else
log.LogInformation("Unable to find Parent with outflow
relationship for " + twinId );
//and receiving end flow value
string parentIdinflow = await AdtUtilities.FindParent(client, twinId,
"inflow", log);
if (parentIdinflow != null)
await AdtUtilities.UpdateTwinProperty(client, parentIdinflow,
"replace", "inflow", "double", propertyValue, log);
else
log.LogInformation("Unable to find Parent with inflow
relationship for " + twinId);
}
Atualizando campos de instância usando APIs
Esta seção do tutorial explica como ouvir as alterações de modelo nos Gêmeos Digitais do Azure, como criação, exclusão de gêmeos ou alteração nas relações entre gêmeos e atualização de campos de instância e hierarquias programaticamente usando APIs de modelo do Time Series Insights. Esse método de atualização do modelo do Time Series Insights geralmente é obtido por meio das funções do Azure. Nos Gêmeos Digitais do Azure, notificações de eventos, como adição ou exclusões de gêmeos, podem ser roteadas serviços downstream, como Hubs de Eventos que, por sua vez, podem ser alimentados para funções do Azure. Mais detalhes sobre roteamento e filtragem de eventos são explicados aqui. O restante desta seção explica o uso de APIs de modelo do Time Series Insights em funções do Azure para atualizar o modelo do Time Series Insights em resposta à adição de gêmeos (um tipo de alteração de modelo) no Azure Digital Twins.
Recebendo e identificando notificação de evento de adição gêmea
[FunctionName("RouteEventsToTsi")]
public async Task Run([EventGridTrigger]EventGridEvent eventGridEvent)
{
try
{
if (eventGridEvent != null && eventGridEvent.Data != null)
{
logger.LogInformation($"EventType: {eventGridEvent.EventType}");
logger.LogInformation($"EventGridEvent: {JsonConvert.SerializeObject(eventGridEvent)}");
//Shape event and Send event data to event hub and tsi
await SendEventToEventHubAsync(eventGridEvent).ConfigureAwait(false);
//If a new twin was created, update the newly created instance in TSI with info retrieved from ADT
if (eventGridEvent.EventType == Constants.TwinCreateEventType)
{
//retrieve building, floor and room of value twin
var twinInfo = await RetrieveTwinInfoAsync(eventGridEvent).ConfigureAwait(false);
//Update Tsi instance with type(sensor type), hierarchy(space hierarchy) and instance fields(twin info retrieved above)
var instance = await CreateInstanceToSendAsync(twinInfo).ConfigureAwait(false);
var instanceToUpdate = new List<TimeSeriesInstance>() { instance };
var response = await tsiClient.TimeSeriesInstances.ExecuteBatchAsync(new InstancesBatchRequest(update: instanceToUpdate)).ConfigureAwait(false);
}
}
}
catch (Exception ex)
{
logger.LogError($"Exception: {ex.Message}");
}
}
Criando o Time Series Insights Client e adicionando detalhes da instância
private async Task<TimeSeriesInstance> CreateInstanceToSendAsync(Dictionary<string, string> twinInfo)
{
try
{
tsiClient = await GetTSIClientAsync().ConfigureAwait(false);
var timeSeriesId = new object[] { twinInfo[Constants.DtId] };
var instances = await tsiClient.TimeSeriesInstances.ExecuteBatchAsync(
new InstancesBatchRequest(
get: new InstancesRequestBatchGetOrDelete(
new IList<object>[] { timeSeriesId }))).ConfigureAwait(false);
var instance = instances.Get.First().Instance;
if (instance != null)
{
instance = await AddHierarchyToInstanceAsync(instance).ConfigureAwait(false);
instance = await AddTypeToInstanceAsync(instance, twinInfo[Constants.TwinType]).ConfigureAwait(false);
instance.InstanceFields = new Dictionary<string, object>
{
{ "Building", twinInfo[Constants.BuildingName] },
{ "Floor", twinInfo[Constants.FloorName] },
{ "Room", twinInfo[Constants.ParentName] }
};
//If value twin is a sensor value twin, add sensor type instance field to diff from spatial value twin
if (twinInfo[Constants.ParentType] == Constants.Sensor)
{
instance.InstanceFields.Add(Constants.SensorType, twinInfo[Constants.TwinType]);
}
return instance;
}
else
{
logger.LogError($"instance with id {twinInfo[Constants.DtId]} not found");
return new TimeSeriesInstance();
}
}
catch (Exception e)
{
logger.LogError(e.Message);
throw;
}
}
Aplicando informações de hierarquia à instância
private async Task<TimeSeriesInstance> AddHierarchyToInstanceAsync(TimeSeriesInstance instance)
{
if (instance.HierarchyIds == null)
{
TimeSeriesHierarchy spacesHierarchy = null;
try
{
var hierarchy = await RunGetHierarchiesAsync(Constants.SpaceHierarchy).ConfigureAwait(false);
spacesHierarchy = hierarchy.First(h => h.Name.Equals(Constants.SpaceHierarchy));
instance.HierarchyIds = new List<Guid?>();
instance.HierarchyIds.Add(spacesHierarchy.Id);
}
catch (Exception ex)
{
logger.LogWarning($"Hierarchy 'space hierarchy' not found, {ex}");
throw;
}
}
return instance;
}
Próximos passos
O terceiro da série de tutoriais é mostrar como consultar dados históricos de Gêmeos Digitais do Azure usando APIs do Time Series Insights. É um trabalho em andamento e a seção será atualizada quando estiver pronta. Enquanto isso, os leitores são incentivados a consultar a documentação da API de consulta de dados do Time Series Insights.