Compartilhar via

Histórico de dados dos Gêmeos Digitais do Azure (com o Azure Data Explorer)

O histórico de dados é um recurso de integração dos Gêmeos Digitais do Azure. Ele permite que você conecte uma instância dos Gêmeos Digitais do Azure a um cluster do Azure Data Explorer para que as atualizações de grafo sejam automaticamente historizadas no Azure Data Explorer. Essas atualizações históricas incluem atualizações de propriedades gêmeas, eventos do ciclo de vida gêmeos e eventos do ciclo de vida do relacionamento.

Depois que as atualizações do grafo forem historizadas no Azure Data Explorer, você poderá executar consultas conjuntas usando o plug-in dos Gêmeos Digitais do Azure para o Azure Data Explorer para raciocinar entre gêmeos digitais, seus relacionamentos e dados de série temporal. Isso pode ser usado para olhar para trás no tempo em que o estado do grafo costumava ser ou para obter insights sobre o comportamento de ambientes modelados. Você também pode usar essas consultas para alimentar painéis operacionais, enriquecer aplicativos Web 2D e 3D e promover experiências imersivas de realidade aumentada/misturada para transmitir o estado atual e histórico de ativos, processos e pessoas modeladas nos Gêmeos Digitais do Azure.

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

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

Pré-requisitos: recursos e permissões

O histórico de dados requer os seguintes recursos:

Esses recursos são conectados ao seguinte fluxo:

Diagrama mostrando o fluxo de dados de telemetria do dispositivo nos Gêmeos Digitais do Azure, passando por um hub de eventos até chegar ao Azure Data Explorer.

Quando o grafo digital twin é atualizado, as informações passam pelo hub de eventos para o cluster do Azure Data Explorer de destino, onde o Azure Data Explorer armazena os dados como um registro com data e hora na tabela correspondente.

Ao trabalhar com o histórico de dados, é recomendável usar a versão 2023-01-31 ou posterior das APIs. Com a versão de 31/05/2022, apenas propriedades gêmeas (não eventos de ciclo de vida gêmeo ou de ciclo de vida de relacionamento) podem ser historicizadas. Com versões anteriores, o histórico de dados não está disponível.

Permissões necessárias

Para configurar uma conexão de histórico de dados, sua instância dos Gêmeos Digitais do Azure deve ter as seguintes permissões para acessar os Hubs de Eventos e os recursos do Azure Data Explorer. Essas funções permitem que os Gêmeos Digitais do Azure configurem o hub de eventos e o banco de dados do Azure Data Explorer em seu nome (por exemplo, criando uma tabela no banco de dados). Essas permissões podem ser removidas opcionalmente após a configuração do histórico de dados.

  • Recurso de Hubs de Eventos: Proprietário de Dados de Hubs de Eventos do Azure
  • Cluster do Azure Data Explorer: Colaborador (abrangendo todo o cluster ou um banco de dados específico)
  • Atribuição principal do banco de dados do Azure Data Explorer: Administrador (com escopo para o banco de dados que está sendo usado)

Posteriormente, sua instância do Gêmeos Digitais do Azure deve ter a seguinte permissão no recurso Event Hubs enquanto o histórico de dados estiver sendo usado: Azure Event Hubs Data Sender (você também pode optar por manter o Hubs de Eventos do Azure Data Owner da configuração do histórico de dados).

Essas permissões podem ser atribuídas usando a CLI do Azure ou o portal do Azure.

Se você quiser restringir o acesso à rede aos recursos envolvidos no histórico de dados (sua instância dos Gêmeos Digitais do Azure, hub de eventos ou cluster do Azure Data Explorer), deverá definir essas restrições depois de configurar a conexão de histórico de dados. Para obter mais informações sobre esse processo, consulte Restringir o acesso à rede aos recursos de histórico de dados.

Criar e gerenciar conexão de histórico de dados

Esta seção contém informações para criar, atualizar e excluir uma conexão de histórico de dados.

Criar uma conexão de histórico de dados

Depois que todos os recursos e permissões forem configurados, você poderá usar a CLI do Azure, o portal do Azure ou o SDK dos Gêmeos Digitais do Azure para criar a conexão de histórico de dados entre eles. O conjunto de comandos da CLI é az dt data-history.

