Conexión de datos de IoT Hub

  • Artículo

Azure IoT Hub es un servicio administrado, hospedado en la nube, que actúa como centro de mensajes para las comunicaciones bidireccionales entre la aplicación IoT y los dispositivos que administra. Azure Data Explorer ofrece ingesta continua de IoT Hubs administrados por el cliente mediante su punto de conexión integrado compatible con event Hubs de mensajes de dispositivo a nube.

La canalización de ingesta de datos de IoT tiene varios pasos. En primer lugar, se crea un centro de IoT y se registra un dispositivo en él. A continuación, se crea una tabla de destino de Azure Data Explorer en la que se realizará la ingesta de datos en un formato determinado mediante el uso de las propiedades de la ingesta especificadas. La conexión de IoT Hub debe conocer el enrutamiento de eventos para conectarse a la tabla de Azure Data Explorer. Los datos se insertan con las propiedades seleccionadas según la asignación de propiedades del sistema de eventos. Este proceso se puede administrar desde Azure Portal, mediante programación con C# o Python o con una plantilla de Azure Resource Manager.

Para obtener información general sobre la ingesta de datos en Azure Data Explorer, consulte Introducción a la ingesta de datos de Azure Data Explorer.

Formato de datos

Propiedades de la ingesta

Las propiedades de la ingesta indican el proceso de ingesta, dónde enrutar los datos y cómo procesarlos. Puede especificar las propiedades de la ingesta de eventos mediante EventData.Properties. Puede establecer las siguientes propiedades:

Propiedad Descripción
Base de datos Nombre de la base de datos de destino (con distinción entre mayúsculas y minúsculas). Esta propiedad se puede usar si desea enviar los datos a una base de datos diferente de aquella en la que se creó la conexión de datos (la base de datos predeterminada). Para enrutar los datos a varias bases de datos, primero debe configurar la conexión como una conexión de varias bases de datos. Para más información, consulte Enrutamiento de eventos.
Tabla Nombre (distingue mayúsculas de minúsculas) de la tabla de destino existente. Invalida el valor de Table establecido en el panel Data Connection.
Formato Formato de datos. Invalida el valor de Data format establecido en el panel Data Connection.
IngestionMappingReference Nombre de la asignación de ingesta existente que se va a usar. Invalida el valor de Column mapping establecido en el panel Data Connection.
Encoding Codificación de datos, el valor predeterminado es UTF8. Puede ser cualquiera de las codificaciones compatibles con .NET.

Nota

Solamente se ingieren los eventos en cola después de crear la conexión de datos.

Enrutamiento de eventos

Cuando se crea una conexión de datos al clúster, se especifica el enrutamiento a dónde enviar los datos ingeridos. El enrutamiento predeterminado es a la tabla de destino especificada en la cadena de conexión asociada a la base de datos de destino. Al enrutamiento predeterminado de los datos, también se le conoce como enrutamiento estático. Puede especificar un enrutamiento alternativo para los datos mediante las propiedades de los datos de evento.

Enrutamiento de datos de eventos a una base de datos alternativa

El enrutamiento de datos a una base de datos alternativa está desactivado de forma predeterminada. Para enviar los datos a otra base de datos, primero debe establecer la conexión como una conexión de varias bases de datos. Para obtener un ejemplo de cómo hacerlo en el Azure Portal, vea Activar el enrutamiento de varias bases de datos. El usuario, grupo, entidad de servicio o identidad administrada que se usa para permitir el enrutamiento de la base de datos debe tener al menos el rol de colaborador y permisos de escritura en el clúster.

Para especificar una base de datos alternativa, establezca la propiedad de ingesta de la base de datos.

Advertencia

Si se especifica una base de datos alternativa sin establecer la conexión como una conexión de datos de varias bases de datos, se producirá un error en la ingesta.

Activar el enrutamiento de varias bases de datos

Para poder establecer una base de datos de destino alternativa, primero debe permitir el enrutamiento de los datos a varias bases de datos. Siga estos pasos para permitir el enrutamiento de los datos a bases de datos alternativas:

  1. En Azure Portal, vaya a su clúster.

  2. Seleccione Bases de datos>Conexiones de datos.

  3. Cree o edite una conexión de datos y, en el panel Conexión de datos, en Data routing settings (Configuración de enrutamiento de datos), active la opción de permitir el enrutamiento de datos a otra base de datos (conexión de datos de varias bases de datos).

    Captura de pantalla de Azure Data Explorer Web U I , en la que se muestra la opción Configuración de enrutamiento de datos establecida para permitir.

Enrutamiento de datos de eventos a una tabla alternativa

También puede especificar las propiedades de la tabla de destino para cada evento mediante las propiedades del evento. La conexión enrutará dinámicamente los datos tal y como se especifica en EventData.Properties, lo que invalida las propiedades estáticas de este evento. Para especificar una tabla alternativa, establezca la propiedad de ingesta de la tabla.

Nota

