Plug-in de consulta dos Gêmeos Digitais do Azure para o Azure Data Explorer

  • Artigo

Este artigo explica sobre o plug-in de consulta dos Gêmeos Digitais do Azure para o Azure Data Explorer, como usar os dados de IoT do Azure Data Explorer com os Gêmeos Digitais do Azure, como mapear dados entre o Azure Data Explorer e os Gêmeos Digitais do Azure e muito mais.

O plug-in dos Gêmeos Digitais do Azure para o Azure Data Explorer permite que você execute consultas do Azure Data Explorer que acessam e combinam dados entre o grafo dos Gêmeos Digitais do Azure e o banco de dados de séries temporais do Azure Data Explorer. Use o plug-in para contextualizar dados de série temporal diferentes através de raciocínio nos gêmeos digitais e em suas relações para obter insights sobre o comportamento de ambientes modelados.

Por exemplo, com esse plug-in, você pode gravar uma consulta do Kusto que:

  1. seleciona gêmeos digitais de interesse através do plug-in de consulta dos Gêmeos Digitais do Azure,
  2. une esses gêmeos em relação às respectivas séries temporais no Azure Data Explorer e, em seguida
  3. executa análise de série temporal avançada nesses gêmeos.

A combinação de dados de um grafo de gêmeos nos Gêmeos Digitais do Azure com dados de série temporal no Azure Data Explorer pode ajudá-lo a entender o comportamento operacional de várias partes da sua solução.

Usando o plug-in

Você pode invocar o plug-in em uma consulta do Kusto com o comando a seguir. Há dois espaços reservados, <Azure-Digital-Twins-endpoint> e <Azure-Digital-Twins-query>, que são cadeias de caracteres que representam o ponto de extremidade da instância dos Gêmeos Digitais do Azure e a consulta dos Gêmeos Digitais do Azure, respectivamente.

evaluate azure_digital_twins_query_request(<Azure-Digital-Twins-endpoint>, <Azure-Digital-Twins-query>)

O plug-in funciona chamando a API de Consulta de Gêmeos Digitais do Azure e a estrutura da linguagem de consulta é a mesma de quando se usa a API, com duas exceções:

  • Não há suporte para o caractere curinga * na cláusula SELECT. Em vez disso, as consultas de Gêmeo Digital do Azure que são executadas usando o plug-in devem usar aliases na cláusula SELECT.

    Por exemplo, considere a consulta dos Gêmeos Digitais do Azure que é executada usando a API:

    SELECT * FROM DIGITALTWINS

    Para executar essa consulta ao usar o plug-in, ele deve ser reescrito da seguinte maneira:

    SELECT T FROM DIGITALTWINS T

  • Os nomes de coluna retornados pelo plug-in não podem começar com um $. O uso de aliases na cláusula SELECT também ajudará a evitar esse cenário.

    Por exemplo, considere a consulta dos Gêmeos Digitais do Azure que é executada usando a API:

    SELECT T.$dtId, T.Temperature FROM DIGITALTWINS T

    Para executar essa consulta ao usar o plug-in, ele deve ser reescrito da seguinte maneira:

    SELECT T.$dtId as tid, T.Temperature FROM DIGITALTWINS T

Importante

O usuário do plug-in deve receber a função de Leitor de Dados de Gêmeos Digitais do Azure ou a função de Proprietário de Dados de Gêmeos Digitais do Azure, pois o token Microsoft Entra do usuário é usado para autenticar. Informações sobre como atribuir essa função podem ser encontradas em Segurança para soluções dos Gêmeos Digitais do Azure.

Para obter mais informações sobre como usar o plug-in, consulte a documentação do Kusto para o plug-in azure_digital_twins_query_request.

Para ver as consultas de exemplo e concluir uma explicação com dados de exemplo, consulte Plug-in de consulta de Gêmeos Digitais do Azure para Azure Data Explorer: exemplos de consultas e instruções no GitHub.

Ingestão de dados dos Gêmeos Digitais do Azure no Azure Data Explorer

Antes de consultar com o plug-in, você precisará fazer a ingestão dos dados dos Gêmeos Digitais do Azure no Azure Data Explorer. Há duas maneiras principais de fazer isso: por meio do recurso de histórico de dados ou pela ingestão direta. As seções a seguir descrevem essas opções mais detalhadamente.

Ingestão com o histórico de dados

A maneira mais simples de ingerir dados de IoT dos Gêmeos Digitais do Azure no Azure Data Explorer é usar o recurso de histórico de dados. Esse recurso permite configurar uma conexão entre sua instância de Gêmeos Digitais do Azure e um cluster do Azure Data Explorer, e as atualizações de gráfico (incluindo atualizações de propriedade gêmea, eventos de ciclo de vida gêmeo e eventos de ciclo de vida de relacionamento) são automaticamente historizadas para o cluster. Essa é uma boa opção se você estiver usando dados de telemetria de dispositivo para dar vida aos seus gêmeos digitais. Para obter mais informações sobre esse recurso, consulte Histórico de dados (com o Azure Data Explorer).