O comando sempre criará uma tabela para eventos de propriedades gêmeas historicizados, que pode usar o nome padrão ou um nome personalizado fornecido por você. Exclusões de propriedades gêmeas podem ser opcionalmente incluídas nessa tabela. Você também pode fornecer nomes de tabelas para eventos de ciclo de vida de relacionamento e eventos de ciclo de vida gêmeos, e o comando criará tabelas com esses nomes para historicizar esses tipos de eventos.

Para obter instruções passo a passo sobre como configurar uma conexão de histórico de dados, consulte Criar uma conexão de histórico de dados.

Histórico de várias instâncias do Gêmeos Digitais do Azure

Se desejar, você pode configurar várias instâncias dos Gêmeos Digitais do Azure para registrar atualizações no mesmo cluster do Azure Data Explorer.

Cada instância do Azure Digital Twins terá sua própria conexão de dados históricos direcionada ao mesmo cluster do Azure Data Explorer. Dentro do cluster, as instâncias podem enviar seus dados gêmeos para...

  • um conjunto separado de tabelas no cluster do Azure Data Explorer.
  • o mesmo conjunto de tabelas no cluster do Azure Data Explorer. Para fazer isso, especifique os mesmos nomes de tabela do Azure Data Explorer ao criar as conexões de histórico de dados. Nos esquemas da tabela de histórico de dados, a ServiceId coluna em cada tabela conterá a URL da instância dos Gêmeos Digitais do Azure de origem, para que você possa usar esse campo para resolver qual instância dos Gêmeos Digitais do Azure emitiu cada registro em tabelas compartilhadas.

Atualizar uma conexão de histórico de dados somente de propriedades

Antes de fevereiro de 2023, o recurso de histórico de dados historizava apenas atualizações de propriedades gêmeas. Se você tiver uma conexão de histórico de dados somente de propriedades daquele momento, poderá atualizá-la para historicizar todas as atualizações de gráfico no Azure Data Explorer (incluindo propriedades gêmeas, eventos de ciclo de vida gêmeos e eventos de ciclo de vida de relacionamento).

Isso exigirá a criação de novas tabelas no cluster do Azure Data Explorer para os novos tipos de atualizações historizadas (eventos de ciclo de vida gêmeos e eventos de ciclo de vida de relacionamento). Para eventos de propriedade gêmea, você pode decidir se deseja que a nova conexão continue usando a mesma tabela da sua conexão de histórico de dados original para armazenar atualizações de propriedade gêmea daqui para frente ou se deseja que a nova conexão use um conjunto totalmente novo de tabelas. Em seguida, siga as instruções abaixo para sua preferência.

Se você quiser continuar usando sua tabela existente para atualizações de propriedades gêmeas: Use as instruções em Criar uma conexão de histórico de dados para criar uma nova conexão de histórico de dados com as novas funcionalidades. O nome da conexão do histórico de dados pode ser o mesmo que o original ou um nome diferente. Use as opções de parâmetro para fornecer novos nomes para as duas novas tabelas de tipos de eventos e para passar o nome da tabela original para a tabela de atualizações de propriedades gêmeas. A nova conexão substituirá a antiga e continuará a usar a tabela original para futuras atualizações históricas de propriedades gêmeas.

Se você quiser usar todas as tabelas novas: Primeiro, exclua sua conexão de histórico de dados original. Em seguida, use as instruções em Criar uma conexão de histórico de dados para criar uma conexão de histórico de dados com os novos recursos. O nome da conexão do histórico de dados pode ser o mesmo que o original ou um nome diferente. Use as opções de parâmetro para fornecer novos nomes para todas as três tabelas de tipo de evento.

Excluir uma conexão de histórico de dados

Você pode usar a CLI do Azure, o portal do Azure ou as APIs e SDKs dos Gêmeos Digitais do Azure para excluir uma conexão de histórico de dados. O comando CLI é az dt data-history conexão exclusão.

Excluir uma conexão também oferece a opção de limpar os recursos associados à conexão de histórico de dados (para o comando da CLI, o parâmetro opcional a ser adicionado é --clean true). Se você usar essa opção, o comando excluirá os recursos no Azure Data Explorer que são usados para vincular seu cluster ao hub de eventos, incluindo conexões de dados para o banco de dados e os mapeamentos de ingestão associados à sua tabela. A opção "limpar recursos" não excluirá o hub de eventos real e o cluster do Azure Data Explorer usados para a conexão de histórico de dados.

