Creación y eliminación de rutas y puntos de conexión mediante la CLI de Azure

En este artículo, se explica cómo se administran las rutas y los puntos de conexión de Azure IoT Hub con la CLI de Azure. Aprenda a usar la CLI de Azure para crear rutas y puntos de conexión en Azure Event Hubs, las colas y los temas de Azure Service Bus, Azure Storage y Cosmos DB.

Para más información sobre cómo funciona el enrutamiento en IoT Hub, consulte Uso del enrutamiento de mensajes de IoT Hub para enviar mensajes del dispositivo a la nube a distintos puntos de conexión. Para obtener información sobre la configuración de una ruta que envíe mensajes al almacenamiento y la posterior realización de pruebas en un dispositivo simulado, consulte Tutorial: Envío de datos de dispositivo a Azure Storage mediante el enrutamiento de mensajes de IoT Hub.

Requisitos previos

Los procedimientos que se describen en el artículo usan los siguientes recursos:

• La CLI de Azure
• Una instancia de IoT Hub
• Un servicio de punto de conexión en Azure

Azure CLI

En este artículo se usa la interfaz de la CLI de Azure para trabajar con IoT Hub y otros servicios de Azure. Puede elegir cómo acceder a la 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.

IoT Hub

Necesita un centro de IoT en la suscripción de Azure. Si aún no tiene ningún centro, puede seguir los pasos necesarios para crear un centro de IoT mediante la CLI de Azure.

Servicio de punto de conexión

También necesita al menos otro servicio de Azure para usarlo como punto de conexión de la ruta. El punto de conexión recibe tanto los mensajes como los registros de eventos del dispositivo.

Decida qué servicio de Azure desea usar como punto de conexión para recibir datos de los eventos y los dispositivos enrutados: un centro de eventos, un tema o una cola de servicio, una cuenta de almacenamiento o un contenedor de Cosmos DB. En el servicio que elija usar, complete los pasos para crear un servicio de punto de conexión.

Event Hubs

1. Cree un espacio de nombres de Event Hubs y un centro de eventos. Para más información, consulte Inicio rápido: Creación de un centro de eventos mediante la CLI de Azure.

2. Cree una regla de autorización. Esta regla se utilizará para conceder permiso a IoT Hub para enviar datos al centro de eventos.

   Sugerencia

   El name valor RootManageSharedAccessKey del parámetro es el nombre predeterminado que permite administrar, enviar y escuchar notificaciones (acceso). Si desea restringir las notificaciones, asigne al parámetro name su nombre único e incluya la marca --rights, seguida de una de las notificaciones. Por ejemplo, --name my-name --rights Send.

   az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey
   

   Para más información, consulte Autorización del acceso a Azure Event Hubs.

Cola de Service Bus

1. Cree un espacio de nombres de Service Bus y una cola. Para más información, consulte Uso de la CLI de Azure para crear espacios de nombres y colas de Service Bus.

2. Cree una regla de autorización que proporcione permiso a IoT Hub para enviar datos a la cola. En name, use un valor único para la regla de autorización.

   az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
   

   Para más opciones de la regla de autorización, consulte az servicebus queue authorization-rule create.

Tema de Service Bus

Cree un espacio de nombres, un tema y una suscripción en Service Bus. Para más información, consulte Uso de la CLI de Azure para crear un tema de Service Bus y suscripciones a dicho tema.

Almacenamiento de Azure

1. Cree una cuenta de almacenamiento. Para obtener más información, consulte Creación de una cuenta de almacenamiento.

2. Cree un contenedor en la cuenta de almacenamiento. Para más información, consulte Administración de contenedores de blobs con la CLI de Azure.

Cosmos DB

Cree una cuenta de Cosmos DB para la API de SQL y un contenedor de Cosmos DB. Para más información, consulte Creación una cuenta de Azure Cosmos DB for NoSQL.

Crear un punto de conexión

