Tutorial: Uso de la CLI de Azure para configurar el enrutamiento de mensajes de IoT Hub

El enrutamiento de mensajes permite enviar datos de telemetría desde dispositivos de IoT a puntos de conexión integrados compatibles con el centro de eventos o puntos de conexión personalizados como Blob Storage, colas de Service Bus, temas de Service Bus y Event Hubs. Para configurar el enrutamiento de mensajes personalizado, cree consultas de enrutamiento para personalizar la ruta que coincide con una condición determinada. Una vez configurado, los datos entrantes se enrutan automáticamente a los puntos de conexión mediante IoT Hub. Si un mensaje no coincide con ninguna de las consultas de enrutamientos definidas, se enruta al punto de conexión predeterminado.

En este tutorial de dos partes, aprenderá a configurar y usar las consultas de enrutamiento personalizadas con IoT Hub. Enrutará los mensajes desde un dispositivo IoT a uno de los múltiples puntos de conexión, entre los que se incluyen Blob Storage y una cola de Service Bus. Una aplicación lógica recogerá los mensajes que se envían a la cola de Service Bus, que se enviarán por correo electrónico. Los mensajes que no tienen definido el enrutamiento de mensajes personalizado se envían al punto de conexión predeterminado y, a continuación, Azure Stream Analytics los recoge y se muestran en una visualización de Power BI.

Para completar las dos partes de este tutorial, realice las siguientes tareas:

Parte I: Creación de recursos, configuración del enrutamiento de mensajes

Parte II: Envío de mensajes al centro, visualización de los resultados del enrutamiento

Requisitos previos

• Para la primera parte de este tutorial:

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

• Para la segunda parte de este tutorial:

  • Debe haber completado la parte I de este tutorial y seguir disponiendo de los recursos.
  • Instale Visual Studio.
  • Debe tener acceso a una cuenta de Power BI para realizar el análisis del flujo del punto de conexión predeterminado. (pruebe Power BI de manera gratuita).
  • Debe tener una cuenta profesional o educativa para enviar notificaciones por correo electrónico.
  • 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).

Uso de Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.

Para iniciar Azure Cloud Shell:

Opción	Ejemplo o vínculo
Seleccione Pruébelo en la esquina superior derecha de un bloque de código. Solo con seleccionar Pruébelo no se copia automáticamente el código en Cloud Shell.
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.

Para ejecutar el código de este artículo en Azure Cloud Shell:

1. Inicie Cloud Shell.

2. Seleccione el botón Copiar de un bloque de código para copiar el código.

3. Pegue el código en la sesión de Cloud Shell. Para ello, seleccione Ctrl+Mayús+V en Windows y Linux, o bien seleccione Cmd+Mayús+V en macOS.

4. Seleccione Entrar para ejecutar el código.

Creación de recursos de base

Antes de configurar el enrutamiento de mensajes, deberá crear una instancia de IoT Hub, una cuenta de almacenamiento y una cola de Service Bus. Estos recursos pueden crearse mediante uno de los cuatro artículos que están disponibles para la parte 1 de este tutorial: Azure Portal, una plantilla de Azure Resource Manager, la CLI de Azure o Azure PowerShell.

Use el mismo grupo de recursos y la misma ubicación para todos los recursos. Al final, puede quitar todos los elementos en un solo paso mediante la eliminación del grupo de recursos.

A continuación se muestra un resumen de los pasos que se deben realizar en las secciones siguientes:

1. Cree un grupo de recursos.

2. Creación de una instancia de IoT Hub en el nivel S1. Agregue un grupo de consumidores a la instancia de IoT Hub. El grupo de consumidores lo utiliza Azure Stream Analytics al recuperar datos.

   Nota

   Debe usar un centro de Iot en un nivel de pago para realizar este tutorial. El nivel gratis solo le permite configurar un punto de conexión, y en este tutorial se necesitan varios.

3. Cree una cuenta de almacenamiento V1 estándar con replicación Standard_LRS.

4. Cree un espacio de nombres de Service Bus y una cola.

