El historial de datos de Azure Digital Twins (con Azure Data Explorer)

El historial de datos es una característica de integración de Azure Digital Twins. Permite conectar una instancia de Azure Digital Twins a un clúster de Azure Data Explorer para que las actualizaciones de propiedades de gemelo digital se incorporen de forma histórica en Azure Data Explorer.

Una vez que los valores de las propiedades gemelas se incorporan de forma histórica en Azure Data Explorer, puede ejecutar consultas conjuntas mediante el complemento de Azure Digital Twins para Azure Data Explorer para sacar conclusiones sobre los gemelos digitales, sus relaciones y datos de serie temporal para obtener información sobre el comportamiento de los entornos modelados. También puede usar estas consultas para reforzar los paneles operativos, enriquecer las aplicaciones web 2D y 3D e impulsar unas experiencias envolventes de realidad aumentada y mixta para transmitir el estado actual e histórico de recursos, procesos y personas que se modelan en Azure Digital Twins.

Para obtener más información sobre el historial de datos, incluida una demostración rápida, vea el siguiente vídeo de presentación de IoT:

Recursos y flujo de datos

El historial de datos requiere los siguientes recursos:

Estos recursos están conectados al flujo siguiente:

Diagrama que muestra el flujo de datos de telemetría en Azure Digital Twins, a través de un centro de eventos, a Azure Data Explorer.

Los datos se mueven a través de estos recursos en este orden:

  1. Se actualiza una propiedad de un gemelo digital en Azure Digital Twins.
  2. El historial de datos reenvía un mensaje que contiene el valor de propiedad actualizado del gemelo y los metadatos al centro de eventos.
  3. El centro de eventos reenvía el mensaje al clúster de Azure Data Explorer de destino.
  4. El clúster de Azure Data Explorer asigna los campos de mensaje al esquema del historial de datos y almacena los datos como un registro con marca de tiempo en una tabla de historial de datos.

Cuando trabaje con el historial de datos, use la versión 31-05-2022 de las API.

Historial de varias instancias de Azure Digital Twins

Si quiere, puede tener varias instancias de Azure Digital Twins que registren las actualizaciones de las propiedades de los gemelos en el mismo clúster de Azure Data Explorer.

Cada instancia de Azure Digital Twins tendrá su propia conexión de historial de datos destinada al mismo clúster de Azure Data Explorer. Dentro del clúster, las instancias pueden enviar sus datos gemelos a...

  • tablas diferentes del clúster de Azure Data Explorer.
  • la misma tabla del clúster de Azure Data Explorer. Para ello, especifique el mismo nombre de tabla de Azure Data Explorer al crear las conexiones del historial de datos. En el esquema de la tabla de historial de datos, la columna ServiceId contendrá la dirección URL de la instancia de Azure Digital Twins de origen, por lo que puede usar este campo para resolver qué instancia de Azure Digital Twins emitió cada registro.

Creación de una conexión de historial de datos

Una vez configurados todos los recursos y permisos, puede usar la CLI de Azure, Azure Portal o el SDK de Azure Digital Twins para crear la conexión del historial de datos entre ellos. El conjunto de comandos de la CLI es az dt data-history.

Para obtener instrucciones detalladas sobre cómo configurar una conexión de historial de datos, vea Uso del historial de datos con Azure Data Explorer.

Permisos necesarios

Para configurar una conexión de historial de datos, la instancia de Azure Digital Twins debe tener los siguientes permisos para acceder a los recursos de Event Hubs y Azure Data Explorer. Estos roles permiten a Azure Digital Twins configurar el centro de eventos y la base de datos de Azure Data Explorer en su nombre (por ejemplo, crear una tabla en la base de datos). Opcionalmente, estos permisos se pueden eliminar después de configurar el historial de datos.

  • Recurso de Event Hubs: Propietario de los datos de Azure Event Hubs
  • Clúster de Azure Data Explorer: Colaborador (ámbito de todo el clúster o una base de datos específica)
  • Asignación de entidad de seguridad de base de datos de Azure Data Explorer: Administrador (ámbito de la base de datos que se usa)

Posteriormente, la instancia de Azure Digital Twins debe tener el siguiente permiso en el recurso de Event Hubs mientras se usa el historial de datos: Emisor de datos de Azure Event Hubs (también puede optar por mantener Propietario de los datos de Azure Event Hubs en la configuración del historial de datos).

Estos permisos se pueden asignar mediante la CLI de Azure o Azure Portal.

Esquema de datos

Los datos de serie temporal para las actualizaciones de propiedades gemelas se almacenan en Azure Data Explorer con el esquema siguiente:

Atributo Tipo Descripción
TimeStamp DateTime Fecha y hora en que Azure Digital Twins procesó el mensaje de actualización de la propiedad. El sistema establece este campo y los usuarios no pueden escribir en este campo.
SourceTimeStamp DateTime Propiedad opcional que se puede escribir que representa la marca de tiempo cuando se observó la actualización de la propiedad en un entorno real. Esta propiedad solo se puede escribir con la versión 31-05-2022 de los SDK o las API de Azure Digital Twins, y el valor debe cumplir el formato de fecha y hora de la normativa ISO 8601. Para obtener más información sobre cómo actualizar esta propiedad, vea Actualizar el valor sourceTime de una propiedad.
ServiceId String Identificador de instancia de servicio del servicio de Azure IoT que guarda el registro
Id String Identificador del gemelo
ModelId String Identificador de modelo DTDL (DTMI)
Key String Nombre de la propiedad actualizada
Value Dinámico Valor de la propiedad actualizada
RelationshipId String Cuando se actualiza una propiedad definida en una relación (en lugar de gemelos o dispositivos), este campo se rellena con el identificador de la relación. Cuando se actualiza una propiedad de gemelo, este campo está vacío.
RelationshipTarget String Cuando se actualiza una propiedad definida en una relación (en lugar de gemelos o dispositivos), este campo se rellena con el identificador de gemelo del gemelo de destino de la relación. Cuando se actualiza una propiedad de gemelo, este campo está vacío.