Todas las rutas IoT Hub apuntan a un punto de conexión, que recibirá los datos de los eventos y los dispositivos enrutados. Puede haber varias rutas que apunten al mismo punto de conexión. Actualmente, IoT Hub admite puntos de conexión de Event Hubs, de las colas o temas de Service Bus, de Storage y de Cosmos DB. Para poder crear el punto de conexión, debe haber una instancia del servicio en la suscripción de Azure que se use como punto de conexión.

Nota

En este artículo, se usa el grupo de comandos az iot hub message-endpoint, que se introdujo en la versión 0.19.0 de la extensión azure-iot de la CLI de Azure. Las versiones anteriores de la extensión azure-iot usaban el grupo de comandos az iot hub routing-endpoint, que es similar y sigue siendo compatible, pero no permite crear puntos de conexión de Cosmos DB.

Use el siguiente comando para actualizar a la versión más reciente de la extensión azure-iot:

az extension update --name azure-iot

Event Hubs

Para crear un punto de conexión de Event Hubs, use la regla de autorización que creó en los requisitos previos.

1. Use el comando az eventhubs eventhub authorization-rule keys list para mostrar la regla de autorización. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   eventhub_group	Grupo de recursos del centro de eventos.
   eventhub_namespace	Nombre del espacio de nombres de Event Hubs.
   eventhub_name	Nombre del centro de eventos.
   rule_name	Nombre de la regla de autorización del centro de eventos. Si copió el ejemplo de los requisitos previos, el nombre será RootManageSharedAccessKey.

   az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}
   

2. Copie la cadena de conexión del centro de eventos de la salida.

3. Use el comando az iot hub message-endpoint create eventhub para crear un punto de conexión personalizado. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   iothub_name	Nombre del centro de IoT en el que se está creando el punto de conexión.
   endpoint_name	Nombre único del punto de conexión.
   eventhub_subscription	Identificador de la suscripción del centro de eventos. Este argumento se puede omitir si el centro de eventos está en la misma suscripción que el centro de IoT.
   eventhub_group	Grupo de recursos del centro de eventos. Este argumento se puede omitir si el centro de eventos está en el mismo grupo de recursos que el centro de IoT.
   eventhub_connection_string	Cadena de conexión que se copió de la regla de autorización del centro de eventos.

   az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}
   

Cola de Service Bus

Para crear un punto de conexión de una cola de Service Bus, use la regla de autorización que creó en los requisitos previos.

1. Use el comando az servicebus queue authorization-rule keys list para obtener la cadena de conexión de la cola de Service Bus. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   queue_group	Grupo de recursos de la cola de Service Bus.
   queue_namespace	Nombre del espacio de nombres de la cola de Service Bus.
   queue_name	Nombre de la cola.
   rule_name	Nombre de la regla de autorización de la cola. Si copió el ejemplo de los requisitos previos, el nombre será my-auth-rule.

   az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}
   

2. Copie la cadena de conexión de la cola de Service Bus de la salida.

3. Use el comando az iot hub message-endpoint create servicebus-queue para crear un punto de conexión personalizado. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   iothub_name	Nombre del centro de IoT en el que se está creando el punto de conexión.
   endpoint_name	Nombre único del punto de conexión.
   queue_connection_string	Cadena de conexión que copió de la regla de autorización de la cola de Service Bus.
   queue_subscription	Identificador de la suscripción de la cola de Service Bus. Este argumento se puede omitir si la cola está en la misma suscripción que el centro de IoT.
   queue_group	Grupo de recursos de la cola de Service Bus. Este argumento se puede omitir si la cola está en el mismo grupo de recursos que el centro de IoT.

   az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}
   

Tema de Service Bus

1. Utilice el comando az servicebus topic authorization-rule keys list para obtener la cadena de conexión de un tema de Service Bus. El nombre predeterminado de la regla de autorización que viene con un nuevo espacio de nombres es RootManageSharedAccessKey. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   topic_group	Grupo de recursos del tema de Service Bus.
   topic_namespace	Nombre del espacio de nombres del tema de Service Bus.
   topic_name	Nombre del tema.

   az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
   