A limpeza é uma tentativa de melhor esforço e requer que a conta que executa o comando tenha permissão de exclusão para esses recursos.

Observação

Se você tiver várias conexões de histórico de dados que compartilham o mesmo hub de eventos ou cluster do Azure Data Explorer, usar a opção "limpar recursos" ao excluir uma dessas conexões poderá interromper suas outras conexões de histórico de dados que dependem desses recursos.

Tipos de dados e esquemas

O histórico de dados historiciza três tipos de eventos da sua instância do Gêmeos Digitais do Azure no Azure Data Explorer: eventos de ciclo de vida de relacionamento, eventos de ciclo de vida de gêmeos e atualizações de propriedades gêmeas (que podem incluir, opcionalmente, exclusões de propriedades gêmeas). Cada um desses tipos de evento é armazenado em sua própria tabela dentro do banco de dados do Azure Data Explorer, o que significa que o histórico de dados mantém três tabelas no total. Você pode especificar nomes personalizados para as tabelas ao configurar a conexão de histórico de dados.

O restante desta seção descreve as três tabelas do Azure Data Explorer em detalhes, incluindo o esquema de dados para cada tabela.

Atualizações de propriedades gêmeas

A tabela do Azure Data Explorer para atualizações de propriedades de gêmeos tem um nome padrão de AdtPropertyEvents. Você pode deixar o nome padrão ao criar a conexão ou especificar um nome de tabela personalizado.

Os dados de série temporal para atualizações de propriedades gêmeas são armazenados com o seguinte esquema:

Atributo Tipo Descrição
TimeStamp Data e Hora Data/hora em que a mensagem de atualização da propriedade foi processada pelo Gêmeos Digitais do Azure. Esse campo é definido pelo sistema e não é gravável pelos usuários.
SourceTimeStamp Data e Hora Uma propriedade gravável opcional representando o carimbo de data/hora quando a atualização da propriedade foi observada no mundo real. Essa propriedade só pode ser gravada usando a versão de 31/05/2022 das APIs/SDKs dos Gêmeos Digitais do Azure, e o valor deve estar em conformidade com o formato de data e hora ISO 8601. Para obter mais informações sobre como atualizar essa propriedade, consulte Atualizar sourceTime de uma propriedade.
ServiceId fio O ID da instância de serviço do serviço IoT do Azure que registra o registro
Id fio A ID do gêmeo
ModelId fio O ID do modelo DTDL (DTMI)
Key fio O nome da propriedade atualizada
Value Dinâmico O valor da propriedade recentemente atualizada
RelationshipId fio Quando uma propriedade definida em uma relação (em vez de gêmeos ou dispositivos) é atualizada, esse campo é preenchido com a ID da relação. Quando uma propriedade de gêmeo é atualizada, esse campo fica vazio.
RelationshipTarget fio Quando uma propriedade definida em um relacionamento (ao contrário de gêmeos ou dispositivos) é atualizada, este campo é preenchido com o ID do gêmeo alvo do relacionamento. Quando uma propriedade de gêmeo é atualizada, esse campo fica vazio.
Action fio Esta coluna só existirá se você optar por historizar eventos de exclusão de propriedade. Se sim, essa coluna contém o tipo de evento de propriedade gêmea (atualização ou exclusão)

Veja abaixo um exemplo de tabela de atualizações de propriedades de gêmeos armazenadas no Azure Data Explorer.

TimeStamp SourceTimeStamp ServiceId Id ModelId Key Value RelationshipTarget RelationshipID
2022-12-15 20:23:29.8697482 2022-12-15 20:22:14.3854859 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A01 dtmi:assetGen:PasteurizationMachine;1 Saída 130
2022-12-15 20:23:39.3235925 2022-12-15 20:22:26.5837559 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A01 dtmi:assetGen:PasteurizationMachine;1 Saída 140
2022-12-15 20:23:47.078367 2022-12-15 20:22:34.9375957 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A01 dtmi:assetGen:PasteurizationMachine;1 Saída 130
2022-12-15 20:23:57.3794198 2022-12-15 20:22:50.1028562 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A01 dtmi:assetGen:PasteurizationMachine;1 Saída 123

Representando propriedades com vários campos

Pode ser necessário armazenar uma propriedade com vários campos. Essas propriedades são representadas com um objeto JSON no Value atributo do esquema.

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