Ingestão direta

Você pode também optar por fazer a ingestão de dados de IoT diretamente no cluster do Azure Data Explorer a partir do Hub IoT ou de outras fontes. Em seguida, o grafo dos Gêmeos Digitais do Azure será usado para contextualizar os dados de série temporal usando consultas conjuntas dos Gêmeos Digitais do Azure/Azure Data Explorer. Essa opção é uma boa opção para cargas de trabalho de ingestão direta, no entanto, não será possível aproveitar a arquitetura baseada em eventos dos Gêmeos Digitais do Azure para atualizar os outros gêmeos, disparar os serviços downstream ou emitir as notificações quando os gêmeos alterarem de estado. Para obter mais informações sobre esse processo, continue no restante desta seção.

Mapeando dados entre o Azure Data Explorer e os Gêmeos Digitais do Azure

Se você estiver ingerindo dados de série temporal diretamente no Azure Data Explorer, você talvez precisará converter esses dados brutos de série temporal em um esquema adequado para consultas conjuntas dos Gêmeos Digitais do Azure/Azure Data Explorer.

Uma política de atualização no Azure Data Explorer permite que você transforme e acrescente dados automaticamente a uma tabela de destino sempre que novos dados são inseridos em uma tabela de origem.

Se a ID do sensor nos dados de telemetria do dispositivo for diferente da ID de gêmeo correspondente nos Gêmeos Digitais do Azure, você poderá usar uma política de atualização para enriquecer seus dados brutos de série temporal com a ID de gêmea e persisti-la em uma tabela de destino. Usando a ID de gêmeo, a tabela de destino pode ser unida aos gêmeos digitais selecionados pelo plug-in dos Gêmeos Digitais do Azure.

Por exemplo, digamos que você criou a tabela a seguir para manter o fluxo dos dados brutos de série temporal para sua instância do Azure Data Explorer.

.create-merge table rawData (Timestamp:datetime, someId:string, Value:string, ValueType:string)

Você pode criar uma tabela de mapeamento para relacionar as IDs de série temporal com IDs de gêmeos e outros campos opcionais.

.create-merge table mappingTable (someId:string, twinId:string, otherMetadata:string)

Em seguida, crie uma tabela de destino para manter os dados de série temporal aprimorados.

.create-merge table timeseriesSilver (twinId:string, Timestamp:datetime, someId:string, otherMetadata:string, ValueNumeric:real, ValueString:string)

Depois, crie uma função Update_rawData para enriquecer os dados brutos unindo-os à tabela de mapeamento. Fazer isso adicionará a ID de gêmeos à tabela de destino resultante.

.create-or-alter function with (folder = "Update", skipvalidation = "true") Update_rawData() { 
rawData 
| join kind=leftouter mappingTable on someId 
| project 
    Timestamp, ValueNumeric = toreal(Value), ValueString = Value, ... 
}

Por fim, crie uma política de atualização para chamar a função e atualizar a tabela de destino.

.alter table timeseriesSilver policy update 
@'[{"IsEnabled": true, "Source": "rawData", "Query": "Update_rawData()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

Depois que a tabela de destino for criada, você pode usar o plug-in dos Gêmeos Digitais do Azure para selecionar gêmeos de interesse e, em seguida, associá-los aos dados de série temporal na tabela de destino.

Esquema de exemplo

Aqui está um exemplo de um esquema que pode ser usado para representar dados compartilhados. O exemplo segue o esquema de histórico de dados do Azure Data Explorer para atualizações de propriedades gêmeas.

TimeStamp SourceTimeStamp TwinId ModelId Name Value RelationshipTarget RelationshipID
2021-02-01 17:24 2021-02-01 17:11 ConfRoomTempSensor dtmi:com:example:TemperatureSensor;1 temperatura 301.0

As propriedades de gêmeos digitais são armazenadas como pares chave-valor (name, value). name e value são armazenados como tipos de dados dinâmicos.

O esquema também dá suporte ao armazenamento de propriedades para relações, de acordo com os campos relationshipTarget e relationshipID. O esquema de chave-valor evita a necessidade de criar uma coluna para cada propriedade de gêmeo.

Representando propriedades com vários campos

Talvez você queira armazenar uma propriedade em seu esquema com vários campos. Essas propriedades são representadas por meio do armazenamento de um objeto JSON como value em seu esquema.

Por exemplo, se você quiser representar uma propriedade com três campos para rotação, inclinação e guinada, o objeto de valor será o seguinte: {"roll": 20, "pitch": 15, "yaw": 45}.

Próximas etapas