Complemento de consulta de Azure Digital Twins para Azure Data Explorer

  • Artículo

En este artículo se explica el complemento de consulta de Azure Digital Twins para Azure Data Explorer, cómo usar datos de IoT de Azure Data Explorer con Azure Digital Twins y cómo asignar datos entre Azure Data Explorer y Azure Digital Twins, entre otras cosas.

El complemento de Azure Digital Twins para Azure Data Explorer permite ejecutar consultas de Azure Data Explorer que acceden a datos en grafos de Azure Digital Twins y bases de datos de series temporales de Azure Data Explorer y los combinan. Use el complemento para contextualizar datos de series temporales dispares mediante el razonamiento entre los gemelos digitales y sus relaciones para obtener información sobre el comportamiento de los entornos modelados.

Por ejemplo, con este complemento, puede escribir una consulta de Kusto que:

  1. seleccione gemelos digitales de interés mediante el complemento de consulta de Azure Digital Twins,
  2. combine esos gemelos con la serie temporal correspondiente de Azure Data Explorer y, luego,
  3. realice análisis avanzados de series temporales en esos gemelos.

La combinación de los datos de un grafo de un gemelo de Azure Digital Twins con datos de series temporales de Azure Data Explorer puede ayudarle a comprender el comportamiento operativo de varios componentes de la solución.

Uso del complemento

Puede invocar el complemento en una consulta de Kusto con el siguiente comando. Hay dos marcadores de posición, <Azure-Digital-Twins-endpoint> y <Azure-Digital-Twins-query>, que son cadenas que representan el punto de conexión de la instancia de Azure Digital Twins y la consulta de Azure Digital Twins, respectivamente.

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

El complemento funciona mediante una llamada a la API de consulta de Azure Digital Twins y la estructura del lenguaje de consulta es la misma que al usar la API, con dos excepciones:

  • No se admite el carácter comodín * en la cláusula SELECT. En su lugar, las consultas de Azure Digital Twins que se ejecutan mediante el complemento deben usar alias en la cláusula SELECT.

    Por ejemplo, considere la siguiente consulta de Azure Digital Twins que se ejecuta mediante la API:

    SELECT * FROM DIGITALTWINS

    Para ejecutar esa consulta cuando se usa el complemento, debe reescribirse de esta forma:

    SELECT T FROM DIGITALTWINS T

  • Los nombres de columna devueltos por el complemento no pueden empezar por $. El uso de alias en la cláusula SELECT también ayudará a evitar este escenario.

    Por ejemplo, considere la siguiente consulta de Azure Digital Twins que se ejecuta mediante la API:

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

    Para ejecutar esa consulta cuando se usa el complemento, debe reescribirse de esta forma:

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

Importante

Al usuario del complemento se le debe conceder el rol Lector de datos de Azure Digital Twins o el rol Propietario de datos de Azure Digital Twins, ya que el token de Microsoft Entra del usuario se usa para autenticarse. Encontrará información sobre cómo asignar este rol en Seguridad para las soluciones de Azure Digital Twins.

Para más información sobre el uso del complemento, consulte la documentación de Kusto para el complemento azure_digital_twins_query_request.

Para ver consultas de ejemplo y completar un tutorial con datos de ejemplo, consulte Complemento de consulta de Azure Digital Twins para Azure Data Explorer: Consultas y tutorial de ejemplo en GitHub.

Ingesta de datos de Azure Digital Twins en Azure Data Explorer

Antes de realizar consultas con el complemento, deberá ingerir los datos de Azure Digital Twins en Azure Data Explorer. Existen dos maneras principales de hacerlo: a través de la característica del historial de datos o a través de la ingesta directa. En las secciones siguientes, se describen estas opciones con más detalle.

Ingesta con historial de datos