Si se ha seleccionado Mis datos incluyen información de enrutamiento, debe proporcionar la información de enrutamiento necesaria como parte de las propiedades de los eventos.

Asignación de propiedades del sistema de eventos

Las propiedades del sistema son una colección que se usa para almacenar las propiedades establecidas por el servicio IoT Hub en el momento en el que se recibe el evento. La conexión con IoT Hub de Azure Data Explorer insertará las propiedades seleccionadas en la carga de datos de la tabla.

Nota

En el caso de la asignación csv, las propiedades se agregan al principio del registro en el orden que se muestra en la tabla siguiente. En el caso de la asignación json, las propiedades se agregan según los nombres de propiedad de la tabla siguiente.

Propiedades del sistema

IoT Hub expone las siguientes propiedades del sistema para los mensajes de IoT Hub del dispositivo a la nube:

Propiedad Descripción
message-id Un identificador configurable por el usuario para el mensaje utilizado para patrones de solicitud y respuesta. Formato: Una cadena que distingue mayúsculas y minúsculas (de hasta 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
iothub-enqueuedtime Fecha y hora en la que IoT Hub recibió el mensaje del dispositivo a la nube.
user-id Un identificador que se utiliza para especificar el origen de los mensajes. Cuando los mensajes se generan mediante IoT Hub, este valor se establece {iot hub name}en .
iothub-connection-device-id Un identificador establecido por IoT Hub en los mensajes de dispositivo a nube. Contiene el deviceId del dispositivo que envió el mensaje.
iothub-connection-module-id Un identificador establecido por IoT Hub en los mensajes de dispositivo a nube. Contiene el moduleId del dispositivo que envió el mensaje.
iothub-connection-auth-generation-id Un identificador establecido por IoT Hub en los mensajes de dispositivo a nube. Contiene el valor connectionDeviceGenerationId (como se indica en Propiedades de identidad del dispositivo) del dispositivo que envió el mensaje.
iothub-connection-auth-method Un método de autenticación establecido por IoT Hub en los mensajes de dispositivo a nube. Esta propiedad contiene información sobre el método de autenticación usado para autenticar el dispositivo que envía el mensaje.
iothub-app-iothub-creation-time-utc Permite al dispositivo enviar la hora de creación de eventos al enviar datos en un lote.
iothub-creation-time-utc Permite al dispositivo enviar la hora de creación de eventos al enviar un único mensaje a la vez.
dt-dataschema El centro de IoT establece este valor en mensajes de dispositivo a la nube. Contiene el id. de modelo del dispositivo establecido en la conexión del dispositivo.
dt-subject Nombre del componente que envía los mensajes del dispositivo a la nube.

Si ha seleccionado Propiedades del sistema de eventos en la sección Origen de datos de la tabla, debe incluir las propiedades en el esquema de la tabla y la asignación.

Ejemplos de asignación de esquemas

Ejemplo de asignación de esquema de tabla

Si los datos incluyen tres columnas (Timespan, Metric y Value) y las propiedades que incluye son iothub-connection-device-id y sequence-number, cree o modifique el esquema de tabla mediante este comando:

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

Ejemplo de asignación CSV

Ejecute los siguientes comandos para agregar datos al principio del registro. Observe los valores ordinales.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

Ejemplo de asignación JSON

Los datos se agregan mediante la asignación de propiedades del sistema. Ejecute estos comandos:

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

Asignación de propiedades de usuario de eventos

No se admite el enriquecimiento de la carga de eventos de IoT Hub con las propiedades del usuario. Considere la posibilidad de insertar propiedades de usuario en el cuerpo del evento ascendente.

Conexión de IoT Hub

Nota

Para obtener el mejor rendimiento, cree todos los recursos en la misma región que el clúster de Azure Data Explorer.

Creación de un IoT Hub

Si aún no lo tiene, cree un centro de eventos. La conexión a IoT Hub se puede administrar desde Azure Portal, mediante programación con C# o Python o con una plantilla de Azure Resource Manager.

Nota

  • El número device-to-cloud partitions no es modificable, por lo que debería tener en cuenta la escala a largo plazo a la hora de configurar el número de particiones.
  • El grupo de consumidores debe ser único por consumidor. Cree un grupo de consumidores dedicado para la conexión de Azure Data Explorer. Busque el recurso en Azure Portal y vaya a Built-in endpoints (Puntos de conexión integrados) para agregar un nuevo grupo de consumidores.
  • La conexión de datos usa el elemento Built-in endpoint de IoT Hub. Si configura cualquier otro Message routing endpoint, los mensajes dejan de fluir a Built-in endpoint a menos que se cree una ruta a ese punto de conexión. Configure una ruta al punto de conexión events para asegurarse de que los mensajes continúen fluyendo hasta el punto de conexión integrado si se agrega una nueva ruta. Para más información, consulte Solución de problemas del enrutamiento de mensajes de IoT Hub.

Envío de eventos

Consulte este proyecto de ejemplo que simula un dispositivo y genera datos.

Paso siguiente

Creación de una conexión de datos IoT Hub