Tutorial: Envío de datos de dispositivo a Azure Storage mediante el enrutamiento de mensajes IoT Hub

Use enrutamiento de mensajes en Azure IoT Hub para enviar datos de telemetría desde los dispositivos IoT a los servicios de Azure, como Blob Storage, colas de Service Bus, temas de Service Bus y Event Hubs. Cada centro de IoT tiene un punto de conexión integrado predeterminado que es compatible con Event Hubs. También puede crear puntos de conexión personalizados y enrutar mensajes a otros servicios de Azure mediante la definición de consultas de enrutamiento. Cada mensaje que llega al centro de IoT se enruta a todos los puntos de conexión cuyas consultas de enrutamiento coinciden. Si un mensaje no coincide con ninguna de las consultas de enrutamientos definidas, se enruta al punto de conexión predeterminado.

En este tutorial se realizan las siguientes tareas:

• Cree un centro de IoT y envíe mensajes de dispositivo a él.
• Cree una cuenta de almacenamiento.
• Cree un punto de conexión personalizado para la cuenta de almacenamiento y enrute los mensajes a él desde el centro de IoT.
• Vea los mensajes del dispositivo en el blob de la cuenta de almacenamiento.

Requisitos previos

• Suscripción a Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

• Una instancia de IoT Hub en la suscripción de Azure. Si aún no tiene un centro, puede seguir los pasos descritos en Creación de un centro de IoT.

• En este tutorial se usa un código de ejemplo del SDK de Azure IoT para C#.

  • Descargue o clone el repositorio del SDK en la máquina de desarrollo.
  • Debe tener .NET Core 3.0.0, o cualquier versión superior, en la máquina de desarrollo. Para comprobar la versión, ejecute dotnet --version y descargue .NET si es necesario.

• Asegúrese de que el puerto 8883 está abierto en el firewall. En el ejemplo de este tutorial se usa el protocolo MQTT, que se comunica mediante el puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

• Opcionalmente, instale Azure IoT Explorer. Esta herramienta le ayuda a observar los mensajes a medida que llegan al centro de IoT. En este artículo se usa Azure IoT Explorer.

Azure Portal

No hay otros requisitos previos para Azure Portal.

CLI de Azure

• Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

  

• Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

  • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

  • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

  • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

Registro de un dispositivo y envío de mensajes a IoT Hub

Registre un nuevo dispositivo en su centro de IoT.

Azure Portal

1. Inicie sesión en Azure Portal y vaya a IoT Hub.

2. Seleccione Dispositivos en la sección Administración de dispositivos del menú.

3. Seleccione Agregar dispositivo.

   

4. Proporcione un id. de dispositivo y seleccione Guardar.

5. El nuevo dispositivo debe estar en la lista de dispositivos ahora. Si no es así, actualice la página. Seleccione el id. de dispositivo y abra la página de detalles del dispositivo.

6. Copie una de las claves del dispositivo y guárdela. Usará este valor para configurar el código de ejemplo que genera mensajes de telemetría de dispositivos simulados.

   

CLI de Azure

Sugerencia

Muchos de los comandos de la CLI usados en este tutorial usan los mismos parámetros. Para su comodidad, tenemos que definir variables locales que se pueden llamar según sea necesario. Asegúrese de ejecutar todos los comandos de la misma sesión o, de lo contrario, tendrá que volver a definir las variables.

1. Defina variables para el centro de IoT y el dispositivo.

   IOTHUB_NAME: sustituya este marcador de posición por el nombre del centro de IoT.

   DEVICE_NAME: reemplace este marcador de posición por cualquier nombre que quiera usar para el dispositivo de este tutorial.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Ejecute el comando az iot hub device-identity create en el shell de la CLI. Este comando crea la identidad del dispositivo.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. En la salida de la identidad del dispositivo, copie el valor primaryKey sin las comillas circundantes y guárdela. Usará este valor para configurar el código de ejemplo que genera mensajes de telemetría de dispositivos simulados.

Ahora que tiene una clave y un id. de dispositivo, use el código de ejemplo para empezar a enviar mensajes de telemetría de dispositivo a IoT Hub.

Sugerencia

