Exportación de datos de IoT a Azure Data Explorer

En este artículo se describe cómo configurar la exportación de datos para enviar datos a Azure Data Explorer.

Utilice esta característica para exportar continuamente los datos de IoT filtrados y enriquecidos desde su aplicación de IoT Central. La exportación de datos inserta los cambios casi en tiempo real en otras partes de la solución en la nube para su análisis y almacenamiento, y conocer los detalles de la ruta de acceso activa.

Por ejemplo, puede:

  • Exportar continuamente la telemetría, los cambios de propiedad, la conectividad del dispositivo, el ciclo de vida del dispositivo, el ciclo de vida de la plantilla de dispositivo y los datos del registro de auditoría en formato JSON casi en tiempo real.
  • Filtrar los flujos de datos para exportar los datos que coincidan con condiciones personalizadas.
  • Enriquecer los flujos de datos con valores personalizados y valores de propiedad del dispositivo.
  • Transforme los flujos de datos para modificar su forma y contenido.

Sugerencia

Cuando se activa la exportación de datos, solo se obtienen los datos a partir de ese momento. Para conservar más datos históricos, active la exportación de datos al principio. Para exportar manualmente datos de momentos en los que estaba desactivada la exportación de datos, consulte Empleo de la API de REST de IoT Central para consultar dispositivos.

Nota:

En algunas circunstancias, los mensajes pueden tardar hasta 60 segundos en exportarse. Este tiempo se mide desde cuando IoT Central recibe el mensaje del centro de IoT subyacente a cuando el mensaje se entrega al punto de conexión de destino.

Requisitos previos

Para usar las funciones de exportación de datos, debe tener el permiso de exportación de datos.

Configuración de un destino de exportación de Azure Data Explorer

Puede usar un clúster de Azure Data Explorer o un grupo de Azure Synapse Data Explorer. Para más información, consulte ¿Cuál es la diferencia entre Azure Data Explorer y Azure Synapse Data Explorer?

IoT Central exporta los datos casi en tiempo real a una tabla de base de datos del clúster de Azure Data Explorer. Los datos están en el cuerpo del mensaje y están en formato JSON codificados como UTF-8. Puede agregar una transformación en IoT Central para exportar los datos que coincidan con el esquema de la tabla.

Para consultar los datos exportados en el portal de Azure Data Explorer, vaya a la base de datos y seleccione Query (Consulta).

El siguiente vídeo muestra cómo exportar datos a Azure Data Explorer:

Opciones de conexión

Los destinos de Azure Data Explorer le permiten configurar la conexión con una entidad de servicio o una identidad administrada.

Las identidades administradas son más seguras porque:

  • No se almacenan las credenciales del recurso en una cadena de conexión en la aplicación IoT Central.
  • Las credenciales se vinculan automáticamente a la vigencia de la aplicación IoT Central.
  • Las identidades administradas rotan automáticamente sus claves de seguridad periódicamente.

Actualmente, IoT Central usa identidades administradas asignadas por el sistema.

Al configurar una identidad administrada, la configuración incluye un ámbito y un rol:

  • El ámbito define dónde puede usar la identidad administrada. Por ejemplo, puede usar un grupo de recursos de Azure como ámbito. En este caso, tanto la aplicación de IoT Central como el destino deben estar en el mismo grupo de recursos.
  • El rol define qué permisos se conceden a la aplicación de IoT Central en el servicio de destino. Por ejemplo, para que la aplicación de IoT Central envíe datos a un centro de eventos, la identidad administrada necesita la asignación de rol emisor de datos de Azure Event Hubs.

El siguiente vídeo proporciona información adicional sobre la identidad administrada asignada por el sistema:

Precaución

Para exportar a Blob Storage, no use el colaborador de la cuenta de almacenamiento como se muestra en el vídeo. Use el rol Colaborador de datos de Storage Blob en su lugar.

Creación de un destino de Azure Data Explorer

En este artículo se muestra cómo crear una identidad administrada con la CLI de Azure. También puede usar Azure Portal para crear una identidad administrada.

