Conexión de datos de IoT Hub
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 una ingesta de datos continua desde los centros de IoT 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
- Los datos se leen desde el punto de conexión del centro de eventos en forma de objetos EventData.
- Consulte los formatos admitidos.
Nota:
IoT Hub no admite el formato .raw.
- Consulte los formatos de compresión admitidos.
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 Azure Portal, consulte Activación del 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.
Activación del 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:
En Azure Portal, vaya a su clúster.
Seleccione Bases de datos>Conexiones de datos.
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).
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 de dispositivo a 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 IoT Hub genera mensajes, este valor se establece en {iot hub name}. |
| 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 partitionsno 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 endpointde IoT Hub. Si configura cualquier otroMessage routing endpoint, los mensajes dejan de fluir aBuilt-in endpointa menos que se cree una ruta a ese punto de conexión. Configure una ruta al punto de conexióneventspara 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.
Enviando eventos
Consulte este proyecto de ejemplo que simula un dispositivo y genera datos.