Si sigue los pasos de la CLI de Azure para este tutorial, ejecute el código de ejemplo en una sesión independiente. De este modo, puede permitir que el código de ejemplo continúe ejecutándose mientras sigue el resto de los pasos de la CLI.

1. Si no formaba parte de los requisitos previos, descargue o clone ahora el SDK de Azure IoT para el repositorio de C# desde GitHub.

2. En la carpeta donde descargó o clonó el SDK, vaya a la carpeta azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample.

3. Instale el SDK de C# de Azure IoT y las dependencias necesarias, tal como se especifica en el archivo HubRoutingSample.csproj:

   dotnet restore
   

4. En el editor que prefiera, edite el archivo Parameters.cs. Este archivo muestra los parámetros que se admiten en el ejemplo. En este artículo, solo se usará el parámetro PrimaryConnectionString al ejecutar el ejemplo. Revise el código de este archivo. No es necesario realizar ningún cambio.

5. Compile y ejecute el código de ejemplo mediante el comando siguiente:

   Reemplace <myDevicePrimaryConnectionString> por la cadena de conexión principal del dispositivo en el centro de IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Debería empezar a ver los mensajes impresos en la salida a medida que se envían a IoT Hub. Deje este programa en marcha durante el tutorial.

Configuración del explorador de IoT para ver mensajes

Configure el explorador de IoT para conectarse al centro de IoT y leer mensajes a medida que llegan al punto de conexión integrado.

En primer lugar, recupere la cadena de conexión para la instancia de IoT Hub.

Azure Portal

1. En Azure Portal, vaya hasta el centro de IoT.

2. Seleccione Directivas de acceso compartido en la sección Configuración de seguridad del menú.

3. Seleccione la directiva iothubowner.

   

4. Copie el contenido de Cadena de conexión principal.

   

CLI de Azure

1. Ejecute el comando az iot hub connection-string show:

   az iot hub connection-string show --hub-name $hubName
   

2. Copie la cadena de conexión sin las comillas circundantes.

Ahora, use esa cadena de conexión para configurar el explorador de IoT para IoT Hub.

1. Abra el explorador de IoT en la máquina de desarrollo.

2. Seleccione Agregar conexión.

   

3. Pegue la cadena de conexión del centro en el cuadro de texto.

4. Seleccione Guardar.

5. Una vez que se conecte al centro de IoT, debería ver una lista de dispositivos. Seleccione el id. del dispositivo que creó para este tutorial.

6. Seleccione Telemetría.

7. Con el dispositivo en ejecución, seleccione Iniciar. Si el dispositivo no se está ejecutando, no verá la telemetría.

   

8. Debería ver los mensajes que llegan desde el dispositivo, con el más reciente mostrado en la parte superior.

   

   Observe los mensajes entrantes durante unos instantes para comprobar que ve tres tipos diferentes de mensajes: normal, storage y critical. Después de ver esto, puedes detener el dispositivo.

Todos estos mensajes llegan al punto de conexión integrado predeterminado del centro de IoT. En las secciones siguientes, vamos a crear un punto de conexión personalizado y a enrutar algunos de estos mensajes al almacenamiento en función de las propiedades del mensaje. Esos mensajes dejarán de aparecer en el explorador de IoT porque los mensajes solo van al punto de conexión integrado cuando no coinciden con ninguna otra ruta en el centro de IoT.

Configuración del enrutamiento de mensajes

Va a enrutar mensajes a diferentes recursos en función de las propiedades que el dispositivo simulado adjunta al mensaje. Los mensajes que no tengan una ruta personalizada se envían al punto de conexión predeterminado (mensajes y eventos).

La aplicación de ejemplo de este tutorial asigna una propiedad level a cada mensaje que envía a IoT Hub. A cada mensaje se le asigna aleatoriamente un nivel normal, storage o critical.

El primer paso es configurar el punto de conexión al que se enrutarán los datos. El segundo paso es configurar la ruta de mensajes que usa ese punto de conexión. Después de configurar el enrutamiento, puede ver los puntos de conexión y las rutas de mensajes en el portal.

Crear una cuenta de almacenamiento

Cree una cuenta de Azure Storage y un contenedor dentro de esa cuenta, que contendrá los mensajes del dispositivo que se enrutan a ella.