2. Copie la cadena de conexión del tema de Service Bus de la salida.

3. Use el comando az iot hub message-endpoint create servicebus-topic para crear el punto de conexión personalizado. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   iothub_name	Nombre del centro de IoT en el que se está creando el punto de conexión.
   endpoint_name	Nombre único del punto de conexión.
   topic_connection_string	Cadena de conexión que copió de la regla de autorización del tema de Service Bus.
   topic_subscription	Identificador de la suscripción del tema de Service Bus. Este argumento se puede omitir si el tema está en la misma suscripción que el centro de IoT.
   topic_group	Grupo de recursos del tema de Service Bus. Este argumento se puede omitir si la cola está en el mismo grupo de recursos que el centro de IoT.

   az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}
   

Almacenamiento de Azure

1. Use el comando az storage account show-connection-string para obtener la cadena de conexión del recurso de Azure Storage con la que va a crear un punto de conexión. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   storage_group	Grupo de recursos de la cuenta de almacenamiento.
   storage_name	Nombre de la cuenta de almacenamiento.

   az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
   

2. Copie la cadena de conexión de la cuenta de almacenamiento de la salida.

3. Use el comando az iot hub message-endpoint create storage-container para crear un nuevo punto de conexión de Azure Storage. Para todos los demás parámetros, use los valores de su escenario. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   iothub_name	Nombre del centro de IoT en el que se está creando el punto de conexión.
   endpoint_name	Nombre único del punto de conexión.
   storage_connection_string	Cadena de conexión que copió del comando de la cuenta de almacenamiento.
   container_name	Nombre del contenedor de la cuenta de almacenamiento donde se van a enviar los datos.
   storage_subscription	Identificador de la suscripción del almacenamiento de Service Bus. Este argumento se puede omitir si el almacenamiento está en la misma suscripción que el centro de IoT.
   storage_group	Grupo de recursos del almacenamiento de Service Bus. Este argumento se puede omitir si la cola está en el mismo grupo de recursos que el centro de IoT.

   az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}
   

Cosmos DB

1. Use el comando az cosmosdb keys list para obtener la cadena de conexión de la cuenta de base de datos de Cosmos DB.

   az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings
   

2. Copie la cadena de conexión de Cosmos DB de la salida.

3. Utilice el comando az iot hub message-endpoint create cosmosdb-container para crear el punto de conexión personalizado. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   iothub_name	Nombre del centro de IoT en el que se está creando el punto de conexión.
   endpoint_name	Nombre único del punto de conexión.
   cosmosdb_connection_string	Cadena de conexión que copió del comando de la cuenta de Cosmos DB.
   container_name	Nombre del contenedor de la cuenta de Cosmos DB donde se van a enviar los datos.
   database_name	Nombre de la base de datos de la cuenta de Cosmos DB donde se van a enviar los datos.
   cosmosdb_subscription	Identificador de la suscripción de la cuenta de base de datos de Cosmos DB. Este argumento se puede omitir si la base de datos está en la misma suscripción que el centro de IoT.
   cosmosdb_group	Grupo de recursos de la cuenta de base de datos de Cosmos DB. Este argumento se puede omitir si la base de datos está en el mismo grupo de recursos que el centro de IoT.

   az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container
   

   Nota

   Si usa identidades administradas en lugar de una cadena de conexión, utilice el comando az cosmosdb sql role assignment create para autenticar la identidad en la cuenta de Cosmos DB.

   az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"
   

Eliminar un extremo

Si desea eliminar un punto de conexión del centro de IoT, use el comando az iot hub message-endpoint delete. Con este comando, puede eliminar un único punto de conexión, todos los puntos de conexión de un mismo tipo o todos los puntos de conexión de un centro.

