Creación y eliminación de rutas y puntos de conexión mediante Azure Resource Manager
En este artículo se muestra cómo exportar una plantilla de Azure IoT Hub, agregar una ruta a un centro de IoT y, después, volver a implementar la plantilla al centro de IoT mediante la CLI de Azure o Azure PowerShell. Use una plantilla de Azure Resource Manager para crear rutas y puntos de conexión. IoT Hub admite los siguientes servicios de Azure como puntos de conexión:
- Contenedores de almacenamiento
- Event Hubs
- Colas de Service Bus
- Temas de Service Bus
- Cosmos DB
Las plantillas de Azure Resource Manager son útiles cuando se desea definir recursos mediante un archivo JSON. Cada recurso de Azure tiene una plantilla que define los componentes que se usan en él. Puede exportar todas las plantillas de recursos de Azure.
Importante
Cuando se usa una plantilla de Resource Manager para implementar un recurso, esta reemplaza a cualquier recurso existente del tipo que va a implementar.
Cuando se crea un centro de IoT, la sobrescritura de un recurso implementado existente no supone ningún problema. Para crear un centro de IoT, puede usar una plantilla básica que tenga las propiedades necesarias, en lugar de exportar una plantilla existente desde un centro de IoT ya implementado.
Pero si agrega una ruta a un centro de IoT existente, use una plantilla que exporte desde el centro de IoT para asegurarse de que todos los recursos y propiedades existentes permanezcan conectados después de implementar la plantilla actualizada. Los recursos que ya estén implementados no se reemplazarán. Por ejemplo, una plantilla de Resource Manager exportada implementada con anterioridad puede contener información de almacenamiento de un centro de IoT, siempre que lo haya conectado al almacenamiento.
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 conocer los pasos que deben realizarse para configurar una ruta que envíe mensajes al almacenamiento y, posteriormente, realizar 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
Revise los requisitos previos de este artículo en función del tipo de punto de conexión al que quiera enrutar los mensajes.
Suscripción a Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita de Azure antes de empezar.
Una instancia de IoT Hub. Si aún no tiene un centro, puede seguir los pasos para crear un centro de IoT.
Un recurso de Event Hubs (con contenedor). Si necesita crear un recurso de Event Hubs, consulte Inicio rápido: Creación de un centro de eventos mediante una plantilla de Resource Manager.
(Recomendado) Una identidad administrada con permisos de control de acceso basado en rol para el espacio de nombres de Event Hubs. Para más información, vea Autenticación de una identidad administrada con Microsoft Entra ID para acceder a recursos de Event Hubs.
Plantilla del Administrador de recursos de Azure
En este artículo se usa una plantilla de Azure Resource Manager en Azure Portal para trabajar con IoT Hub y otros servicios de Azure. Para más información sobre cómo usar plantillas de Resource Manager, consulte ¿Qué son las plantillas de Azure Resource Manager?
Creación de una ruta
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. Luego, se usan consultas de enrutamiento para filtrar los mensajes o eventos antes de que van al punto de conexión.
Puede usar un centro de eventos, una cola o un tema de Service Bus o una cuenta de Azure Storage como punto de conexión de la ruta del centro de IoT. El servicio que use para crear el punto de conexión debe existir en la cuenta de Azure.
Exportación de la plantilla de Resource Manager del centro de IoT
En primer lugar, exporte una plantilla de Resource Manager desde el centro de IoT. Al exportar la plantilla desde el centro de IoT, puede agregar recursos de punto de conexión y ruta, y repetir la implementación sin perder la configuración existente.
En Azure Portal, vaya hasta su instancia de IoT Hub. En el menú de recursos, en Automatización, seleccione Exportar plantilla.
En Exportar plantilla, en la pestaña Plantilla, siga estos pasos:
Vea el archivo JSON que se genera para el centro de IoT.
Desactive la casilla Incluir parámetros.
Seleccione Descargar para descargar una copia local del archivo JSON.
La plantilla tiene varios marcadores de posición que se pueden usar para agregar características o servicios a cualquier centro de IoT. Para este artículo, agregue valores solo a las propiedades que están en
routing
o anidadas a él.
Adición de un punto de conexión a la plantilla
Cada ruta apunta a un punto de conexión, que es donde terminan los mensajes o registros de eventos. Cree un punto de conexión en el centro de IoT al que pueda hacer referencia la ruta. Puede usar un centro de eventos, una cola o un tema de Service Bus, una cuenta de almacenamiento de Azure o un contenedor de Azure Cosmos DB para que sea el punto de conexión de la ruta del centro de IoT. El servicio que use para crear el punto de conexión debe existir en la cuenta de Azure.
El centro de IoT necesita permisos de acceso para cualquier recurso de punto de conexión al que envíe mensajes o registros. Puede proporcionar acceso mediante identidades administradas y Microsoft Entra ID, o bien mediante cadenas de conexión. Microsoft recomienda autenticarse con Entra ID como la opción más segura.
Agregue un punto de conexión de Event Hubs a la plantilla de Resource Manager. Para más información, vea Plantilla RoutingEventHubProperties de Azure Resource Manager.
En el archivo JSON, busque la propiedad
"endpoints": []
anidada en"routing"
.Reemplace la línea
"endpoints": []
por el código JSON siguiente:"endpoints": { "serviceBusQueues": [], "serviceBusTopics": [], "eventHubs": [ { "endpointUri": "", "entityPath": "", "authenticationType": "identityBased", "identity": { "userAssignedIdentity": "" }, "name": "", "id": "", "subscriptionId": "", "resourceGroup": "" } ], "storageContainers": [], "cosmosDBSqlContainers": [] },
Actualice el código JSON con la siguiente información sobre el recurso de Event Hubs:
Propiedad Valor endpointUri (Si el tipo de autenticación es identityBased
; de lo contrario, elimine). Nombre de host del espacio de nombres de Event Hubs en el formatosb://<eventhubs_namespace_name>.servicebus.windows.net
entityPath (Si el tipo de autenticación es identityBased
; de lo contrario, elimine). El nombre del centro de eventos.authenticationType identityBased
okeyBased
. Microsoft recomienda la autenticación basada en identidades como la opción más segura.identity (Si el tipo de autenticación es identityBased
). Puede usar una identidad administrada asignada por el usuario o una identidad administrada asignada por el sistema si la instancia de IoT Hub tiene habilitada la identidad administrada asignada por el sistema.
Para identidades asignadas por el usuario: el identificador externo de la identidad administrada con permisos de acceso al centro de eventos con el formato/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>
.
Para identidades asignadas por el sistema: deje el parámetro identity como una lista vacía. Por ejemplo:"identity": {},
connectionString (Si el tipo de autenticación es keyBased
). La cadena de conexión principal de una de las directivas de acceso compartido del centro de eventos con el formato<connection_string>;EntityPath=<event_hub_name>.
Puede recuperar el valor de la cadena de conexión desde Azure Portal y, después, anexar la ruta de acceso de la entidad.nombre Proporcione un valor único para asignar un nombre al punto de conexión. id Déjelo como una cadena vacía. El servicio de Azure proporciona un valor al crear el punto de conexión. subscriptionId Id. de la suscripción que contiene el centro de eventos. resourceGroup Nombre del grupo de recursos que contiene el centro de eventos. Sugerencia
Para la administración de secretos, puede crear un archivo de parámetros o usar Azure Key Vault para pasar valores de parámetros seguros durante la implementación.
Adición de una ruta a la plantilla
Agregue una definición de ruta a la plantilla de Resource Manager. Para más información, vea Plantilla RouteProperties de Azure Resource Manager.
En el archivo JSON, busque la propiedad
"routes": []
anidada en"routing"
y agregue una ruta nueva.Precaución
Si reemplaza los valores existentes de
"routes"
por los valores de ruta que se usan en los ejemplos de código siguientes, las rutas existentes se quitan al realizar la implementación. Para conservar las rutas existentes, agregue el nuevo objeto ruta a la lista"routes"
."routes": [ { "name": "", "source": "DeviceConnectionStateEvents", "condition": "true", "endpointNames": [ "" ], "isEnabled": true } ],
Actualice el código JSON con la siguiente información sobre el recurso de Cosmos DB:
Propiedad Valor nombre Proporcione un valor único para asignar un nombre a la ruta. origen Seleccione el origen del mensaje o de los registros de eventos que se van a enrutar al punto de conexión. Para obtener una lista de opciones de origen, vea az iot hub route. condition Consulta para filtrar los datos de origen. Si no se necesita ninguna condición, por ejemplo, true
. Para más información, consulte Sintaxis de las consultas de enrutamiento de mensajes de IoT Hub.endpointNames Nombre del punto de conexión existente donde se enrutarán estos datos. Actualmente solo se permite un punto de conexión. isEnabled Establezca en true
para habilitar la ruta, o bien enfalse
para deshabilitarla.Guarde el archivo JSON.
Implementación de la plantilla de Resource Manager
Con el nuevo punto de conexión y la ruta agregados a la plantilla de Resource Manager, ahora puede volver a implementar el archivo JSON en el centro de IoT.
Implementación local
az deployment group create \
--name my-iot-hub-template \
--resource-group my-resource-group \
--template-file "my\path\to\template.json"
Implementación de Azure Cloud Shell
Dado que Azure Cloud Shell se ejecuta en un explorador web, se puede cargar el archivo de plantilla antes de ejecutar el comando de implementación. Con el archivo cargado, solo se necesita el nombre del archivo de plantilla (en lugar de la ruta de acceso completa) que se va a usar en el parámetro template-file
.
az deployment group create \
--name my-iot-hub-template \
--resource-group my-resource-group \
--template-file "template.json"
Nota
Si se produjo un error en la implementación, use el modificador -verbose
para obtener información sobre los recursos que se están creando. Utilice el modificador -debug
para más información sobre la depuración.
Confirmación de la implementación
Para confirmar que la plantilla se implementó correctamente en Azure, en Azure Portal, vaya al recurso del grupo de recursos. En el menú de recursos de Configuración, seleccione Implementaciones para ver la plantilla en una lista de las implementaciones.
Para ver la nueva ruta en Azure Portal, vaya al recurso de IoT Hub. En el panel Enrutamiento de mensajes, en la pestaña Rutas, confirme que aparece la ruta.
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.