Plug-in de consulta do Azure Digital Twins para o Azure Data Explorer

  • Artigo

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

O plug-in Gêmeos Digitais do Azure para o Azure Data Explorer permite executar consultas do Azure Data Explorer que acessam e combinam dados no gráfico dos Gêmeos Digitais do Azure e nos bancos de dados de séries cronológicas do Azure Data Explorer . Use o plug-in para contextualizar dados de séries temporais díspares, raciocinando entre gêmeos digitais e seus relacionamentos para obter insights sobre o comportamento de ambientes modelados.

Por exemplo, com este plugin, você pode escrever uma consulta Kusto que:

  1. Seleciona gêmeos digitais de interesse por meio do plug-in de consulta Gêmeos Digitais do Azure,
  2. Junta esses gêmeos às respetivas séries temporais no Azure Data Explorer e, em seguida,
  3. Executa análises avançadas de séries temporais nesses gêmeos.

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

Usando o plugin

Você pode invocar o plug-in em uma consulta Kusto com o seguinte comando. Há dois espaços reservados <Azure-Digital-Twins-endpoint> e , que são cadeias de caracteres que representam o ponto de extremidade da instância dos Gêmeos Digitais do Azure e <Azure-Digital-Twins-query>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 que ao usar a API, com duas exceções:

  • O * curinga na SELECT cláusula não é suportado. Em vez disso, as consultas do Gêmeo Digital do Azure que são executadas usando o plug-in devem usar aliases na SELECT cláusula.

    Por exemplo, considere a consulta Azure Digital Twins abaixo que é executada usando a API:

    SELECT * FROM DIGITALTWINS

    Para executar essa consulta ao usar o plugin, ela deve ser reescrita assim:

    SELECT T FROM DIGITALTWINS T

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

    Por exemplo, considere a consulta Azure Digital Twins abaixo que é executada usando a API:

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

    Para executar essa consulta ao usar o plugin, ela deve ser reescrita assim:

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

Importante

O usuário do plug-in deve receber a função Leitor de Dados do Azure Digital Twins ou a função Proprietário de Dados do Azure Digital Twins, 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 de 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 consultas de exemplo e concluir um passo a passo com dados de exemplo, consulte Plug-in de consulta do Azure Digital Twins para o Azure Data Explorer: consultas de exemplo e passo a passo no GitHub.

Ingerir dados do Azure Digital Twins no Azure Data Explorer

Antes de consultar com o plug-in, você precisará ingerir seus dados do Azure Digital Twins no Azure Data Explorer. Existem duas formas principais de o fazer: através da funcionalidade de histórico de dados ou através da ingestão direta. As secções seguintes descrevem estas opções mais detalhadamente.

Ingerir com 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 que você configure uma conexão entre sua instância do Azure Digital Twins e um cluster do Azure Data Explorer, e as atualizações de gráficos (incluindo atualizações de propriedade gêmea, eventos de ciclo de vida gêmeos e eventos de ciclo de vida de relacionamento) são automaticamente historizadas no cluster. Esta é uma boa escolha se você estiver usando dados de telemetria do 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ê também pode optar por ingerir dados da IoT diretamente em seu cluster do Azure Data Explorer a partir do Hub IoT ou de outras fontes. Em seguida, o gráfico de Gêmeos Digitais do Azure será usado para contextualizar os dados de séries temporais usando consultas conjuntas do Azure Digital Twins/Azure Data Explorer. Essa opção é uma boa opção para cargas de trabalho de ingestão direta — no entanto, você não poderá aproveitar a arquitetura baseada em eventos do Azure Digital Twins para atualizar outros gêmeos, acionar serviços downstream ou emitir notificações quando os gêmeos mudarem de estado. Para obter mais informações sobre esse processo, continue pelo restante desta seção.

Mapeando dados no Azure Data Explorer e nos Gêmeos Digitais do Azure

Se você estiver ingerindo dados de séries temporais diretamente no Azure Data Explorer, talvez seja necessário converter esses dados brutos de séries temporais em um esquema adequado para consultas conjuntas do Azure Digital Twins/Azure Data Explorer.

Uma política de atualização no Azure Data Explorer permite transformar e acrescentar 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éries temporais com a ID de gêmeos e mantê-los em uma tabela de destino. Usando a ID de gêmeos, a tabela de destino pode ser unida aos gêmeos digitais selecionados pelo plug-in Gêmeos Digitais do Azure.

Por exemplo, digamos que você criou a tabela a seguir para armazenar os dados brutos da série temporal fluindo 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 IDs de séries temporais com IDs gêmeos e outros campos opcionais.

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

Em seguida, crie uma tabela de destino para armazenar os dados de séries cronológicas enriquecidos.

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

Em seguida, crie uma função Update_rawData para enriquecer os dados brutos unindo-os à tabela de mapeamento. Isso adicionará o ID gêmeo à 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ê poderá usar o plug-in Gêmeos Digitais do Azure para selecionar gêmeos de interesse e, em seguida, juntá-los aos dados de séries temporais 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 do histórico de dados do Azure Data Explorer para atualizações de propriedade 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 suporta o armazenamento de propriedades para relacionamentos, de acordo com os relationshipTarget campos e relationshipID . O esquema chave-valor evita a necessidade de criar uma coluna para cada propriedade gêmea.

Representando propriedades com vários campos

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

Por exemplo, se você quiser representar uma propriedade com três campos para rolar, inclinar e bocejar, o objeto value terá esta aparência: {"roll": 20, "pitch": 15, "yaw": 45}.

Próximos passos