Tutorial: Uso del enriquecimiento de mensajes de Azure IoT Hub

El enriquecimiento de mensajes es la capacidad de Azure IoT Hub para marcar los mensajes con información adicional antes de que los mensajes se envíen al punto de conexión designado. Una razón para utilizar el enriquecimiento de mensajes es incluir datos que se pueden usar para simplificar el procesamiento descendente. Por ejemplo, el enriquecimiento de mensajes de dispositivos con una etiqueta de dispositivo gemelo puede reducir la carga de los clientes para realizar llamadas API de dispositivos gemelos para obtener esta información. Para más información, consulte la introducción al enriquecimiento de mensajes.

En la primera parte de este tutorial, ha visto cómo crear puntos de conexión personalizados y cómo enrutar mensajes a otros servicios de Azure. En este tutorial, verá cómo crear y configurar los recursos adicionales necesarios para probar la riqueza de los mensajes para un centro de IoT. Los recursos incluyen un segundo contenedor de almacenamiento para una cuenta de almacenamiento existente (creada en la primera parte del tutorial) para contener los mensajes enriquecidos y una ruta de mensajes para enviarlos allí. Una vez finalizadas las configuraciones para el enrutamiento de mensajes y el enriquecimiento de mensajes, use una aplicación para enviar mensajes al centro de IoT. A continuación, el centro los enruta a ambos contenedores de almacenamiento. Solo están enriquecidos los mensajes enviados al punto de conexión para el contenedor de almacenamiento enriquecido.

En este tutorial se realizan las siguientes tareas:

• Cree un segundo contenedor en la cuenta de almacenamiento.
• Cree otro punto de conexión personalizado y enrute los mensajes a él desde el centro de IoT.
• Configure los enriquecimientos de mensajes que se enrutan al nuevo punto de conexión.
• Ejecute una aplicación que simule un dispositivo IoT que envía mensajes al centro.
• Vea los resultados y compruebe que se aplican los enriquecimientos de mensajes a los mensajes de destino.

Requisitos previos

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

• Debe haber completado el Tutorial: Envío de datos de dispositivo a Azure Storage mediante el enrutamiento de mensajes IoT Hub y haber realizado el mantenimiento de los recursos que ha creado para él.

• Asegúrese de que está abierto el puerto 8883 del firewall. En el dispositivos de 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).

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.

Creación de un segundo contenedor en la cuenta de almacenamiento

En la primera parte de este tutorial, ha creado una cuenta de almacenamiento y un contenedor para los mensajes enrutados. Ahora debe crear un segundo contenedor para los mensajes enriquecidos.

Azure Portal

1. Abra Azure Portal y busque Cuentas de almacenamiento.

2. Seleccione la cuenta creada anteriormente.

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

4. Seleccione Contenedor para crear un contenedor.

   

5. Asigne al contenedor el nombre enriched y seleccione Crear.

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.

Los valores de estas variables deben ser para los mismos recursos que usó en la primera parte de este tutorial.

1. Defina las variables para el centro de IoT, 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.

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

   DEVICE_ID: reemplace este marcador de posición por el identificador del dispositivo.

   STORAGE_NAME: reemplace este marcador de posición por el nombre de la cuenta de almacenamiento.

   Para este tutorial, el valor de la variable containerName debe enriquecerse.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

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

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

Enrutamiento de mensajes a un segundo punto de conexión

Cree un segundo punto de conexión y una ruta para los mensajes enriquecidos.

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	Escriba ContosoStorageEndpointEnriched.
   Contenedor de Azure Storage	Seleccione Seleccionar un contenedor. Siga las indicaciones para seleccionar la cuenta de almacenamiento y el contenedor enriquecido 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 Create + next (Crear y siguiente).

5. Siga creando la nueva ruta, ahora que ha agregado el punto de conexión de almacenamiento. Proporcione la siguiente información para la nueva ruta:

   Parámetro	Value
   Nombre	ContosoStorageRouteEnriched
   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á establecido en enabled.
   Consulta de enrutamiento	escriba level="storage" como cadena de consulta.

   

6. Seleccione Create + add enrichments (Crear y agregar enriquecimientos).

CLI de Azure

1. Configure las variables para el punto de conexión y los comandos de ruta para usar los valores ContosoStorageEndpointEnriched y ContosoStorageRouteEnriched, respectivamente.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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"'
   

Adición del enriquecimiento de mensajes al nuevo punto de conexión

Cree tres enriquecimientos de mensajes que se enrutarán al contenedor de almacenamiento enriquecido.

Azure Portal

1. En la pestaña Enrichment (Enriquecimiento) del asistente Add a route (Agregar una ruta), agregue tres enriquecimientos de mensaje para los mensajes que van al punto de conexión del contenedor de almacenamiento que se llama enriquecido.

   Agregue estos valores como enriquecimientos de mensaje para el punto de conexión ContosoStorageEndpointEnriched:

   Nombre	Value
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (suponiendo que el dispositivo gemelo tenga una etiqueta de ubicación)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Cuando haya terminado, los enriquecimientos deberían ser similares a lo siguiente:

   

