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 para Azure Event Hubs, colas y temas de Azure Service Bus y Azure Storage.

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.

Sin embargo, si agrega una ruta a una plantilla existente de Resource Manager para centros de IoT, 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

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

• Una plantilla de Azure Resource Manager
• Una instancia de IoT Hub
• Un servicio de punto de conexión en Azure

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?

centro de IoT

Para crear una ruta de un centro de IoT, se necesita el centro de IoT que se creó mediante Azure IoT Hub. Tanto los mensajes como los registros de eventos del dispositivo parten del centro de IoT.

Asegúrese de tener el siguiente recurso de centro para que pueda usarlo al crear la ruta del centro de IoT:

• Un centro de IoT en la suscripción de Azure. Si aún no tiene ningún centro, siga los pasos necesarios para crear un centro de IoT mediante una plantilla de Azure Resource Manager (PowerShell).

Servicio de punto de conexión

Para crear una ruta de un centro de IoT, se necesita al menos otro servicio de Azure, con el fin de usarlo como punto de conexión a la ruta. El punto de conexión recibe tanto los mensajes como los registros de eventos del dispositivo. Puede elegir qué servicio de Azure usa para que cada punto de conexión se conecte a la ruta del centro de IoT: Event Hubs, colas o temas de Service Bus o Azure Storage.

Asegúrese de tener uno de los siguientes recursos para usarlo al crear un punto de conexión en la ruta del 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.

• Un recurso de cola de Service Bus. Si necesita crear una cola de Service Bus, consulte Inicio rápido: Creación de un espacio de nombres y una cola de Service Bus mediante una plantilla de Resource Manager.

• Un recurso de tema de Service Bus. Si necesita crear un tema de Service Bus, consulte Inicio rápido: Creación de un espacio de nombres de Service Bus con un tema y una suscripción mediante una plantilla de Resource Manager.

• Un recurso de Azure Storage. Si necesita crear una instancia de Azure Storage, consulte Creación de una cuenta de almacenamiento.

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 desde un centro de IoT

En primer lugar, exporte una plantilla de Resource Manager desde un centro de IoT y, después, agréguele una ruta.

1. En Azure Portal, vaya hasta su instancia de IoT Hub. En el menú de recursos, en Automatización, seleccione Exportar plantilla.

   

2. En Exportar plantilla, en la pestaña Plantilla, siga estos pasos:

   1. Vea el archivo JSON que se genera para el centro de IoT.

   2. Desactive la casilla Incluir parámetros.

   3. 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 nuevo punto de conexión a la plantilla de Resource Manager

En el archivo JSON, busque la propiedad "endpoints": [] anidada en "routing". Complete los pasos necesarios para agregar un nuevo punto de conexión basado en el servicio de Azure que elija para el punto de conexión: Event Hubs, colas o temas de Service Bus o Azure Storage.

Event Hubs

Para aprender a crear un recurso de Event Hubs (con contenedor), consulte Inicio rápido: Creación de un centro de eventos mediante una plantilla de Resource Manager.

En Azure Portal, obtenga la cadena de conexión principal del recurso de Event Hubs. En el panel Directivas de acceso compartido del recurso, seleccione una de las directivas para ver la clave y la información de la cadena de conexión. Agregue el nombre del centro de eventos a la ruta de acceso de la entidad al final de la cadena de conexión. Por ejemplo, use ;EntityPath=my-event-hubs. Este es el nombre del centro de eventos, no el nombre del espacio de nombres.

En el caso de name, use un valor único para el punto de conexión de Event Hubs. Deje el parámetro id como una cadena vacía. El servicio de Azure proporciona un valor id al implementar el punto de conexión.

"routing": {
   "endpoints": {
      "serviceBusQueues": [],
      "serviceBusTopics": [],
      "eventHubs": [
            {
               "connectionString": "my Event Hubs connection string + entity path",
               "authenticationType": "keyBased",
               "name": "my-event-hubs-endpoint",
               "id": "",
               "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
               "resourceGroup": "my-resource-group"
            }
      ],
      "storageContainers": [],
      "cosmosDBSqlCollections": []
   },
},

Cola de Service Bus

Para aprender a crear un recurso cola de Service Bus (un espacio de nombres y una cola), consulte Inicio rápido: Creación de un espacio de nombres y una cola de Service Bus mediante una plantilla de Resource Manager.

En Azure Portal, obtenga la cadena de conexión principal del recurso de Service Bus. En el panel Directivas de acceso compartido del recurso, seleccione una de las directivas para ver la clave y la información de la cadena de conexión. Agregue el nombre del centro de eventos a la ruta de acceso de la entidad al final de la cadena de conexión. Por ejemplo, use ;EntityPath=my-service-bus-queue. Este es el nombre de la cola, no el nombre del espacio de nombres.

