Exportación de datos de IoT a Webhook

Artículo
03/10/2024

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

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 Webhook

En el caso de los destinos de Webhook, IoT Central exporta los datos casi en tiempo real. Los datos del cuerpo del mensaje están en el mismo formato que en Event Hubs y Service Bus.

Creación de un destino de Webhook

Puede exportar los datos a un punto de conexión de Webhook HTTP disponible públicamente. Puede crear un punto de conexión de Webhook de prueba mediante RequestBin. RequestBin limita las solicitudes cuando se alcanza el límite:

Vaya a RequestBin.
Seleccione Crear RequestBin.
Inicie sesión con uno de los métodos disponibles.
Copie la dirección URL de RequestBin. Use esta dirección URL al probar la exportación de datos.

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

Seleccione + Nuevo destino.
Elija Webhook como tipo de destino.
Pegue la dirección URL de devolución de llamada del punto de conexión de Webhook. También puede configurar la autorización de Webhook y agregar encabezados personalizados.
- Para OAuth2.0, solo se admite el flujo de concesión de credenciales de cliente. Al guardar el destino, IoT Central se comunica con el proveedor de OAuth para recuperar un token de autorización. Este token se adjuntará al encabezado Authorization para cada mensaje que se envíe a este destino.
- En Token de autorización, puede especificar un valor de token que se adjuntará directamente al encabezado Authorization para cada mensaje que se envíe a este destino.
Seleccione Guardar.

Configuración de OAuth 2.0 de ejemplo

En este ejemplo, se muestra cómo configurar un destino de webhook para usar una aplicación de funciones de Azure protegida mediante inicio de sesión de Microsoft Entra:

Configuración	Ejemplo	Notas
Tipo de destino	webhook
Dirección URL de devolución de llamadas	`https://myapp.azurewebsites.net/api/HttpExample`	Dirección URL de la función.
Authorization	OAuth 2.0
Dirección URL del token	`https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token`	Dirección URL que se va a usar para recuperar un token. Puede encontrar este valor en la aplicación de funciones: Autenticación> su proveedor de identidades de Microsoft > Puntos de conexión > Punto de conexión de tokens de OAuth 2.0 (v2)
Id. de cliente	`your-client-id`	Identificador de cliente de la aplicación de funciones. Puede encontrar este valor en la aplicación de funciones: Autenticación> su proveedor de identidades de Microsoft > Identificador de aplicación (cliente)
Secreto del cliente	`your-client-secret`	Secreto de cliente de la aplicación de funciones. Puede encontrar este valor en la aplicación de funciones: Autenticación> su proveedor de identidades de Microsoft > Certificados y secretos
Público	N/D	En blanco si usa una aplicación de funciones.
Ámbito	`https://your-client-id/.default`	Ámbito del token. Para una aplicación de funciones, use el valor del identificador de cliente.**
Tipo de contenido de la solicitud de token	Automático

Otros destinos de webhook pueden requerir valores diferentes para esta configuración.

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:

Inicie sesión en su aplicación de IoT Central.
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.
Seleccione + New export (+ Nueva exportación).
Escriba un nombre para mostrar para la nueva exportación y asegúrese de que la exportación de datos está habilitada.

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

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

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:

Seleccione + Destino para agregar un destino que ya haya creado, o seleccione Crear uno nuevo.
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.
Seleccione + Destino para agregar hasta cinco destinos a una única exportación.
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);
}

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

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

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.

Pasos siguientes

Ahora que sabe cómo exportar datos a Service Bus, el siguiente paso sugerido es aprender a exportar a Event Hubs.