2. Seleccione Agregar para agregar los enriquecimientos de mensaje.

CLI de Azure

Realice tres llamadas al comando az iot hub message-enrichment create para agregar enriquecimientos de mensajes a la ruta que va al punto de conexión creado anteriormente.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Ahora tiene los enriquecimientos de mensajes configurados para todos los mensajes enrutados al punto de conexión que creó para los mensajes enriquecidos. Si no desea agregar una etiqueta de ubicación al dispositivo gemelo, puede ir directamente a la sección Prueba del enriquecimiento de mensajes para continuar con el tutorial.

Añadir etiqueta de ubicación al dispositivo gemelo

Uno de los enriquecimientos de mensajes configurados en IoT Hub especifica una clave de DeviceLocation con su valor determinado por la siguiente ruta de acceso del dispositivo gemelo: $twin.tags.location. Si el dispositivo no tiene una etiqueta de ubicación, la ruta de acceso gemela, $twin.tags.location, se marcará como una cadena para la clave DeviceLocation en el enriquecimiento de mensajes.

Siga estos pasos para agregar una etiqueta de ubicación al gemelo del dispositivo:

Azure Portal

1. Vaya a IoT Hub en Azure Portal.

2. Seleccione Dispositivos en el menú de navegación del centro de IoT y, después, seleccione su dispositivo.

3. Seleccione la pestaña Dispositivo gemelo en la parte superior de la página del dispositivo y agregue la siguiente línea justo antes de la llave de cierre en la parte inferior del dispositivo gemelo. Después, seleccione Guardar.

     , "tags": {"location": "Plant 43"}
   

   

CLI de Azure

Use el comando az iot hub device-twin update para actualizar el dispositivo gemelo con una nueva clave de etiqueta y un valor.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Sugerencia

Espere unos cinco minutos antes de continuar con la sección siguiente. Las actualizaciones del dispositivo gemelo pueden tardar hasta ese tiempo en reflejarse en los valores de enriquecimiento de mensajes.

Para más información sobre cómo se controlan las rutas de acceso de dispositivo gemelo con enriquecimientos de mensajes, consulte Limitaciones de enriquecimiento de mensajes. Para más información, consulte Información y uso de dispositivos gemelos en IoT Hub.

Prueba del enriquecimiento de mensajes

Ahora que el enriquecimiento de mensajes está configurado para el punto de conexión ContosoStorageEndpointEnriched, ejecute la aplicación de dispositivo simulado para enviar mensajes al centro de IoT. En este momento, el enrutamiento de mensajes se ha configurado de la siguiente manera:

• Los mensajes enrutados al punto de conexión de almacenamiento que creó en la primera parte del tutorial no se enriquecerán y se almacenarán en el contenedor de almacenamiento que creó después.

• Los mensajes enrutados al punto de conexión de almacenamiento ContosoStorageEndpointEnriched se enriquecerán y almacenarán en el contenedor de almacenamiento enriquecido.

Si aún no está ejecutando la aplicación de consola SimulatedDevice de la primera parte de este tutorial, vuelva a ejecutarla:

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. En la carpeta de ejemplo, vaya a la carpeta /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. Las definiciones de variables que ha actualizado antes deben seguir siendo válidas, pero, si no es así, edítelas en el archivo Program.cs:

   1. Busque las definiciones de variables en la parte superior de la clase Program. Actualice las siguientes variables con su propia información:

      • s_myDeviceId: id. del dispositivo que asignó al registrar el dispositivo en el centro de IoT.
      • s_iotHubUri: nombre de host del centro de IoT, que adquiere el formato IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: clave principal del dispositivo que se encuentra en la información de identidad del dispositivo.

   2. Guarde y cierre el archivo.

3. Ejecución del código de ejemplo:

   dotnet run
   

Después de salir de la aplicación de consola para que se ejecute durante unos minutos, vea los datos:

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

2. Seleccione Explorador de almacenamiento en el menú de navegación. Seleccione Contenedores de blob para ver los dos contenedores que creó durante estos tutoriales.

   

Los mensajes del contenedor denominados enriched cuentan con enriquecimiento de mensajes incluido en los mensajes. Los mensajes del contenedor que creó anteriormente contienen los mensajes sin procesar y sin enriquecimiento. Explore en profundidad el contenedor enriquecido hasta que llegue al final y luego abra el archivo de mensaje más reciente. A continuación, haga lo mismo para que el otro contenedor compruebe que uno está enriquecido y otro no lo está.

Cuando examine los mensajes enriquecidos, debería ver "myIotHub" con el nombre del centro, la ubicación y el identificador de cliente, de esta manera:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Limpieza de recursos

Para quitar todos los recursos que creó en las dos partes de 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, puede seleccionar recursos individuales incluidos para eliminarlos.

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 configurado y probado los enriquecimientos de mensajes para los mensajes de IoT Hub a medida que se enrutan a un punto de conexión.

Para obtener más información sobre el enriquecimiento de mensajes, consulte la Introducción al enriquecimiento de mensajes.

Para más información sobre un centro de IoT, continúe con el siguiente tutorial.

Tutorial: Configuración y uso de métricas y registros con un centro de IoT