Si no tiene una base de datos de Azure Data Explorer a la que realizar la exportación, siga estos pasos: Tiene dos opciones para crear una base de datos de Azure Data Explorer:

Para configurar la identidad administrada que permite a la aplicación IoT Central exportar datos de forma segura al recurso de Azure:

  1. Cree una identidad administrada para la aplicación de IoT Central que se usará para conectarse a la base de datos. Utilice Azure Cloud Shell para ejecutar el comando siguiente:

    az iot central app identity assign --name {your IoT Central app name} \
        --resource-group {resource group name} \
        --system-assigned
    

    Anote la salida principalId y tenantId del comando. Estos valores se usan en el paso siguiente.

  2. Configure los permisos de base de datos para permitir conexiones desde la aplicación de IoT Central. Utilice Azure Cloud Shell para ejecutar el comando siguiente:

    az kusto database-principal-assignment create --cluster-name {name of your cluster} \
        --database-name {name of your database}    \
        --resource-group {resource group name} \
        --principal-assignment-name {name of your IoT Central application} \
        --principal-id {principal id from the previous step} \
        --principal-type App --role Admin \
        --tenant-id {tenant id from the previous step}
    

    Sugerencia

    Si usa Azure Synapse, consulte az synapse kusto database-principal-assignment.

  3. Cree una tabla en la base de datos con un esquema adecuado para los datos que va a exportar. En la consulta de ejemplo siguiente, se crea una tabla llamada smartvitalspatch. Para más información, consulte Transformación de datos dentro de la aplicación de IoT Central para su exportación:

    .create table smartvitalspatch (
      EnqueuedTime:datetime,
      Message:string,
      Application:string,
      Device:string,
      Simulated:boolean,
      Template:string,
      Module:string,
      Component:string,
      Capability:string,
      Value:dynamic
    )
    
  4. (Opcional) Para acelerar la ingesta de datos en la base de datos de Azure Data Explorer:

    1. Vaya a la página Configurations (Configuraciones) del clúster de Azure Data Explorer. A continuación, habilite la opción Streaming ingestion (Ingesta de streaming).

    2. Ejecute la consulta siguiente para modificar la directiva de la tabla para habilitar la ingesta de streaming:

      .alter table smartvitalspatch policy streamingingestion enable
      

Para crear el destino de Azure Data Explorer en IoT Central en la página Exportación de datos:

  1. Seleccione + Nuevo destino.

  2. Seleccione Azure Data Explorer como tipo de destino.

  3. Especifique la dirección URL del grupo o clúster, el nombre de la base de datos y el nombre de la tabla de Azure Data Explorer. Seleccione Identidad administrada asignada por el sistema como tipo de autorización.

    Sugerencia

    La dirección URL de un clúster independiente de Azure Data Explorer es similar a https://<ClusterName>.<AzureRegion>.kusto.windows.net. La dirección URL de un grupo de Azure Synapse Data Explorer es similar a https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net.

    Captura de pantalla del destino de exportación de Azure Data Explorer que usa una identidad administrada.

Si no ve los datos que llegan al servicio de destino, consulte Solución de problemas con las exportaciones de datos desde la aplicación de Azure IoT Central.

Configuración de una exportación de datos