5. Cree una identidad de dispositivo para el dispositivo simulado que envíe mensajes al centro. Guarde la clave para la fase de pruebas. (Si crea una plantilla de Resource Manager, esto se realizará después de implementar la plantilla).

Descarga del script (opcional)

En la segunda parte de este tutorial, descargará y ejecutará una aplicación de Visual Studio para enviar mensajes a IoT Hub. En esa descarga hay una carpeta que contiene la plantilla de Azure Resource Manager y el archivo de parámetros, así como los scripts de la CLI de Azure y PowerShell.

Si desea ver el script terminado, descargue los ejemplos de C# de Azure IoT. Descomprima el archivo main.zip. El script de la CLI de Azure se encuentra en /iot-hub/Tutorials/Routing/SimulatedDevice/resources/ como iothub_routing_cli.azcli.

Uso de la CLI de Azure para crear los recursos

Copie y pegue el siguiente script en Cloud Shell y presione Entrar. El script se ejecuta de línea en línea. Con esta primera sección del script creará los recursos de base para este tutorial, incluida la cuenta de almacenamiento, la instancia de IoT Hub, el espacio de nombres de Service Bus y la cola de Service Bus. Conforme avance en el resto del tutorial, copie cada bloque de script y péguelo en Cloud Shell para ejecutarlo.

Hay varios nombres de recurso que deben ser únicos globalmente, como el nombre de IoT Hub y el nombre de la cuenta de almacenamiento. Para facilitar esta tarea, se anexan los nombres de los recursos con un valor alfanumérico aleatorio denominado randomValue. El valor RandomValue se genera una vez en la parte superior del script y se anexa a los nombres de los recursos según sea necesario en el script. Si no desea que sea aleatorio, puede establecerlo en una cadena vacía o en un valor específico.

# This command retrieves the subscription id of the current Azure account. 
# This field is used when setting up the routing queries.
subscriptionID=$(az account show --query id -o tsv)

# Concatenate this number onto the resources that have to be globally unique.
# You can set this to "" or to a specific value if you don't want it to be random.
# This retrieves a random value.
randomValue=$RANDOM

# This command installs the IOT Extension for Azure CLI.
# You only need to install this the first time.
# You need it to create the device identity. 
az extension add --name azure-iot

# Set the values for the resource names that 
#   don't have to be globally unique.
location=westus
resourceGroup=ContosoResources
iotHubConsumerGroup=ContosoConsumers
containerName=contosoresults
iotDeviceName=Contoso-Test-Device

# Create the resource group to be used
#   for all the resources for this tutorial.
az group create --name $resourceGroup \
    --location $location

# The IoT hub name must be globally unique, 
#   so add a random value to the end.
iotHubName=ContosoTestHub$randomValue 
echo "IoT hub name = " $iotHubName

# Create the IoT hub.
az iot hub create --name $iotHubName \
    --resource-group $resourceGroup \
    --sku S1 --location $location

# Add a consumer group to the IoT hub for the 'events' endpoint.
az iot hub consumer-group create --hub-name $iotHubName \
    --name $iotHubConsumerGroup

# The storage account name must be globally unique, 
#   so add a random value to the end.
storageAccountName=contosostorage$randomValue
echo "Storage account name = " $storageAccountName

# Create the storage account to be used as a routing destination.
az storage account create --name $storageAccountName \
    --resource-group $resourceGroup \
    --location $location \
    --sku Standard_LRS

# Get the primary storage account key. 
#    You need this to create the container.
storageAccountKey=$(az storage account keys list \
    --resource-group $resourceGroup \
    --account-name $storageAccountName \
    --query "[0].value" | tr -d '"') 

# See the value of the storage account key.
echo "storage account key = " $storageAccountKey

# Create the container in the storage account. 
az storage container create --name $containerName \
    --account-name $storageAccountName \
    --account-key $storageAccountKey \
    --public-access off

# The Service Bus namespace must be globally unique, 
#   so add a random value to the end.
sbNamespace=ContosoSBNamespace$randomValue
echo "Service Bus namespace = " $sbNamespace

# Create the Service Bus namespace.
az servicebus namespace create --resource-group $resourceGroup \
    --name $sbNamespace \
    --location $location