Azure Portal

1. Abra Azure Portal y busque Cuentas de almacenamiento.

2. Seleccione Crear.

3. Proporcione los siguientes valores para la cuenta de almacenamiento:

   Parámetro	Valor
   Suscripción	Seleccione la misma suscripción que contiene el centro de IoT.
   Grupos de recursos	Seleccione el mismo grupo de recursos que contiene el centro de IoT.
   Nombre de cuenta de almacenamiento	Proporcione un nombre globalmente único para la cuenta de almacenamiento.
   Rendimiento	Acepte el valor predeterminado Estándar.

   

4. Para aceptar todos los demás valores predeterminados, seleccione Revisar y crear.

5. Una vez completada la validación, seleccione Crear.

6. Una vez finalizada la implementación, seleccione Ir al recurso.

7. En el menú de la cuenta de almacenamiento, seleccione Contenedores en la sección Almacenamiento de datos.

8. Seleccione + Contenedor para crear un nuevo contenedor.

   

9. Proporcione un nombre para el contenedor y seleccione Crear.

CLI de Azure

1. Defina las variables para la cuenta de almacenamiento y el contenedor.

   GROUP_NAME: reemplace este marcador de posición por el nombre del grupo de recursos que contiene el centro de IoT.

   STORAGE_NAME: reemplace este marcador de posición por un nombre para la cuenta de almacenamiento. Los nombres de cuenta de almacenamiento debe estar en minúsculas y ser únicos globalmente.

   CONTAINER_NAME: reemplace este marcador de posición por un nombre para el contenedor.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Use el comando az storage account create para crear una cuenta de almacenamiento estándar de uso general v2.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. Use el comando az storage container create para agregar un contenedor a la cuenta de almacenamiento.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Enrutamiento a una cuenta de almacenamiento

Ahora, configure el enrutamiento de la cuenta de almacenamiento. En esta sección se define un nuevo punto de conexión que apunta a la cuenta de almacenamiento que ha creado. A continuación, cree una ruta que filtre los mensajes en los que la propiedad level esté establecida en storage y enrútelos al punto de conexión de almacenamiento.

Nota:

Se pueden escribir datos en Blob Storage con formato Apache Avro, que es el predeterminado, o JSON.

El formato de codificación solo se puede establecer en el momento en que se configura el punto de conexión de Blob Storage. No se puede cambiar el formato de un punto de conexión que ya se ha configurado. Cuando se usa la codificación JSON, debe establecer contentType en JSON y contentEncoding en UTF-8 en las propiedades del sistema de mensajes.

Para obtener más información sobre el uso de un punto de conexión de Blob Storage, consulte la guía sobre el enrutamiento Azure Storage.

Azure Portal

1. En Azure Portal, vaya hasta su instancia de IoT Hub.

2. En el menú de recursos de Configuración del centro, seleccione Enrutamiento de mensajes y, después, Agregar.

   

3. En la pestaña Punto de conexión, cree un punto de conexión de almacenamiento proporcionando esta información:

   Parámetro	Value
   Tipo de punto de conexión	Seleccione Storage.
   Nombre del extremo	Proporcione un nombre único para este punto de conexión.
   Contenedor de Azure Storage	Seleccione Seleccionar un contenedor. Siga las indicaciones para seleccionar la cuenta de almacenamiento y el contenedor que creó en la sección anterior.
   Encoding	Seleccione JSON. Si este campo está atenuado, la región de la cuenta de almacenamiento no admite JSON. En ese caso, continúe con el valor AVRO predeterminado.

   

4. Acepte los valores predeterminados para el resto de los parámetros y seleccione Crear + siguiente.

5. En la pestaña Ruta, proporcione la siguiente información para crear una ruta que apunte al punto de conexión de Storage que ha creado:

   Parámetro	Value
   Nombre	Cree un nombre para la ruta.
   Origen de datos	Compruebe que la opción Mensajes de telemetría del dispositivo está seleccionada en la lista desplegable.
   Habilitar ruta	Compruebe que este campo está marcado.
   Consulta de enrutamiento	escriba level="storage" como cadena de consulta.

   

6. Seleccione Crear y omitir enriquecimientos.

