Histórico de dados do Azure Digital Twins (com o Azure Data Explorer)

O histórico de dados é uma funcionalidade de integração do Azure Digital Twins. Permite-lhe ligar uma instância do Azure Digital Twins a um cluster do Azure Data Explorer para que as atualizações de propriedades de duplos digitais sejam automaticamente historizadas no Azure Data Explorer.

Assim que os valores das propriedades duplos forem historizados no Azure Data Explorer, pode executar consultas conjuntas com o plug-in do Azure Digital Twins para o Azure Data Explorer para raciocinar entre duplos digitais, relações e dados de série temporal para obter informações sobre o comportamento dos ambientes modelados. Também pode utilizar estas consultas para alimentar dashboards operacionais, enriquecer aplicações Web 2D e 3D e impulsionar experiências envolventes de realidade aumentada/mista para transmitir o estado atual e histórico dos recursos, processos e pessoas modeladas no Azure Digital Twins.

Para obter mais informações sobre uma introdução ao histórico de dados, incluindo uma demonstração rápida, veja o seguinte vídeo de apresentação de IoT:

Recursos e fluxo de dados

O histórico de dados requer os seguintes recursos:

Estes recursos estão ligados ao fluxo seguinte:

Diagrama a mostrar o fluxo de dados telemétricos para o Azure Digital Twins, através de um hub de eventos, para o Azure Data Explorer.

Os dados passam por estes recursos por esta ordem:

  1. É atualizada uma propriedade de um duplo digital no Azure Digital Twins.
  2. O histórico de dados reencaminha uma mensagem que contém o valor de propriedade e metadados atualizados do duplo para o hub de eventos.
  3. O hub de eventos reencaminha a mensagem para o cluster Data Explorer do Azure de destino.
  4. O cluster do Azure Data Explorer mapeia os campos de mensagens para o esquema do histórico de dados e armazena os dados como um registo com carimbo de data/hora numa tabela do histórico de dados.

Ao trabalhar com o histórico de dados, utilize a versão 2022-05-31 das APIs.

Histórico de várias instâncias do Azure Digital Twins

Se quiser, pode ter várias instâncias do Azure Digital Twins a históricor atualizações de propriedades de duplos para o mesmo cluster do Azure Data Explorer.

Cada instância do Azure Digital Twins terá a sua própria ligação de histórico de dados direcionada para o mesmo cluster de Data Explorer do Azure. No cluster, as instâncias podem enviar os respetivos dados duplos para...

  • tabelas diferentes no cluster de Data Explorer do Azure.
  • a mesma tabela no cluster do Azure Data Explorer. Para tal, especifique o mesmo nome da tabela Data Explorer do Azure ao criar as ligações do histórico de dados. No esquema da tabela do histórico de dados, a ServiceId coluna irá conter o URL da instância do Azure Digital Twins de origem, para que possa utilizar este campo para resolver que instância do Azure Digital Twins emitiu cada registo.

Criar uma ligação do histórico de dados

Assim que todos os recursos e permissões estiverem configurados, pode utilizar a CLI do Azure, portal do Azure ou o SDK do Azure Digital Twins para criar a ligação do histórico de dados entre os mesmos. O conjunto de comandos da CLI é az dt data-history.

Para obter instruções passo a passo sobre como configurar uma ligação do histórico de dados, veja Utilizar o histórico de dados com o Azure Data Explorer.

Permissões obrigatórias

Para configurar uma ligação do histórico de dados, a instância do Azure Digital Twins tem de ter as seguintes permissões para aceder aos Hubs de Eventos e aos recursos do Azure Data Explorer. Estas funções permitem ao Azure Digital Twins configurar o hub de eventos e a base de dados do Azure Data Explorer em seu nome (por exemplo, criar uma tabela na base de dados). Opcionalmente, estas permissões podem ser removidas após a configuração do histórico de dados.

  • Recurso dos Hubs de Eventos: Proprietário de Dados do Hubs de Eventos do Azure
  • Cluster de Data Explorer do Azure: Contribuidor (no âmbito de todo o cluster ou base de dados específica)
  • Atribuição do principal da base de dados do Azure Data Explorer: Administração (no âmbito da base de dados que está a ser utilizada)

Mais tarde, a instância do Azure Digital Twins tem de ter a seguinte permissão no recurso dos Hubs de Eventos enquanto o histórico de dados está a ser utilizado: Hubs de Eventos do Azure Remetente de Dados (também pode optar por manter Hubs de Eventos do Azure Proprietário de Dados da configuração do histórico de dados).

Estas permissões podem ser atribuídas com a CLI do Azure ou portal do Azure.

Esquema de dados

Os dados de série temporal para atualizações de propriedades de duplos são armazenados no Azure Data Explorer com o seguinte esquema:

Atributo Tipo Description
TimeStamp DateTime A data/hora em que a mensagem de atualização da propriedade foi processada pelo Azure Digital Twins. Este campo é definido pelo sistema e não é gravável pelos utilizadores.
SourceTimeStamp DateTime Uma propriedade opcional gravável que representa o carimbo de data/hora quando a atualização da propriedade foi observada no mundo real. Esta propriedade só pode ser escrita com a versão 2022-05-31 das APIs/SDKs do Azure Digital Twins e o valor tem de estar em conformidade com o formato de data e hora ISO 8601. Para obter mais informações sobre como atualizar esta propriedade, consulte Atualizar o sourceTime de uma propriedade.
ServiceId String O ID da instância de serviço do serviço IoT do Azure a registar o registo
Id String O ID duplo
ModelId String O ID do modelo DTDL (DTMI)
Key String O nome da propriedade atualizada
Value Dinâmica O valor da propriedade atualizada
RelationshipId String Quando uma propriedade definida numa relação (por oposição a duplos ou dispositivos) é atualizada, este campo é preenchido com o ID da relação. Quando uma propriedade de duplo é atualizada, este campo está vazio.
RelationshipTarget String Quando uma propriedade definida numa relação (por oposição a duplos ou dispositivos) é atualizada, este campo é preenchido com o ID duplo do duplo visado pela relação. Quando uma propriedade de duplo é atualizada, este campo está vazio.