Ahora que tiene un destino al que exportar los datos, configure la exportación de datos en su aplicación de IoT Central:

  1. Inicie sesión en su aplicación de IoT Central.

  2. En el panel izquierdo, seleccione Exportación de datos.

    Sugerencia

    Si no ve Exportación de datos en el panel izquierdo, no tiene permisos para configurar la exportación de datos en la aplicación. Hable con un administrador para configurar la exportación de datos.

  3. Seleccione + New export (+ Nueva exportación).

  4. Escriba un nombre para mostrar para la nueva exportación y asegúrese de que la exportación de datos está habilitada.

  5. Elija el tipo de datos para exportar. En la tabla siguiente se enumeran los tipos de exportación de datos compatibles:

    Tipo de datos Descripción Formato de datos
    Telemetría Exporte los mensajes de telemetría de los dispositivos casi en tiempo real. Cada mensaje exportado contiene todo el contenido del mensaje del dispositivo original, normalizado. Formato del mensaje de telemetría
    Cambios de la propiedad Exporte los cambios de las propiedades de dispositivos y la nube casi en tiempo real. En el caso de las propiedades de dispositivo de solo lectura, se exportan los cambios realizados en los valores notificados. En el caso de las propiedades de lectura y escritura, se exportan los valores notificados y deseados. Formato de los mensajes de cambio de propiedad
    Conectividad de dispositivos Exporte eventos de dispositivos conectados y desconectados. Formato de mensaje de conectividad del dispositivo
    Ciclo de vida del dispositivo Exporte los eventos registrados, eliminados, aprovisionados, habilitados, deshabilitados, displayNameChanged y deviceTemplateChanged. Formato de los mensajes de cambios del ciclo de vida de dispositivo
    Ciclo de vida de plantillas de dispositivo Exporte los cambios de plantilla de dispositivo publicados, incluidos los creados, actualizados y eliminados. Formato de los mensajes de cambios del ciclo de vida de plantilla de dispositivo
    Registros de auditoría Registros de actualizaciones iniciadas por el usuario en las entidades de la aplicación. Para obtener más información, vea Uso de registros de auditoría para realizar un seguimiento de la actividad en la aplicación de IoT Central. Formato de los mensajes del registro de auditoría
  6. Opcionalmente, agregue filtros para reducir la cantidad de datos exportados. Hay diferentes tipos de filtros disponibles para cada tipo de exportación de datos:

    Tipo de datos Filtros disponibles
    Telemetría
    • Filtrar por nombre de dispositivo, id. de dispositivo, plantilla de dispositivo y si el dispositivo está simulado
    • Filtrar el flujo para que solo contenga la telemetría que cumpla las condiciones de filtro
    • Filtrar el flujo para que solo contenga la telemetría de dispositivos con propiedades que coincidan con las condiciones de filtro
    • Filtrar el flujo para que solo contenga la telemetría que tenga propiedades de mensaje que cumplan la condición de filtro. Las propiedades del mensaje (también conocidas como propiedades de la aplicación) se envían en un contenedor de pares clave-valor en cada mensaje de telemetría. Para crear un filtro de propiedad de mensaje, escriba la clave de la propiedad de mensaje que busca y especifique una condición. Solo se exportarán los mensajes de telemetría con propiedades que coincidan con la condición de filtro especificada. Obtenga más información sobre las propiedades de aplicaciones en la documentación de IoT Hub.
    Cambios de la propiedad
    • Filtrar por nombre de dispositivo, id. de dispositivo, plantilla de dispositivo y si el dispositivo está simulado
    • Filtrar el flujo para que contenga solo los cambios de propiedad que cumplan las condiciones de filtro
    Conectividad de dispositivos
    • Filtrar por nombre de dispositivo, identificador de dispositivo, plantilla de dispositivo y si el dispositivo es simulado
    • Filtrar el flujo para que solo contenga los cambios de dispositivos con propiedades que coincidan con las condiciones de filtro
    Ciclo de vida del dispositivo
    • Filtrar por nombre de dispositivo, id. de dispositivo, plantilla de dispositivo y si el dispositivo está aprovisionado, habilitado o simulado
    • Filtrar el flujo para que solo contenga los cambios de dispositivos con propiedades que coincidan con las condiciones de filtro
    Ciclo de vida de plantillas de dispositivo
    • Filtrar por plantilla de dispositivo
    Registros de auditoría N/D
  7. Opcionalmente, puede enriquecer los mensajes exportados con metadatos adicionales de pares clave-valor. Están disponibles los enriquecimientos siguientes para los tipos de exportación de datos de telemetría, cambios de propiedad, conectividad de dispositivo y ciclo de vida de dispositivo:

    • Cadena personalizada: agrega una cadena estática personalizada a cada mensaje. Escriba cualquier clave y especifique cualquier valor de cadena.
    • Propiedad, que agrega a cada mensaje:
      • Metadatos del dispositivo, como el nombre del dispositivo, el nombre de la plantilla de dispositivo, si está habilitado, las organizaciones, si está aprovisionado y si es simulado.
      • La propiedad notificada de dispositivo actual o el valor de propiedad de la nube a cada mensaje. Si el mensaje exportado procede de un dispositivo que no tiene la propiedad especificada, no obtendrá el enriquecimiento.