CLI de Azure

1. Configure las variables que necesita para los comandos de punto de conexión y ruta.

   ENDPOINT_NAME: proporcione un nombre para el punto de conexión que representa el contenedor de almacenamiento.

   ROUTE_NAME: proporcione un nombre para la ruta que filtra los mensajes para el punto de conexión de almacenamiento.

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. Use el comando az iot hub routing-endpoint create para crear un punto de conexión personalizado que apunte al contenedor de almacenamiento que creó en la sección anterior.

   az iot hub routing-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --endpoint-resource-group $resourceGroup \
     --endpoint-subscription-id $(az account show --query id -o tsv) \
     --endpoint-type azurestoragecontainer
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Use el comando az iot hub route create para crear una ruta que pase cualquier mensaje donde level=storage se dirija al punto de conexión del contenedor de almacenamiento.

   az iot hub route create \
     --name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Visualización de mensajes enrutados

Una vez creada la ruta en IoT Hub y habilitada, iniciará inmediatamente el enrutamiento de mensajes que cumplan su condición de consulta al punto de conexión de almacenamiento.

Supervisión del punto de conexión integrado con el explorador de IoT

Vuelva a la sesión del explorador de IoT en la máquina de desarrollo. Recuerde que el explorador de IoT supervisa el punto de conexión integrado para el centro de IoT. Esto significa que ahora debería ver solo los mensajes que no se enrutan mediante la ruta personalizada que hemos creado.

Vuelva a iniciar el ejemplo ejecutando el código. Observe los mensajes entrantes durante unos instantes y solo debería ver los mensajes en los que level está establecido en normal o critical.

Visualización de mensajes en el contenedor de almacenamiento

Compruebe que los mensajes llegan al contenedor de almacenamiento.

1. En Azure Portal, vaya a la cuenta de almacenamiento.

2. Seleccione Contenedores en la sección Almacenamiento de datos del menú.

3. Seleccione el contenedor que creó para este tutorial.

4. Debe haber una carpeta con el nombre del centro de IoT. Explore en profundidad la estructura de archivos hasta que llegue a un archivo .json.

   

5. Seleccione el archivo JSON y, a continuación, Descargar para descargar el archivo JSON. Descargue el archivo JSON y confirme que contiene mensajes del dispositivo con la propiedad level establecida en storage.

6. Deje de ejecutar el ejemplo.

Limpieza de recursos

Si desea quitar todos los recursos de Azure que ha creado para este tutorial, elimine el grupo de recursos. Esta acción elimina también todos los recursos del grupo. Si no desea eliminar todo el grupo de recursos, use el Azure Portal para buscar y eliminar los recursos individuales.

Si tiene intención de continuar con el siguiente tutorial, conserve los recursos que ha creado aquí.

Azure Portal

1. En Azure Portal, vaya al grupo de recursos que contiene el centro de IoT y la cuenta de almacenamiento de este tutorial.
2. Revise todos los recursos que se encuentran en el grupo de recursos para determinar cuáles desea limpiar.
   • Si desea eliminar todos los recursos, puede seleccionar Eliminar grupo de recursos.
   • Si solo desea eliminar determinados recursos, use las casillas situadas junto a cada nombre de recurso para seleccionar los que desea eliminar. A continuación, seleccione Eliminar.

CLI de Azure

1. Use el comando az resource list para ver todos los recursos del grupo de recursos.

   az resource list --resource-group $resourceGroup --output table
   

2. Revise todos los recursos que se encuentran en el grupo de recursos para determinar cuáles desea limpiar.

   • Si desea eliminar todos los recursos, use el comando az group delete.

     az group delete --name $resourceGroup
     

   • Si solo desea eliminar determinados recursos, use el comando az resource delete. Por ejemplo:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Pasos siguientes

En este tutorial ha aprendido a crear un punto de conexión personalizado para un recurso de Azure y, a continuación, a crear una ruta para enviar mensajes de dispositivo a ese punto de conexión. Continúe con el siguiente tutorial para aprender a enriquecer los mensajes con datos adicionales que se pueden usar para simplificar el procesamiento descendente.

Uso del enriquecimiento de mensajes de Azure IoT Hub