Segue-se um exemplo de tabela de atualizações de propriedades de duplos armazenadas no Azure Data Explorer.

TimeStamp SourceTimeStamp ServiceId Id ModelId Key Value RelationshipTarget RelationshipID
2021-06-30T20:23:29.8697482Z 2021-06-30T20:22:14.3854859Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Saída 130
2021-06-30T20:23:39.3235925Z 2021-06-30T20:22:26.5837559Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Saída 140
2021-06-30T20:23:47.078367Z 2021-06-30T20:22:34.9375957Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Saída 130
2021-06-30T20:23:57.3794198Z 2021-06-30T20:22:50.1028562Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Saída 123

Representar propriedades com vários campos

Poderá ter de armazenar uma propriedade com vários campos. Estas propriedades são representadas com um objeto JSON no Value atributo do esquema.

Por exemplo, se estiver a representar uma propriedade com três campos para roll, pitch e yaw, o histórico de dados irá armazenar o seguinte objeto JSON como o Value: {"roll": 20, "pitch": 15, "yaw": 45}.

Preços

As mensagens emitidas pelo histórico de dados são medidas na dimensão preços da mensagem.

Latência de ingestão ponto a ponto

O histórico de dados do Azure Digital Twins baseia-se no mecanismo de ingestão existente fornecido pelo Azure Data Explorer. O Azure Digital Twins irá garantir que as atualizações de propriedades são disponibilizadas ao Azure Data Explorer em menos de dois segundos. A latência adicional pode ser introduzida pelo Azure Data Explorer ingerir os dados.

Existem dois métodos no Azure Data Explorer para ingerir dados: ingestão de lotes e ingestão de transmissão em fluxo. Pode configurar estes métodos de ingestão para tabelas individuais de acordo com as suas necessidades e o cenário específico de ingestão de dados.

A ingestão de transmissão em fluxo tem a latência mais baixa. No entanto, devido à sobrecarga de processamento, este modo só deve ser utilizado se forem ingeridos menos de 4 GB de dados por hora. A ingestão de lotes funciona melhor se forem esperadas taxas de dados de ingestão elevadas. O Azure Data Explorer utiliza a ingestão de lotes por predefinição. A tabela seguinte resume a latência ponto a ponto mais esperada:

Configuração do Azure Data Explorer Latência ponto a ponto esperada Taxa de dados recomendada
Ingestão em transmissão em fluxo <12 segundos (<3 segundos típico) <4 GB/h
Ingestão de lotes Varia (12 segundos a 15 m, dependendo da configuração) >4 GB/h

O resto desta secção contém detalhes para ativar cada tipo de ingestão.

Ingestão de lotes (predefinição)

Caso contrário, o Azure Data Explorer utilizará a ingestão de lotes. As predefinições podem levar a que os dados fiquem disponíveis para consulta apenas 5 a 10 minutos após a execução de uma atualização para um duplo digital. A política de ingestão pode ser alterada, de modo a que o processamento em lotes ocorra no máximo a cada 10 segundos (no mínimo; ou 15 minutos no máximo). Para alterar a política de ingestão, tem de ser emitido o seguinte comando na vista de consulta Data Explorer do Azure:

.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}' 

Certifique-se de que <table_name> é substituído pelo nome da tabela que foi configurada para si. MaximumBatchingTimeSpan deve ser definido como o intervalo de criação de batches preferido. A política pode demorar entre 5 a 10 minutos a entrar em vigor. Pode ler mais sobre a criação de batches de ingestão na seguinte ligação: Comando de gestão de políticas Kusto IngestionBatching.

Ingestão em transmissão em fluxo

A ativação da ingestão de transmissão em fluxo é um processo de dois passos:

  1. Ative a ingestão de transmissão em fluxo para o cluster. Esta ação só tem de ser efetuada uma vez. (Aviso: se o fizer, terá efeito na quantidade de armazenamento disponível para a cache frequente e poderá introduzir limitações adicionais). Para obter instruções, veja Configurar a ingestão de transmissão em fluxo no cluster do Azure Data Explorer.
  2. Adicione uma política de ingestão de transmissão em fluxo para a tabela pretendida. Pode ler mais sobre como ativar a ingestão de transmissão em fluxo para o cluster na documentação do Azure Data Explorer: Comando de gestão de políticas Kusto IngestionBatching.

Para ativar a ingestão de transmissão em fluxo para a tabela do histórico de dados do Azure Digital Twins, tem de ser emitido o seguinte comando no painel de consulta Data Explorer do Azure:

.alter table <table_name> policy streamingingestion enable 

Certifique-se de que <table_name> é substituído pelo nome da tabela que foi configurada para si. A política pode demorar entre 5 a 10 minutos a entrar em vigor.

Passos seguintes

Depois de os dados duplos serem historizados no Azure Data Explorer, pode utilizar o plug-in de consulta do Azure Digital Twins para o Azure Data Explorer para executar consultas nos dados. Leia mais sobre o plug-in aqui: Consultar com o plug-in do Azure Data Explorer.

Em alternativa, aprofunde o histórico de dados com um cenário de exemplo neste procedimento: Utilizar o histórico de dados com o Azure Data Explorer.