# The Service Bus queue name must be globally unique, 
#   so add a random value to the end.
sbQueueName=ContosoSBQueue$randomValue
echo "Service Bus queue name = " $sbQueueName

# Create the Service Bus queue to be used as a routing destination.
az servicebus queue create --name $sbQueueName \
    --namespace-name $sbNamespace \
    --resource-group $resourceGroup

# Create the IoT device identity to be used for testing.
az iot hub device-identity create --device-id $iotDeviceName \
    --hub-name $iotHubName

# Retrieve the information about the device identity, then copy the primary key to
#   Notepad. You need this to run the device simulation during the testing phase.
az iot hub device-identity show --device-id $iotDeviceName \
    --hub-name $iotHubName

Ahora que los recursos de base están configurados, puede continuar por el enrutamiento de mensajes.

Configuración del enrutamiento de mensajes

Va a enrutar mensajes a diferentes recursos en función de 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). En el siguiente tutorial, enviará mensajes a IoT Hub y verá cómo se enrutan a los distintos destinos.

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.

Para crear un punto de conexión de enrutamiento, use az iot hub routing-endpoint create. Para crear la ruta de mensajes para el punto de conexión, use az iot hub route create.

Enrutamiento a una cuenta de almacenamiento

En primer lugar, configure el punto de conexión para la cuenta de almacenamiento y, después, configure la ruta.

Estas son las variables utilizadas por el script que se debe establecer en la sesión de Cloud Shell:

storageConnectionString: Este valor se recupera de la cuenta de almacenamiento configurada en el script anterior. El enrutamiento de mensajes lo utiliza para acceder a la cuenta de almacenamiento.

resourceGroup: el grupo de recursos aparece dos veces, configure los datos de su grupo de recursos.

endpoint subscriptionID: este campo se establece con el identificador de suscripción de Azure del punto de conexión.

endpointType: este campo es el tipo de punto de conexión. Este valor debe establecerse en azurestoragecontainer, eventhub, servicebusqueue o servicebustopic. Para los fines de este tutorial, establézcalo en azurestoragecontainer.

iotHubName: este campo es el nombre del centro que realizará el enrutamiento.

containerName: este campo es el nombre del contenedor de la cuenta de almacenamiento en la que se escribirán los datos.

encoding: este campo será avro o json. Esta opción denota el formato de los datos almacenados.

routeName: este campo es el nombre de la ruta que se va a configurar.

endpointName: este campo es el nombre que identifica el punto de conexión.

enabled: el valor predeterminado de este campo es true, lo cual indica que la ruta de mensajes debe estar habilitada tras la creación.

condition: este campo es la consulta utilizada para filtrar los mensajes enviados a este punto de conexión. La condición de consulta para que los mensajes se enruten al almacenamiento es level="storage".

Copie este script, péguelo en la ventana de Cloud Shell y ejecútelo.

##### ROUTING FOR STORAGE ##### 

endpointName="ContosoStorageEndpoint"
endpointType="azurestoragecontainer"
routeName="ContosoStorageRoute"
condition='level="storage"'

# Get the connection string for the storage account.
# Adding the "-o tsv" makes it be returned without the default double quotes around it.
storageConnectionString=$(az storage account show-connection-string \
  --name $storageAccountName --query connectionString -o tsv)

El siguiente paso es crear el punto de conexión de enrutamiento para la cuenta de almacenamiento. También se especificará el contenedor donde se almacenarán los resultados. El contenedor se creó antes, cuando se creó la cuenta de almacenamiento.

# Create the routing endpoint for storage.
az iot hub routing-endpoint create \
  --connection-string $storageConnectionString \
  --endpoint-name $endpointName \
  --endpoint-resource-group $resourceGroup \
  --endpoint-subscription-id $subscriptionID \
  --endpoint-type $endpointType \
  --hub-name $iotHubName \
  --container $containerName \
  --resource-group $resourceGroup \
  --encoding avro

A continuación se crea la ruta para el punto de conexión de almacenamiento. La ruta de mensajes designa dónde enviar los mensajes que cumplan la especificación de consulta.

