Histórico de dados do Azure Digital Twins (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 Azure Digital Twins a um cluster do Azure Data Explorer para que as atualizações de gráficos sejam automaticamente historizadas no Azure Data Explorer . Essas atualizações históricas incluem atualizações de propriedades gêmeas, eventos de ciclo de vida gêmeos e eventos de ciclo de vida de relacionamento.
Depois que as atualizações de gráficos são registradas 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éries temporais. Isso pode ser usado para olhar para trás no tempo para o que o estado do gráfico costumava ser, ou para obter insights sobre o comportamento de ambientes modelados. Também pode utilizar estas consultas para ligar dashboards operacionais, melhorar aplicações Web 2D e 3D e realizar experiências de realidade mista/aumentada envolventes para transmitir o estado atual e histórico dos ativos, processos e pessoas modelados no Azure Digital Twins.
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 da IoT:
As mensagens emitidas pelo histórico de dados são medidas sob a dimensão de preço da mensagem.
Pré-requisitos: Recursos e permissões
O histórico de dados requer os seguintes recursos:
- Instância do Azure Digital Twins, com uma identidade gerenciada atribuída ao sistema habilitada.
- Espaço de nomes 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 de destino do Azure Data Explorer, onde o Azure Data Explorer armazena os dados como um registro com carimbo de data/hora na tabela correspondente.
Ao trabalhar com 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 propriedades gêmeas (não eventos de ciclo de vida gêmeo ou ciclo de vida de relacionamento) podem ser historizadas. Com versões anteriores, o histórico de dados não está disponível.
Permissões obrigatórias
Para configurar uma conexão de histórico de dados, sua instância do Azure Digital Twins 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 principal de banco de dados do Azure Data Explorer: Admin (escopo para o banco de dados que está sendo usado)
Mais tarde, sua instância de Gêmeos Digitais do Azure deve ter a seguinte permissão no recurso Hubs de Eventos enquanto o histórico de dados estiver 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 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 quiser restringir o acesso à rede aos recursos envolvidos no histórico de dados (sua instância do Azure Digital Twins, 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 aos 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 estiverem 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 do 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 historizada, que pode usar o nome padrão ou um nome personalizado fornecido. Exclusões de propriedades gêmeas podem ser incluídas opcionalmente nesta tabela. Você também pode fornecer nomes de tabela para eventos do ciclo de vida do relacionamento e eventos do ciclo de vida gêmeos, e o comando criará tabelas com esses nomes para historizar 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 Azure Digital Twins
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 do Azure Digital Twins terá sua própria conexão de histórico de dados 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 coluna em cada tabela conterá a
ServiceIdURL da instância de origem dos Gêmeos Digitais do Azure, 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 histórico de dados apresentava apenas atualizações históricas de propriedades gêmeas. Se você tiver uma conexão de histórico de dados somente de propriedades desse momento, poderá atualizá-la para historiar todas as atualizações de gráfico para o 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 históricas (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 original do histórico de dados 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 propriedades gêmeas. A nova conexão substituirá a antiga e continuará a usar a tabela original para futuras atualizações de propriedade gêmea histórica.
Se você quiser usar todas as novas tabelas: 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 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 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 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 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.
Nota
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 historiza três tipos de eventos da sua instância do Azure Digital Twins no Azure Data Explorer: eventos do ciclo de vida do relacionamento, eventos do ciclo de vida do gêmeo e atualizações de propriedade gêmea (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éries temporais para atualizações de propriedades gêmeas são armazenados com o seguinte esquema:
| Atributo | Type | Description |
|---|---|---|
TimeStamp |
DateTime | A data/hora em que a mensagem de atualização de propriedade foi processada pelos Gêmeos Digitais do Azure. Este campo é definido pelo sistema e não pode ser gravado 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. Essa propriedade só pode ser gravada usando a versão 2022-05-31 das APIs/SDKs do Azure Digital Twins 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 |
Id |
String | O ID gêmeo |
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 em um relacionamento (em oposição a gêmeos ou dispositivos) é atualizada, esse campo é preenchido com a ID do relacionamento . Quando uma propriedade gêmea é atualizada, esse campo está vazio. |
RelationshipTarget |
String | Quando uma propriedade definida em um relacionamento (ao contrário de gêmeos ou dispositivos) é atualizada, esse campo é preenchido com a ID do gêmeo alvo da relação. Quando uma propriedade gêmea é atualizada, esse campo está vazio. |
Action |
String | Esta coluna só existe se você optar por historizar eventos de exclusão de propriedade. Em caso afirmativo, esta coluna contém o tipo de evento de propriedade gêmea (atualizar ou excluir) |
Abaixo está uma tabela de exemplo de atualizações de propriedades gêmeas 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
Talvez seja 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 de ciclo de vida 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éries temporais para eventos de ciclo de vida gêmeos são armazenados com o seguinte esquema:
| Atributo | Type | Description |
|---|---|---|
TwinId |
String | O ID 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 do ciclo de vida do gêmeo foi processado pelos Gêmeos Digitais do Azure. Este campo é definido pelo sistema e não pode ser gravado pelos utilizadores. |
ServiceId |
String | A ID da instância de serviço do serviço IoT do Azure registrando o registro |
ModelId |
String | O ID do modelo DTDL (DTMI) |
Abaixo está uma tabela de exemplo de atualizações de ciclo de vida gêmeas 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 | Eliminar | 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 do ciclo de vida do relacionamento tem um nome personalizado que você especificará ao criar a conexão do histórico de dados.
Os dados de séries temporais para eventos do ciclo de vida do relacionamento são armazenados com o seguinte esquema:
| Atributo | Type | Description |
|---|---|---|
RelationshipId |
String | O ID da relação. Este campo é definido pelo sistema e não pode ser gravado pelos utilizadores. |
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 da relação foi processado pelos Gêmeos Digitais do Azure. Este campo é definido pelo sistema e não pode ser gravado pelos utilizadores. |
ServiceId |
A ID da instância de serviço do serviço IoT do Azure registrando o registro | |
Source |
O ID gêmeo de origem. Este é o ID do gémeo onde a relação se origina. | |
Target |
O ID gêmeo alvo. Este é o ID do gémeo onde chega a relação. |
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 | Alimentação | Criar | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | Alimentação | Criar | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | Alimentação | Criar | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | contém | Eliminar | 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
O histórico de dados do Azure Digital Twins 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 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 ingerindo os 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ó deve 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 dados de ingestão. 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 esperada no pior caso:
| Configuração do Azure Data Explorer | Latência esperada de ponta a ponta | Taxa de dados recomendada |
|---|---|---|
| Ingestão em transmissão em fluxo | <12 seg (<3 seg típico) | <4 GB / hora |
| Ingestão em lote | Varia (12 seg-15 m, dependendo da configuração) | >4 GB / hora |
O restante desta seção contém detalhes para permitir cada tipo de ingestão.
Ingestão em lote (padrão)
Se não configurado de outra forma, o Azure Data Explorer usará a ingestão em lote. As configurações padrão podem levar a que os dados fiquem disponíveis para consulta apenas 5-10 minutos após uma atualização para um gêmeo digital ter sido executada. A política de ingestão pode ser alterada, de modo que o processamento em lote 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 no modo de exibição de consulta do Azure Data Explorer:
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
Certifique-se de que é substituído pelo nome da tabela que <table_name> foi configurada para você. MaximumBatchingTimeSpan deve ser definido para o intervalo de lote preferido. Pode levar de 5 a 10 minutos para que a política entre em vigor. Você pode ler mais sobre o lote de ingestão no seguinte link: Kusto IngestionBatching policy management command.
Ingestão em transmissão em fluxo
Habilitar a ingestão de streaming é um processo de 2 etapas:
- Habilite a ingestão de streaming para seu cluster. Esta ação só tem de ser feita uma vez. (Aviso: Isso terá um efeito sobre a quantidade de armazenamento disponível para hot cache e pode introduzir limitações extras). Para obter instruções, consulte Configurar a ingestão de streaming em seu cluster do Azure Data Explorer.
- 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: Kusto IngestionBatching policy management command.
Para habilitar a ingestão de streaming para sua tabela de histórico de dados do Azure Digital Twins, o seguinte comando deve ser emitido no painel de consulta do Azure Data Explorer:
.alter table <table_name> policy streamingingestion enable
Certifique-se de que é substituído pelo nome da tabela que <table_name> foi configurada para você. Pode levar de 5 a 10 minutos para que a política entre em vigor.
Visualize propriedades historizadas
O Azure Digital Twins Explorer, uma ferramenta de desenvolvedor para visualizar e interagir com dados de Gêmeos Digitais do Azure, oferece um recurso de explorador de histórico de dados para exibir propriedades históricas 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 de histórico de dados, consulte Validar e explorar propriedades historizadas.
Nota
Se você encontrar problemas ao 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 quebrará esse recurso de visualização. Se isso acontecer, revise as definições do modelo e verifique se todas as propriedades são válidas.
Próximos passos
Depois que os dados de gêmeos tiverem sido históricos no Azure Data Explorer, você poderá usar o plug-in de consulta de 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.