En el caso de name, use un valor único para el punto de conexión de la cola de Service Bus. Deje el parámetro id como una cadena vacía. El servicio de Azure proporciona un valor id al implementar el punto de conexión.

"routing": {
   "endpoints": {
      "serviceBusQueues": [
            {
               "connectionString": "my Service Bus connection string + entity path",
               "authenticationType": "keyBased",
               "name": "my-service-bus-queue-endpoint",
               "id": "",
               "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
               "resourceGroup": "my-resource-group"
            }
      ],
      "serviceBusTopics": [],
      "eventHubs": [],
      "storageContainers": [],
      "cosmosDBSqlCollections": []
   },
},

Tema de Service Bus

Si necesita crear un recurso tema de Service Bus (un espacio de nombres, un tema y una suscripción), consulte Inicio rápido: Creación de un espacio de nombres y un tema de Service Bus mediante una plantilla de Resource Manager.

En Azure Portal, obtenga la cadena de conexión principal del recurso de Service Bus. En el panel Directivas de acceso compartido del recurso, seleccione una de las directivas para ver la clave y la información de la cadena de conexión. Agregue el nombre del centro de eventos a la ruta de acceso de la entidad al final de la cadena de conexión. Por ejemplo, use ;EntityPath=my-service-bus-topic. Este es el nombre del tema, no el nombre del espacio de nombres.

En el caso de name, especifique un nombre único para el punto de conexión. Deje el parámetro id como una cadena vacía. El servicio de Azure proporciona un valor id al implementar el punto de conexión.

"routing": {
   "endpoints": {
      "serviceBusQueues": [],
      "serviceBusTopics": [
         {
            "connectionString": "my Service Bus connection string + entity path",
            "authenticationType": "keyBased",
            "name": "my-service-bus-topic-endpoint",
            "id": "",
            "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "resourceGroup": "my-resource-group"
         }
      ],
      "eventHubs": [],
      "storageContainers": [],
      "cosmosDBSqlCollections": []
   },
},

Almacenamiento de Azure

Para aprender a crear un recurso de Azure Storage (un espacio de nombres, un tema y una suscripción), consulte Creación de una cuenta de almacenamiento.

En Azure Portal, obtenga la cadena de conexión principal del recurso de Azure Storage en el panel Claves de acceso del recurso.

En el caso de name, especifique un nombre único para el punto de conexión. Deje el parámetro id como una cadena vacía. El servicio de Azure proporciona un valor id al implementar el punto de conexión.

"routing": {
   "endpoints": {
      "serviceBusQueues": [],
      "serviceBusTopics": [],
      "eventHubs": [],
      "storageContainers": [
         {
            "connectionString": "my Azure storage connection string",
            "containerName": "my-container",
            "fileNameFormat": "{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}.avro",
            "batchFrequencyInSeconds": 100,
            "maxChunkSizeInBytes": 104857600,
            "encoding": "avro",
            "authenticationType": "keyBased",
            "name": "my-storage-endpoint",
            "id": "",
            "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "resourceGroup": "my-resource-group"
         }
      ],
      "cosmosDBSqlCollections": []
   },
},

Adición de una ruta nueva a una plantilla de Resource Manager

En el archivo JSON, busque la propiedad "routes": [], anidada en "routing", y agregue la siguiente ruta nueva, según el servicio de punto de conexión que se elija (Event Hubs, cola o tema de Service Bus, o Azure Storage).

La ruta de reserva predeterminada recopila mensajes de DeviceMessages. Elija otra opción, como DeviceConnectionStateEvents. Para más información acerca de las opciones de origen, consulte az iot hub route.

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

Para más información sobre la plantilla, consulte Definición del recurso plantilla de Azure Resource Manager.

Event Hubs

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-event-hubs-endpoint"
        ],
        "isEnabled": true
    }
],

Guarde el archivo JSON.

Cola de Service Bus

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-service-bus-queue-endpoint"
        ],
        "isEnabled": true
    }
],

Guarde el archivo JSON.

Tema de Service Bus

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-service-bus-topic-endpoint"
        ],
        "isEnabled": true
    }
],

Guarde el archivo JSON.

Almacenamiento de Azure

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-storage-endpoint"
        ],
        "isEnabled": true
    }
],

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

CLI de Azure

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "my\path\to\template.json"

PowerShell

New-AzResourceGroupDeployment `
  -Name MyTemplate `
  -ResourceGroupName MyResourceGroup `
  -TemplateFile "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.

CLI de Azure

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "template.json"

PowerShell

New-AzResourceGroupDeployment `
  -Name MyIoTHubTemplate `
  -ResourceGroupName MyResourceGroup `
  -TemplateFile "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.