A continuación se muestra una tabla de ejemplo de actualizaciones de propiedades gemelas almacenadas en Azure Data Explorer.

TimeStamp SourceTimeStamp ServiceId Id ModelId Key Value RelationshipTarget RelationshipID
2021-06-30T20:23:29.8697482Z 2021-06-30T20:22:14.3854859Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Resultados 130
2021-06-30T20:23:39.3235925Z 2021-06-30T20:22:26.5837559Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Resultados 140
2021-06-30T20:23:47.078367Z 2021-06-30T20:22:34.9375957Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Resultados 130
2021-06-30T20:23:57.3794198Z 2021-06-30T20:22:50.1028562Z myInstance.api.neu.digitaltwins.azure.net solar_plant_3 dtmi:example:grid:plants:solarPlant;1 Resultados 123

Representación de propiedades con varios campos

Deberá almacenar una propiedad con varios campos. Estas propiedades se representan con un objeto JSON en el atributo Value del esquema.

Por ejemplo, si representa una propiedad con tres campos para los valores relativos a "roll" (alabeo), "pitch" (cabeceo) y"yaw" (guiñada), el historial de datos almacenará el siguiente objeto JSON como Value: {"roll": 20, "pitch": 15, "yaw": 45}.

Precios

Los mensajes emitidos por el historial de datos se miden en la dimensión de precios de los mensajes.

Latencia de ingesta completa

El historial de datos de Azure Digital Twins se basa en el mecanismo de ingesta existente proporcionado por Azure Data Explorer. Azure Digital Twins garantizará que las actualizaciones de propiedades estén disponibles para Azure Data Explorer en menos de dos segundos. Azure puede introducir latencia adicional para la ingesta de datos de Data Explorer.

Hay dos métodos en Azure Data Explorer para la ingesta de datos: la ingesta por lotes y la ingesta de streaming. Puede configurar estos métodos de ingesta para tablas individuales según sus necesidades y el escenario de ingesta de datos específico.

La ingesta de streaming tiene la latencia más baja. Sin embargo, debido a la sobrecarga de procesamiento, este modo solo se debe usar si se ingieren menos de 4 GB de datos cada hora. La ingesta por lotes funciona mejor si se esperan altas tasas de datos de ingesta. Azure Data Explorer utiliza la ingesta por lotes de forma predeterminada. En la tabla siguiente se resume la latencia completa para el peor escenario previsto:

Configuración de Data Explorer Azure Latencia completa prevista Velocidad de datos recomendada
Ingesta de streaming <12 s (<3 s típico) <4 GB/h
Ingesta por lotes Varía (de 12 s a 15 min, según la configuración) >4 GB/h

El resto de esta sección contiene detalles para habilitar cada tipo de ingesta.

Ingesta por lotes (valor predeterminado)

Si no se configura de otro modo, Azure Data Explorer utilizará la ingesta por lotes. La configuración predeterminada puede suponer que los datos estén disponibles para la consulta solo entre 5 y 10 minutos tras realizarse una actualización de un gemelo digital. La directiva de ingesta se puede modificar, de modo que el procesamiento por lotes se produzca como máximo cada 10 segundos (como mínimo, o 15 minutos como máximo). Para modificar la directiva de ingesta, se debe emitir el siguiente comando en la vista de consulta de Azure Data Explorer:

.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}' 

Asegúrese de que <table_name> se reemplaza por el nombre de la tabla que se ha configurado. MaximumBatchingTimeSpan debe establecerse en el intervalo de procesamiento por lotes preferido. La directiva puede tardar entre 5 y 10 minutos en entrar en vigor. Puede obtener más información sobre la ingesta por lotes en el siguiente vínculo: Comando de administración de directivas IngestionBatching de Kusto.

Ingesta de streaming

La habilitación de la ingesta de streaming es un proceso de dos pasos:

  1. Habilitar la ingesta de streaming para su clúster. Esta acción solo debe llevarse a cabo un vez. (Advertencia: su ejecución tendrá un efecto en la cantidad de almacenamiento disponible para la caché en caliente y puede suponer limitaciones adicionales). Para obtener instrucciones, consulte Configuración de la ingesta de streaming en el clúster de Azure Data Explorer.
  2. Agregue una directiva de ingesta de streaming para la tabla deseada. Puede obtener más información sobre cómo habilitar la ingesta de streaming para el clúster en la documentación de Azure Data Explorer: Comando de administración de directivas IngestionBatching de Kusto.

Para habilitar la ingesta de streaming para el historial de datos de Azure Digital Twins, se debe emitir el siguiente comando en el panel de consulta de Data Explorer:

.alter table <table_name> policy streamingingestion enable 

Asegúrese de que <table_name> se reemplaza por el nombre de la tabla que se ha configurado. La directiva puede tardar entre 5 y 10 minutos en entrar en vigor.

Pasos siguientes

Una vez que los datos gemelos se han pasado a Azure Data Explorer, puede usar el complemento de consulta de Azure Digital Twins para Azure Data Explorer para ejecutar consultas en los datos. Obtenga más información sobre el complemento aquí: Consulta con el complemento de Data Explorer Azure.

O bien, profundice en el historial de datos con un escenario de ejemplo en este procedimiento: Uso del historial de datos con Azure Data Explorer.