# Create the route for the storage endpoint.
az iot hub route create \
  --name $routeName \
  --hub-name $iotHubName \
  --source devicemessages \
  --resource-group $resourceGroup \
  --endpoint-name $endpointName \
  --enabled \
  --condition $condition

Ruta a una cola de Service Bus

Ahora, configure el enrutamiento de la cola de Service Bus. Para recuperar la cadena de conexión para la cola de Service Bus, debe crear una regla de autorización con los derechos correctos definidos. El siguiente script crea una regla de autorización para la cola de Service Bus llamada sbauthrule y establece los derechos en Listen Manage Send. Una vez definida esta regla de autorización, podrá usarla para recuperar la cadena de conexión para la cola.

# Create the authorization rule for the Service Bus queue.
az servicebus queue authorization-rule create \
  --name "sbauthrule" \
  --namespace-name $sbNamespace \
  --queue-name $sbQueueName \
  --resource-group $resourceGroup \
  --rights Listen Manage Send \
  --subscription $subscriptionID

Ahora, use la regla de autorización para recuperar la cadena de conexión a la cola de Service Bus.

# Get the Service Bus queue connection string.
# The "-o tsv" ensures it is returned without the default double-quotes.
sbqConnectionString=$(az servicebus queue authorization-rule keys list \
  --name "sbauthrule" \
  --namespace-name $sbNamespace \
  --queue-name $sbQueueName \
  --resource-group $resourceGroup \
  --subscription $subscriptionID \
  --query primaryConnectionString -o tsv)

# Show the Service Bus queue connection string.
echo "service bus queue connection string = " $sbqConnectionString

Ahora, configure el punto de conexión de enrutamiento y la ruta de mensajes para la cola de Service Bus. Estas son las variables utilizadas por el script que se debe establecer en la sesión de Cloud Shell:

endpointName: este campo es el nombre que identifica el punto de conexión.

endpointType: este campo es el tipo de punto de conexión. Este valor debe establecerse en azurestoragecontainer, eventhub, servicebusqueue o servicebustopic. Para los fines de este tutorial, establézcalo en servicebusqueue.

routeName: este campo es el nombre de la ruta que se va a configurar.

condition: este campo es la consulta utilizada para filtrar los mensajes enviados a este punto de conexión. La condición de consulta para que los mensajes se enruten a la cola de Service Bus es level="critical".

Esta es la CLI de Azure para el punto de conexión de enrutamiento y la ruta de mensajes para la cola de Service Bus.

endpointName="ContosoSBQueueEndpoint"
endpointType="ServiceBusQueue"
routeName="ContosoSBQueueRoute"
condition='level="critical"'

# Set up the routing endpoint for the Service Bus queue.
# This uses the Service Bus queue connection string.
az iot hub routing-endpoint create \
  --connection-string $sbqConnectionString \
  --endpoint-name $endpointName \
  --endpoint-resource-group $resourceGroup \
  --endpoint-subscription-id $subscriptionID \
  --endpoint-type $endpointType \
  --hub-name $iotHubName \
  --resource-group $resourceGroup 

# Set up the message route for the Service Bus queue endpoint.
az iot hub route create --name $routeName \
  --hub-name $iotHubName \
  --source-type devicemessages \
  --resource-group $resourceGroup \
  --endpoint-name $endpointName \
  --enabled \
  --condition $condition

Visualización del enrutamiento de mensajes en el portal

Ahora que están configurados los puntos de conexión y las rutas de mensajes, puede ver su configuración en el portal. Inicie sesión en Azure Portal y vaya a Grupos de recursos. A continuación, seleccione el grupo de recursos y, luego, el centro (el nombre del centro comienza con ContosoTestHub en este tutorial). Verá el panel de IoT Hub.

En las opciones del centro de IoT, seleccione Enrutamiento de mensajes. Se muestran las rutas que ha configurado correctamente.

En la pantalla Enrutamiento de mensajes, seleccione Puntos de conexión personalizados para ver los puntos de conexión que ha definido para las rutas.

Pasos siguientes

Ahora que tiene las rutas de mensajes y los recursos configurados, pase al siguiente tutorial para aprender a enviar mensajes a IoT Hub y verlos enrutados a los distintos destinos.