Exportación de datos de IoT a Event Hubs

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

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 Event Hubs

IoT Central exporta datos casi en tiempo real. Los datos están en el cuerpo del mensaje y están en formato JSON codificados como UTF-8.

Las anotaciones o el contenedor de propiedades del sistema del mensaje contienen los campos iotcentral-device-id, iotcentral-application-id, iotcentral-message-source y iotcentral-message-type, que tienen los mismos valores que los campos correspondientes del cuerpo del mensaje.

Opciones de conexión

Los destinos de Event Hubs permiten configurar la conexión con una cadena de conexión 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 Event Hubs

Identidad administrada

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 un espacio de nombres de Event Hubs existente al que exportar, ejecute el siguiente script en el entorno de Bash de Azure Cloud Shell. El script crea un grupo de recursos, un espacio de nombres de Event Hubs y un centro de eventos. A continuación, el script habilita la identidad administrada para la aplicación de IoT Central y asigna el rol que necesita para acceder al centro de eventos:

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

EH=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Event Hubs Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $EHNS.servicebus.windows.net"
echo "Event Hub: $EH"

Para proteger aún más el centro de eventos y permitir solo el acceso desde servicios de confianza con identidades administradas, consulte Exportación de datos a un destino seguro en una instancia de Azure Virtual Network.

Para crear el destino de Event Hubs en IoT Central en la página Exportación de datos:

1. Seleccione + Nuevo destino.

2. Elija Azure Event Hubs como tipo de destino.

3. Seleccione Identidad administrada asignada por el sistema como tipo de autorización.

4. Especifique el nombre de host del recurso de Event Hubs. A continuación, especifique el nombre del centro de eventos, que distingue mayúsculas de minúsculas. Un nombre de host tiene el aspecto siguiente: contoso-waste.servicebus.windows.net.

5. Seleccione Guardar.

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.

Cadena de conexión

Si no tiene un espacio de nombres de Event Hubs existente al que exportar, ejecute el siguiente script en el entorno de Bash de Azure Cloud Shell. El script crea un grupo de recursos, un espacio de nombres de Event Hubs y un centro de eventos. A continuación, imprime la cadena de conexión que se usará al configurar la exportación de datos en IoT Central:

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM
EH=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS
az eventhubs eventhub authorization-rule create --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --rights Send

CS=$(az eventhubs eventhub authorization-rule keys list --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Event hub connection string: $CS"

Para crear el destino de Event Hubs en IoT Central en la página Exportación de datos:

1. Seleccione + Nuevo destino.

2. Elija Azure Event Hubs como tipo de destino.

3. Seleccione Cadena de conexión como tipo de autorización.

4. Pegue la cadena de conexión del recurso Event Hubs y, si es necesario, especifique el nombre del centro de eventos, que distingue mayúsculas de minúsculas.

5. Seleccione Guardar.

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 mensajes de IoT Hub de dispositivo a nube.

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.

JavaScript

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);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(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.

Para Event Hubs, IoT Central exporta nuevos datos de mensajes al centro de eventos casi en tiempo real. En las propiedades de usuario (también conocidas como propiedades de la aplicación) de cada mensaje, iotcentral-device-id, iotcentral-application-id, iotcentral-message-source e iotcentral-message-type se incluyen automáticamente.

Pasos siguientes

Ahora que sabe cómo exportar a Event Hubs, es recomendable que aprenda Cómo exportar a Azure Data Explorer.