La manera más sencilla de ingerir datos de IoT de Azure Digital Twins a Azure Data Explorer consiste en usar la característica historial de datos. Esta característica permite configurar una conexión entre la instancia de Azure Digital Twins y un clúster de Azure Data Explorer, y las actualizaciones de grafos (incluidas las actualizaciones de propiedades gemelas, los eventos del ciclo de vida del gemelo y los eventos del ciclo de vida de las relaciones) se historizan automáticamente al clúster. Esta es una buena opción si usa datos de telemetría de dispositivos para que los gemelos digitales se vuelvan a la vida. Para obtener más información sobre esta característica, consulte Historial de datos (con Azure Data Explorer).

Ingesta directa

También puede optar por ingerir los datos de IoT directamente en el clúster de Azure Data Explorer desde IoT Hub o desde otros orígenes. Posteriormente, se usará el grafo de Azure Digital Twins para contextualizar los datos de la serie temporal mediante consultas conjuntas de Azure Digital Twins y Azure Data Explorer. Esta opción es una buena elección para cargas de trabajo de ingesta directa; sin embargo, no podrá sacar provecho de la arquitectura basada en eventos de Azure Digital Twins para actualizar otros gemelos, desencadenar servicios de bajada o emitir notificaciones cuando los gemelos cambien de estado. Para obtener más información sobre este proceso, continúe con el resto de esta sección.

Asignación de datos entre Azure Data Explorer y Azure Digital Twins

Si va a ingerir datos de serie temporal directamente en Azure Data Explorer, es posible que tenga que convertir estos datos de serie temporal sin procesar en un esquema adecuado para consultas conjuntas de Azure Digital Twins y Azure Data Explorer.

Una directiva de actualización en Azure Data Explorer permite transformar y anexar datos automáticamente a una tabla de destino cada vez que se inserten nuevos datos en una tabla de origen.

Si el identificador del sensor de los datos de telemetría del dispositivo difiere del identificador de gemelo correspondiente en Azure Digital Twins, puede usar una directiva de actualización para enriquecer los datos de serie temporal sin procesar con el identificador del gemelo y conservarlos en una tabla de destino. Con el identificador del gemelo, la tabla de destino se puede combinar con los gemelos digitales seleccionados por el complemento de Azure Digital Twins.

Por ejemplo, supongamos que ha creado la tabla siguiente para que contenga los datos de serie temporal sin procesar que se transfieren a la instancia de Azure Data Explorer.

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

Puede crear una tabla de asignación para relacionar los identificadores de series temporales con los identificadores de los gemelos y otros campos opcionales.

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

A continuación, cree una tabla de destino que contenga los datos de series temporales enriquecidos.

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

A continuación, cree una función Update_rawData para enriquecer los datos sin procesar combinándolos con la tabla de asignación. Esto agregará el identificador del gemelo a la tabla 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 último, cree una directiva de actualización para llamar a la función y actualizar la tabla de destino.

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

Una vez creada la tabla de destino, puede usar el complemento de Azure Digital Twins para seleccionar los gemelos de interés y, a continuación, combinarlos con los datos de series temporales de la tabla de destino.

Esquema de ejemplo

Este es un ejemplo de un esquema que podría usarse para representar datos compartidos. En el ejemplo se sigue el esquema del historial de datos de Azure Data Explorer para las actualizaciones de propiedades gemelas.

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

Las propiedades de los gemelos digitales se almacenan como pares clave-valor (name, value). name y value se almacenan como tipos de datos dinámicos.

El esquema también admite el almacenamiento de propiedades de las relaciones, según los campos relationshipTarget y relationshipID. El esquema clave-valor evita la necesidad de crear una columna para cada propiedad del gemelo.

Representación de propiedades con varios campos

Es posible que quiera almacenar una propiedad en el esquema con varios campos. Estas propiedades se representan mediante el almacenamiento de un objeto JSON como value en el esquema.

Por ejemplo, si desea representar una propiedad con tres campos para roll, pitch y yaw, el objeto de valor tendría este aspecto: {"roll": 20, "pitch": 15, "yaw": 45}.

Pasos siguientes