Por ejemplo, el siguiente comando elimina todos los puntos de conexión de un centro de IoT que apuntan a recursos de almacenamiento:

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

Creación de una ruta de IoT Hub

En IoT Hub, puede crear una ruta para enviar mensajes o capturar eventos. Cada ruta tiene un origen de datos y un punto de conexión. El origen de datos es el lugar del que parten los mensajes o los registros de eventos. El punto de conexión es el lugar en que terminan los mensajes o los registros de eventos. Cuando se crea una ruta en el centro de IoT, se eligen las ubicaciones del origen de datos y del punto de conexión. Opcionalmente, puede agregar consultas a las rutas de mensajes para filtrar mensajes o eventos antes de ir al punto de conexión.

Nota

En este artículo, se utiliza el grupo de comandos az iot hub message-route, que se introdujo en la versión 0.19.0 de la extensión azure-iot de la CLI de Azure. Las versiones anteriores de la extensión azure-iot usaban el grupo de comandos az iot hub route, que es similar y todavía se admite.

Use el siguiente comando para actualizar a la versión más reciente de la extensión azure-iot:

az extension update --name azure-iot

1. Use el comando az iot hub message-route create para crear una nueva ruta de IoT Hub mediante ese punto de conexión. Proporcione los siguientes valores para los parámetros de marcador de posición:

   parámetro	value
   iothub_name	Nombre del centro de IoT donde se está creando la ruta.
   route_name	Nombre único de la nueva ruta.
   endpoint_name	Nombre del punto de conexión al que la ruta enviará datos.
   data_source	Origen de la ruta. Los valores aceptados son: deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, invalid o twinchangeevents.

   az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
   

2. Si desea confirmar que la nueva ruta esté en el centro de IoT, use el comando az iot hub message-route list para ver todas las rutas del centro de IoT:

   az iot hub message-route list --hub-name {iothub_name}
   

   En la CLI de Azure debería ver una respuesta similar a la de este ejemplo:

   [
      {
        "condition": "true",
        "endpointNames": [
          "endpoint_name"
        ],
        "isEnabled": true,
        "name": "route_name",
        "source": "DeviceConnectionStateEvents"
      }
   ]
   

Actualización de una ruta de IoT Hub

Puede actualizar algunas propiedades de las rutas después de crearlas. Puede cambiar el origen, el punto de conexión, la condición o el estado habilitado de una ruta existente.

Utilice el comando az iot hub message-route show para ver los detalles de una ruta.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

Utilice el comando az iot hub message-route update para actualizar las propiedades de una ruta. Por ejemplo, el siguiente comando actualiza el origen de la ruta.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

Eliminación de una ruta de IoT Hub

Utilice el comando az iot hub message-route delete para eliminar una ruta del centro de IoT.

Al eliminar una ruta, no se elimina el punto de conexión, ya que puede haber otras rutas que apunten al mismo punto de conexión. Si desea eliminar un punto de conexión, puede hacerlo de forma independiente, sin eliminar ninguna ruta.

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

Administración de la ruta de reserva

La ruta de reserva envía al punto de conexión integrado todos los mensajes del origen devicemessages que no cumplen las condiciones de consulta de ninguna de las rutas existentes.

Utilice el comando az iot hub message-route fallback show para ver el estado de la ruta de reserva del centro de IoT.

az iot hub message-route fallback show --hub-name {iothub_name}

Utilice el comando az iot hub message-route fallback set para habilitar o deshabilitar la ruta de reserva del centro de IoT.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

Pasos siguientes

En este artículo de procedimientos ha aprendido a crear una ruta y un punto de conexión para Event Hubs, colas o temas de Service Bus y Azure Storage.

Para más información sobre el enrutamiento de mensajes, consulte Tutorial: Envío de datos de dispositivo a Azure Storage mediante el enrutamiento de mensajes de IoT Hub. En este tutorial, se crea una ruta de almacenamiento y se prueba con un dispositivo de un centro de IoT.