Eventos do ciclo de vida de gêmeos

A tabela do Azure Data Explorer para eventos de ciclo de vida gêmeo tem um nome personalizado que você especificará ao criar a conexão de histórico de dados.

Os dados de série temporal para eventos do ciclo de vida gêmeo são armazenados com o seguinte esquema:

Atributo Tipo Descrição
TwinId fio A ID do gêmeo
Action fio O tipo de evento de ciclo de vida gêmeo (criar ou excluir)
TimeStamp Data e Hora A data/hora em que o evento do ciclo de vida gêmeo foi processado pelo Gêmeos Digitais do Azure. Esse campo é definido pelo sistema e não é gravável pelos usuários.
ServiceId fio O ID da instância de serviço do serviço IoT do Azure que registra o registro
ModelId fio O ID do modelo DTDL (DTMI)

Abaixo está uma tabela de exemplo de atualizações de ciclo de vida duplo armazenadas no Azure Data Explorer.

TwinId Action TimeStamp ServiceId ModelId
PasteurizationMachine_A01 Criar 2022-12-15 07:14:12.4160 dairyadtinstance.api.wcus.digitaltwins.azure.net dtmi:assetGen:PasteurizationMachine;1
Máquina de Pasteurização A02 (PasteurizationMachine_A02) Criar 2022-12-15 07:14:12.4210 dairyadtinstance.api.wcus.digitaltwins.azure.net dtmi:assetGen:PasteurizationMachine;1
SaltMachine_C0 Criar 2022-12-15 07:14:12.5480 dairyadtinstance.api.wcus.digitaltwins.azure.net dtmi:assetGen:SaltMachine;1
Máquina de Pasteurização A02 (PasteurizationMachine_A02) Excluir 2022-12-15 07:15:49.6050 dairyadtinstance.api.wcus.digitaltwins.azure.net dtmi:assetGen:PasteurizationMachine;1

Eventos do ciclo de vida da relação

A tabela do Azure Data Explorer para eventos de ciclo de vida de relação tem um nome personalizado que você especificará ao criar a conexão de histórico de dados.

Os dados de série temporal para eventos de ciclo de vida de relação são armazenados com o seguinte esquema:

Atributo Tipo Descrição
RelationshipId fio O ID do relacionamento. Esse campo é definido pelo sistema e não é gravável pelos usuários.
Name fio O nome da relação
Action O tipo de evento de ciclo de vida da relação (criar ou excluir)
TimeStamp Data e Hora A data/hora em que o evento do ciclo de vida do relacionamento foi processado pelo Gêmeos Digitais do Azure. Esse campo é definido pelo sistema e não é gravável pelos usuários.
ServiceId O ID da instância de serviço do serviço IoT do Azure que registra o registro
Source O ID gêmeo de origem. Esta é a ID do gêmeo de onde a relação se origina.
Target O ID do gêmeo alvo. Esse é o ID do gêmeo onde o relacionamento chega.

Veja abaixo um exemplo de tabela de atualizações do ciclo de vida da relação armazenadas no Azure Data Explorer.

RelationshipId Name Action TimeStamp ServiceId Source Target
PasteurizationMachine_A01_feeds_Relationship0 feeds Criar 2022-12-15 07:16:12.7120 dairyadtinstance.api.wcus.digitaltwins.azure.net PasteurizationMachine_A01 SaltMachine_C0
PasteurizationMachine_A02_feeds_Relationship0 feeds Criar 2022-12-15 07:16:12.7160 dairyadtinstance.api.wcus.digitaltwins.azure.net Máquina de Pasteurização A02 (PasteurizationMachine_A02) SaltMachine_C0
PasteurizationMachine_A03_feeds_Relationship0 feeds Criar 2022-12-15 07:16:12.7250 dairyadtinstance.api.wcus.digitaltwins.azure.net MáquinaDePasteurização_A03 SaltMachine_C1
OsloFactory_contains_Relationship0 contém Excluir 2022-12-15 07:16:13.1780 dairyadtinstance.api.wcus.digitaltwins.azure.net OsloFactory SaltMachine_C0

Latência de ingestão de ponta a ponta

O histórico de dados dos Gêmeos Digitais do Azure baseia-se no mecanismo de ingestão existente fornecido pelo Azure Data Explorer. Os Gêmeos Digitais do Azure garantirão que os eventos de atualização de grafo sejam disponibilizados para o Azure Data Explorer em menos de dois segundos. A latência extra pode ser introduzida pelo Azure Data Explorer ingerindo os dados.

