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 do Gêmeos Digitais do Azure a um cluster do Azure Data Explorer para que as atualizações de gráfico sejam automaticamente historiadas no Azure Data Explorer . Essas atualizações historizadas incluem atualizações de propriedade gêmea, eventos de ciclo de vida gêmeo e eventos de ciclo de vida de relacionamento.
Depois que as atualizações de gráfico são historiadas no Azure Data Explorer, você pode executar consultas conjuntas usando o plug-in 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 qual era o estado do gráfico ou para obter insights sobre o comportamento de ambientes modelados. Você também pode usar essas consultas para impulsionar painéis operacionais, enriquecer aplicativos Web 2D e 3D e propiciar experiências imersivas de realidade aumentada/misturada para transmitir o estado atual e histórico de ativos, processos e pessoas modelados nos Gêmeos Digitais do Azure.
Para obter mais informações sobre o 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 da mensagem.
Pré-requisitos: Recursos e permissões
O histórico de dados requer os seguintes recursos:
- Instância dos Gêmeos Digitais do Azure, com uma identidade gerenciada atribuída ao sistema habilitada.
- Namespace de Hubs de Eventos que contém um hub de eventos.
- Cluster do Azure Data Explorer que contém um banco de dados. O cluster deve ter o acesso à rede pública habilitado.
Esses recursos estão conectados ao seguinte fluxo:
Quando o gráfico de gêmeo digital é 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 carimbo de data/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 2022-05-31, apenas as propriedades gêmeas (não eventos de ciclo de vida de gêmeos ou de relacionamento) podem ser registradas. 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, a 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). Opcionalmente, essas permissões podem ser removidas após a configuração do histórico de dados.
- Recurso de Hubs de Eventos: proprietário de dados dos Hubs de Eventos do Azure
- Cluster do Azure Data Explorer: Colaborador (com escopo para todo o cluster ou banco de dados específico)
- Atribuição de entidade de segurança de banco de dados do Azure Data Explorer: Administrador (com escopo para o banco de dados que está sendo usado)
Posteriormente, a instância dos Gêmeos Digitais do Azure deve ter a seguinte permissão no recurso de Hubs de Eventos enquanto o histórico de dados está sendo usado: remetente de dados dos Hubs de Eventos do Azure (você também pode optar por manter o proprietário de dados dos Hubs de Eventos do Azure a partir 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 do Gêmeos Digitais do Azure, hub de eventos ou cluster do Azure Data Explorer), defina essas restrições depois de configurar a conexão do histórico de dados. Para obter mais informações sobre esse processo, consulte Restringir o acesso à rede a recursos do 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 são definidos, você pode 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 propriedade gêmea historizados, que podem usar o nome padrão ou um nome personalizado fornecido. As exclusões de propriedade gêmea podem, opcionalmente, ser incluídas nesta tabela. Você também pode fornecer nomes de tabela 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 historiar esses tipos de evento.
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 dos Gêmeos Digitais do Azure
Se desejar, você pode ter várias instâncias do Azure Digital Twins historize atualizações para o mesmo cluster do Azure Data Explorer.
Cada instância dos Gêmeos Digitais do Azure terá sua própria conexão de histórico de dados direcionada ao mesmo cluster do Azure Data Explorer. No 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 do histórico de dados. Nos esquemas de tabela de histórico de dados, a
ServiceIdcoluna em cada tabela conterá a URL da instância de origem dos Gêmeos Digitais do Azure, para que você possa usar esse campo para resolver qual instância do 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 histórico de dados apresentava apenas atualizações de propriedades gêmeas historiadas. Se você tiver uma conexão de histórico de dados somente de propriedades desse momento, poderá atualizá-la para registrar 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 em seu 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 conexão do histórico de dados original para armazenar atualizações de propriedade gêmea no futuro 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 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 as duas novas tabelas de tipo de evento e para passar o nome da tabela original para a tabela de atualizações de propriedade gêmea. A nova conexão substituirá a antiga e continuará a usar a tabela original para futuras atualizações de propriedade gêmea historizada.
Se você quiser usar todas as novas tabelas: primeiro, exclua sua conexão original do histórico de dados. Em seguida, 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 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 do Azure Digital Twins para excluir uma conexão de histórico de dados. O comando CLI é az dt data-history connection delete.
A exclusão de uma conexão também oferece a opção de limpar recursos associados à conexão do histórico de dados (para o comando 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 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 à 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 do 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 pode interromper suas outras conexões de histórico de dados que dependem desses recursos.
Tipos de dados e esquemas
O histórico de dados historia três tipos de eventos de 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, opcionalmente, incluir 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 do 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 gêmeas 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 |
DateTime | A data/hora em que a mensagem de atualização de propriedade foi processada pelos Gêmeos Digitais do Azure. Esse campo é definido pelo sistema e não pode ser gravável pelos usuários. |
SourceTimeStamp |
DateTime | 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 |
String | A ID da instância de serviço do serviço IoT do Azure registrando o registro em log |
Id |
String | A ID do gêmeo |
ModelId |
String | A DTMI (ID do modelo DTDL) |
Key |
String | O nome da propriedade atualizada |
Value |
Dinâmico | O valor da propriedade atualizada |
RelationshipId |
String | Quando uma propriedade definida em uma relação (em vez de gêmeos ou dispositivos) é atualizada, este campo é preenchido com a ID da relação. Quando uma propriedade de gêmeo é atualizada, este campo fica vazio. |
RelationshipTarget |
String | Quando uma propriedade definida em uma relação (em vez de gêmeos ou dispositivos) é atualizada, este campo é preenchido com a ID do gêmeo pretendido pela relação. Quando uma propriedade de gêmeo é atualizada, este campo fica vazio. |
Action |
String | Essa coluna só existe se você optar por historiar eventos de exclusão de propriedade. Em caso afirmativo, esta coluna contém o tipo de evento de propriedade gêmea (atualizar ou excluir) |
Veja abaixo uma tabela de exemplo de atualizações de propriedade de gêmeo 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 atributo Value 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 dos gêmeos
A tabela do Azure Data Explorer para eventos de ciclo de vida gêmeos tem um nome personalizado que você especificará ao criar a conexão do histórico de dados.
Os dados de série temporal para eventos de ciclo de vida gêmeos são armazenados com o seguinte esquema:
| Atributo | Tipo | Descrição |
|---|---|---|
TwinId |
String | A ID do gêmeo |
Action |
String | O tipo de evento de ciclo de vida gêmeo (criar ou excluir) |
TimeStamp |
DateTime | A data/hora em que o evento de ciclo de vida do gêmeo foi processado pelos Gêmeos Digitais do Azure. Esse campo é definido pelo sistema e não pode ser gravável pelos usuários. |
ServiceId |
String | A ID da instância de serviço do serviço IoT do Azure registrando o registro em log |
ModelId |
String | A DTMI (ID do modelo DTDL) |
Abaixo está uma tabela de exemplo de atualizações de ciclo de vida gêmeo 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 |
| 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 |
| 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 do relacionamento
A tabela do Azure Data Explorer para eventos de ciclo de vida de relacionamento tem um nome personalizado que você especificará ao criar a conexão do histórico de dados.
Os dados de série temporal para eventos de ciclo de vida de relacionamento são armazenados com o seguinte esquema:
| Atributo | Tipo | Descrição |
|---|---|---|
RelationshipId |
String | O ID de relacionamento. Esse campo é definido pelo sistema e não pode ser gravável pelos usuários. |
Name |
String | O nome da relação |
Action |
O tipo de evento do ciclo de vida do relacionamento (criar ou excluir) | |
TimeStamp |
DateTime | A data/hora em que o evento do ciclo de vida do relacionamento foi processado pelos Gêmeos Digitais do Azure. Esse campo é definido pelo sistema e não pode ser gravável pelos usuários. |
ServiceId |
A ID da instância de serviço do serviço IoT do Azure registrando o registro em log | |
Source |
O ID do gêmeo de origem. Este é o ID do gêmeo onde a relação se origina. | |
Target |
O ID de gêmeo de destino. Este é o ID do gêmeo onde a relação chega. |
Abaixo está uma tabela de exemplo de atualizações do ciclo de vida do relacionamento 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 | PasteurizationMachine_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | feeds | Criar | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | contém | Excluir | 2022-12-15 07:16:13.1780 | dairyadtinstance.api.wcus.digitaltwins.azure.net | OsloFábrica | SaltMachine_C0 |
Latência de ingestão de ponta a ponta
As compilações do histórico de dados dos Gêmeos Digitais do Azure se baseiam 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 gráfico sejam disponibilizados para o Azure Data Explorer em menos de dois segundos. A latência extra pode ser introduzida pelo Azure Data Explorer por meio da ingestão dos dados.
Há dois métodos no Azure Data Explorer para ingestão de 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 funcionará melhor se altas taxas de dados de ingestão são esperadas. O Azure Data Explorer usa a ingestão em lote por padrão. A tabela a seguir resume a latência esperada de ponta a ponta no pior cenário:
| Configuração de Data Explorer Azure | Latência de ponta a ponta esperada | Taxa de dados recomendada |
|---|---|---|
| Ingestão de streaming | <12 segundos (<3 segundos típicos) | <4 GB/h |
| Ingestão em lote | Varia (de 12 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)
Caso contrário, se não estiver configurado, o Azure Data Explorer usará a ingestão em lote. As configurações padrão podem levar a dados que estão disponíveis para consulta apenas de 5 a 10 minutos após a atualização para um gêmeo digital ter sido executada. A política de ingestão pode ser alterada, de forma 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 consulta do Azure Data Explorer:
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
Certifique-se de que <table_name> seja substituído pelo nome da tabela que foi configurada para você. MaximumBatchingTimeSpan deve ser definido como o intervalo de lote preferencial. Pode demorar até 5-10 horas para a política entrar em vigor. Você pode ler mais sobre o envio em lote de ingestão no seguinte link: Comando de gerenciamento de política Kusto IngestionBatching.
Ingestão de streaming
A habilitação da ingestão de streaming é um processo de duas etapas:
- Habilite a ingestão de streaming para o cluster. Essa ação precisa ser realizada apenas uma vez. (Aviso: isso terá um efeito sobre a quantidade de armazenamento disponível para o cache frequente e poderá introduzir limitações extras). Para obter instruções, consulte Configurar ingestão de streaming no cluster do Azure Data Explorer.
- Adicione uma política de ingestão de streaming para a tabela desejada. Você pode ler mais sobre a habilitação da ingestão de streaming para o cluster na documentação do Azure Data Explorer: Kusto Comando de gerenciamento de política IngestionBatching Kusto.
Para habilitar a ingestão de streaming para a tabela de histórico de dados dos Gêmeos Digitais do Azure, o comando a seguir deve ser emitido no painel de consulta do Azure Data Explorer:
.alter table <table_name> policy streamingingestion enable
Certifique-se de que <table_name> seja substituído pelo nome da tabela que foi configurada para você. Pode demorar até 5-10 horas para a política entrar em vigor.
Visualize propriedades historizadas
O Azure Digital Twins Explorer, uma ferramenta de desenvolvedor para visualizar e interagir com dados do Azure Digital Twins, oferece um recurso de explorador de histórico de dados para exibir propriedades historizadas ao longo do tempo em um gráfico ou 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 dos ativos 3D.
Para obter informações mais detalhadas sobre como usar o explorador do histórico de dados, consulte Validar e explorar propriedades historiadas.
Observação
Se você encontrar problemas para selecionar uma propriedade na experiência do explorador de histórico de dados visual, isso pode significar que há um erro em algum modelo em sua instância. Por exemplo, ter valores de enum não exclusivos nos atributos de um modelo interromperá esse recurso de visualização. Se isso acontecer, revise suas definições de modelo e verifique se todas as propriedades são válidas.
Próximas etapas
Depois que os dados gêmeos são armazenados em histórico no Azure Data Explorer, você pode usar o plug-in de consulta dos Gêmeos Digitais do Azure para o Azure Data Explorer 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.