Configure el destino de la exportación:

  1. Seleccione + Destino para agregar un destino que ya haya creado, o seleccione Crear uno nuevo.

  2. Para transformar los datos antes de exportarlos, seleccione + Transformar. Para más información, consulte Transformación de datos dentro de la aplicación de IoT Central para su exportación.

  3. Seleccione + Destino para agregar hasta cinco destinos a una única exportación.

  4. Cuando haya terminado de configurar la exportación, seleccione Guardar. Transcurridos unos minutos, los datos aparecen en sus destinos.

Supervisión de la exportación

En IoT Central, la página Exportación de datos permite comprobar el estado de las exportaciones. También puede usar Azure Monitor para ver cuántos datos está exportando y los errores de exportación. Puede acceder a las métricas de exportación y estado del dispositivo en los gráficos de Azure Portal mediante la API REST, consultas en PowerShell o la CLI de Azure. Actualmente, puede supervisar las siguientes métricas de exportación de datos en Azure Monitor:

  • Número de mensajes entrantes para exportar antes de que se apliquen los filtros
  • Número de mensajes que pasan a través de filtros
  • Número de mensajes exportados correctamente a destinos
  • Número de errores encontrados.

Para más información, consulte Supervisión del estado de la aplicación.

Formatos de datos

En las secciones siguientes se describen los formatos de los datos exportados:

Formato de los datos de telemetría

Cada mensaje exportado contiene un formato normalizado del mensaje completo que el dispositivo envió en el cuerpo del mensaje. El mensaje está en formato JSON y codificado como UTF-8. La información de los mensajes incluye:

  • applicationId: identificador de la aplicación de IoT Central.
  • messageSource: origen del mensaje: telemetry.
  • deviceId: el identificador del dispositivo que envió el mensaje de telemetría.
  • schema: el nombre y la versión del esquema de carga.
  • templateId: id. de la plantilla de dispositivo asignada a este dispositivo
  • enqueuedTime: hora a la que IoT Central recibió este mensaje.
  • enrichments: cualquier enriquecimiento configurado en la exportación.
  • module: el módulo IoT Edge que envió este mensaje. Este campo solo aparece si el mensaje provino de un módulo IoT Edge.
  • component: el componente que envió este mensaje. Este campo solo aparece si las funcionalidades enviadas en el mensaje se modelaron como un componente en la plantilla de dispositivo.
  • messageProperties: más propiedades que el dispositivo envió con el mensaje. A veces, estas propiedades se denominan propiedades de la aplicación. Puede encontrar más información en la documentación de IoT Hub.

Propiedades del mensaje

Los mensajes de telemetría tienen propiedades para los metadatos, así como para la carga de telemetría. El fragmento de código anterior muestra ejemplos de mensajes del sistema, como deviceId y enqueuedTime. Para obtener más información sobre las propiedades del mensaje del sistema, consulte Propiedades del sistema de los mensajes de IoT Hub D2C.

Puede agregar propiedades a los mensajes de telemetría si necesita agregar metadatos personalizados a los mensajes de telemetría. Por ejemplo, tiene que agregar una marca de tiempo cuando el dispositivo crea el mensaje.

En el fragmento de código siguiente se muestra cómo agregar la propiedad iothub-creation-time-utc al mensaje cuando se crea en el dispositivo:

Importante

El formato de esta marca de tiempo debe ser UTC sin información de zona horaria. Por ejemplo, 2021-04-21T11:30:16Z es válido y 2021-04-21T11:30:16-07:00 no lo es.

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Formato de cambios de propiedades