Há dois métodos no Azure Data Explorer para ingerir dados: ingestão em lote e ingestão de streaming. Você pode configurar esses métodos de ingestão para tabelas individuais de acordo com suas necessidades e o cenário específico de ingestão de dados.

A ingestão de streaming tem a menor latência. No entanto, devido à sobrecarga de processamento, esse modo só deverá ser usado se menos de 4 GB de dados forem ingeridos a cada hora. A ingestão em lote funciona melhor se forem esperadas altas taxas de ingestão de dados. O Azure Data Explorer usa a ingestão em lote por padrão. A tabela a seguir resume a latência de ponta a ponta no pior cenário esperada.

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

O restante desta seção contém detalhes para habilitar cada tipo de ingestão.

Ingestão em lote (padrão)

Se não estiver configurado de outra forma, o Azure Data Explorer usará a ingestão em lote. As configurações padrão podem fazer com que os dados fiquem disponíveis para consulta apenas de 5 a 10 minutos após a execução de uma atualização para um gêmeo digital. A política de ingestão pode ser alterada, de modo 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, o seguinte comando deve ser emitido na exibição de consulta do Azure Data Explorer:

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

Verifique se <table_name> foi substituído pelo nome da tabela que foi configurada para você. MaximumBatchingTimeSpan deve ser definido como o intervalo de lote preferencial. Pode levar de 5 a 10 minutos para que a política entre em vigor. Você pode ler mais sobre o processamento em lote de ingestão no seguinte link: Comando de gerenciamento de política Kusto IngestionBatching.

Ingestão de streaming

Habilitar a ingestão de streaming é um processo de duas etapas:

  1. Habilite a ingestão de streaming para seu cluster. Essa ação só precisa ser feita uma vez. (Aviso: isso terá um efeito sobre a quantidade de armazenamento disponível para cache quente e poderá introduzir limitações extras). Para obter instruções, consulte Configurar a ingestão de streaming no cluster do Azure Data Explorer.
  2. Adicione uma política de ingestão de streaming para a tabela desejada. Você pode ler mais sobre como habilitar a ingestão de streaming para seu cluster na documentação do Azure Data Explorer: comando de gerenciamento de política Kusto IngestionBatching.

Para habilitar a ingestão de streaming para sua tabela de histórico de dados dos Gêmeos Digitais do Azure, o seguinte comando deve ser emitido no painel de consulta do Azure Data Explorer:

.alter table <table_name> policy streamingingestion enable

Verifique se <table_name> foi substituído pelo nome da tabela que foi configurada para você. Pode levar de 5 a 10 minutos para que a política entre em vigor.

Visualizar propriedades historizadas

O Azure Digital Twins Explorer, uma ferramenta de desenvolvedor para visualizar e interagir com dados dos Gêmeos Digitais do Azure, oferece um recurso do Gerenciador de Histórico de Dados para exibir propriedades historizadas ao longo do tempo em um gráfico ou uma tabela. Esse recurso também está disponível no 3D Scenes Studio, um ambiente 3D imersivo para dar aos Gêmeos Digitais do Azure o contexto visual de ativos 3D.

Captura de tela do gerenciador de histórico de dados para o 3D Scenes Studio.

Para obter informações mais detalhadas sobre como usar o gerenciador de histórico de dados, consulte Validar e explorar propriedades historizadas.

Observação

Se você encontrar problemas ao selecionar uma propriedade na experiência do gerenciador de histórico de dados visual, isso pode significar que há um erro em algum modelo em sua instância. Por exemplo, ter valores enum não únicos nos atributos de um modelo falhará esse recurso de visualização. Se isso acontecer, reveja as definições do seu modelo e certifique-se de que todas as propriedades sejam válidas.

Próximas etapas

Depois que os dados gêmeos forem historizados no Azure Data Explorer, você poderá usar o plug-in de consulta dos Gêmeos Digitais do Azure para o Azure Data Explorer para executar consultas nos dados. Leia mais sobre o plug-in aqui: Consultando com o plug-in do Azure Data Explorer.

Ou aprofunde-se no histórico de dados com instruções de criação e um cenário de exemplo: criar uma conexão de histórico de dados.

  • Last updated on