Partilhar via

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

Este artigo é sobre o plug-in de consulta do Azure Digital Twins para o Azure Data Explorer.

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.

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 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 no Azure Digital Twins, poderá usar uma política de atualização para enriquecer os seus dados brutos de séries temporais com a ID de gémeo e armazená-los numa tabela de destino. Usando a ID de gémeos, a tabela de destino pode ser ligada aos gémeos digitais selecionados pelo plugin 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, nos relationshipTarget e relationshipID campos. 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 pretenderes representar uma propriedade com três campos para rotação, inclinação e guinada, o objeto de valor terá esta aparência: {"roll": 20, "pitch": 15, "yaw": 45}.

Usando o plugin

Depois que seus dados do Azure Digital Twins estiverem no Azure Data Explorer, você poderá usar o plug-in para consultá-los.

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

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

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 de Gêmeos Digitais do Azure.

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

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

    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 plugin podem não começar com um $. O uso de pseudónimos na cláusula SELECT 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

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.

Próximos passos

  • Last updated on