Cada mensaje o registro representa los cambios en las propiedades del dispositivo y de la nube. La información del mensaje exportado incluye:

  • applicationId: identificador de la aplicación de IoT Central.
  • messageSource: origen del mensaje: properties.
  • messageType: cloudPropertyChange, devicePropertyDesiredChange o devicePropertyReportedChange.
  • deviceId: el identificador del dispositivo que envió el mensaje de telemetría.
  • schema: el nombre y la versión del esquema de carga.
  • enqueuedTime: hora a la que IoT Central detectó este cambio.
  • templateId: id. de la plantilla de dispositivo asignada a este dispositivo
  • properties: una matriz de propiedades que han cambiado que incluye los nombres de las propiedades y los valores que han cambiado. La información del componente y del módulo se incluye si la propiedad se modela dentro de un componente o un módulo de IoT Edge.
  • enrichments: cualquier enriquecimiento configurado en la exportación.

Formato de los cambios de conectividad de dispositivos

Cada mensaje o registro representa un evento de conectividad de un único dispositivo. La información del mensaje exportado incluye:

  • applicationId: identificador de la aplicación de IoT Central.
  • messageSource: origen del mensaje: deviceConnectivity.
  • messageType: connected o disconnected.
  • deviceId: el id. del dispositivo que se ha cambiado.
  • schema: el nombre y la versión del esquema de carga.
  • templateId: id. de la plantilla de dispositivo asignada a este dispositivo
  • enqueuedTime: la hora a la que se produjo este cambio en IoT Central.
  • enrichments: cualquier enriquecimiento configurado en la exportación.

Formato de los cambios de ciclo de vida de dispositivo

Cada mensaje o registro representa un cambio en un único dispositivo. La información del mensaje exportado incluye:

  • applicationId: identificador de la aplicación de IoT Central.
  • messageSource: origen del mensaje: deviceLifecycle.
  • messageType: tipo de error que se produjo. Uno de los siguientes: registered, deleted, provisioned, enabled, disabled, displayNameChanged y deviceTemplateChanged.
  • deviceId: el id. del dispositivo que se ha cambiado.
  • schema: el nombre y la versión del esquema de carga.
  • templateId: id. de la plantilla de dispositivo asignada a este dispositivo
  • enqueuedTime: la hora a la que se produjo este cambio en IoT Central.
  • enrichments: cualquier enriquecimiento configurado en la exportación.

Formato de los cambios del ciclo de vida de plantilla de dispositivo

Cada mensaje o registro representa un cambio en una única plantilla de dispositivo publicada. La información del mensaje exportado incluye:

  • applicationId: identificador de la aplicación de IoT Central.
  • messageSource: origen del mensaje: deviceTemplateLifecycle.
  • messageType: created, updated o deleted.
  • schema: el nombre y la versión del esquema de carga.
  • templateId: id. de la plantilla de dispositivo asignada a este dispositivo
  • enqueuedTime: la hora a la que se produjo este cambio en IoT Central.
  • enrichments: cualquier enriquecimiento configurado en la exportación.

Formato de los registros de auditoría

Cada mensaje del registro de auditoría representa un cambio iniciado por el usuario en una entidad auditable dentro de la aplicación de IoT Central. La información del mensaje exportado incluye:

  • actor: información sobre el usuario que ha modificado la entidad.
  • applicationId: identificador de la aplicación de IoT Central.
  • messageSource: origen del mensaje: audit.
  • messageType: tipo de error que se produjo. Uno de estos valores: updated, created o deleted.
  • updated: solo está presente si messageType es updated. Proporciona más detalles sobre la actualización.
  • resource: detalles de la entidad modificada.
  • schema: el nombre y la versión del esquema de carga.
  • deviceId: el id. del dispositivo que se ha cambiado.
  • enqueuedTime: la hora a la que se produjo este cambio en IoT Central.
  • enrichments: cualquier enriquecimiento configurado en la exportación.

Pasos siguientes

Ahora que sabe cómo exportar a Azure Data Explorer, es recomendable que aprenda a Exportar a Webhook.