Programación y difusión de trabajos (CLI de Azure)

Artículo
03/16/2023

Use Azure IoT Hub para programar y realizar el seguimiento de los trabajos que actualizan millones de dispositivos. Use los trabajos para:

Actualizar las propiedades deseadas
Actualizar etiquetas
Invocar métodos directos

Conceptualmente, un trabajo contiene una de estas acciones y realiza un seguimiento del progreso de ejecución en un conjunto de dispositivos. El conjunto de dispositivos con los que interactúa un trabajo se define mediante una consulta de dispositivo gemelo. Por ejemplo, una aplicación back-end puede usar un trabajo para invocar un método de reinicio en 10 000 dispositivos, especificado por una consulta de dispositivos gemelos y programada en el futuro. Esa aplicación puede después seguir el progreso cuando cada uno de estos dispositivos reciben y ejecutan el método de reinicio.

Más información sobre estas funcionalidades en estos artículos:

Dispositivo gemelo y propiedades: Introducción a los dispositivos gemelos y Tutorial: Uso de las propiedades deseadas para configurar dispositivos
Métodos directos: Guía para desarrolladores de IoT Hub: métodos directos

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

En este artículo se muestra cómo crear dos sesiones de la CLI de Azure:

Una sesión que crea un dispositivo simulado. El dispositivo simulado está configurado para devolver un código de estado y una carga JSON cuando se invoca cualquier método directo.
Una sesión que crea dos trabajos programados. El primer trabajo invoca un método directo y el segundo trabajo actualiza una propiedad de dispositivo gemelo deseada en el dispositivo simulado creado en la otra sesión.

Prerrequisitos

CLI de Azure. También puede ejecutar todos los comandos de este artículo mediante Azure Cloud Shell, un shell interactivo de la CLI que se ejecuta en el explorador o en una aplicación como el terminal de Windows. Si usa el Cloud Shell, no necesita instalar nada. Si prefiere usar la CLI en un entorno local, para este artículo se requiere la versión 2.36 o posterior de la CLI de Azure. Ejecute az --version para encontrar la versión. Para instalar localmente o actualizar la CLI de Azure, vea Instalación de la CLI de Azure.
Una instancia de IoT Hub en la suscripción de Azure. Si aún no tiene un centro, puede seguir los pasos descritos en Creación de un centro de IoT.
Asegúrese de que el puerto 8883 está abierto en el firewall. En el ejemplo de dispositivo de este artículo 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).

Preparar el Cloud Shell

Si desea usar Azure Cloud Shell, primero debe iniciarlo y configurarlo. Si usa la CLI localmente, vaya a la sección Preparar dos sesiones de la CLI.

Seleccione el icono Cloud Shell en el encabezado de página del Azure Portal.

Nota

Si es la primera vez que usa el Cloud Shell, le pedirá que cree el almacenamiento, que es necesario para usar el Cloud Shell. Seleccione una suscripción para crear una cuenta de almacenamiento y un recurso compartido de Microsoft Azure Files.
Use el selector de entorno en la barra de herramientas de Cloud Shell para seleccionar el entorno de la CLI preferido. En este artículo se usa el entorno de Bash. También puede usar el entorno de PowerShell.

Nota:

Algunos comandos requieren una sintaxis o formato diferentes en los entornos de Bash y PowerShell. Para obtener más información, consulte Sugerencias para usar correctamente la CLI de Azure.

Preparación de dos sesiones de la CLI

A continuación, debe preparar dos sesiones de la CLI de Azure. Si utiliza Cloud Shell, ejecutará estas sesiones en pestañas independientes de Cloud Shell. Si usa un cliente de la CLI local, ejecutará instancias independientes de la CLI. Use las sesiones independientes de la CLI para las siguientes tareas:

La primera sesión simula un dispositivo IoT que se comunica con su centro de IoT.
La segunda sesión programa trabajos para el dispositivo simulado con el centro de IoT.

Nota

CLI de Azure requiere que haya iniciado sesión en su cuenta de Azure. Si usa el Cloud Shell, iniciará sesión automáticamente en su cuenta de Azure. Si usa un cliente de la CLI local, debe iniciar sesión en cada sesión de la CLI. Todas las comunicaciones entre la sesión de Shell de CLI de Azure y el centro de IoT se autentican y cifran. Como resultado, este artículo no necesita autenticación adicional que se usaría con un dispositivo real, como una cadena de conexión. Para más información sobre la autenticación con la CLI de Azure, consulte Inicio de sesión con la CLI de Azure.

En la primera sesión de la CLI, ejecute el comando az extension add. El comando agrega la extensión de Microsoft Azure IoT para la CLI de Azure al shell de la CLI. La extensión agrega comandos específicos de IoT Hub, IoT Edge e IoT Device Provisioning Service (DPS) a la CLI de Azure. Después de instalar la extensión de Azure IOT, no es necesario volver a instalarla en ninguna sesión de Cloud Shell.
```
az extension add --name azure-iot
```
Nota

En este artículo se usa la versión más reciente de la extensión de Azure IoT, denominada azure-iot. La versión heredada se denomina azure-cli-iot-ext. Solo debe tener instalada una versión a la vez. Puede usar el comando az extension list para validar las extensiones instaladas actualmente.

Use az extension remove --name azure-cli-iot-ext para eliminar la versión heredada de la extensión.

Use az extension add --name azure-iot para agregar la nueva versión de la extensión.

Para ver las extensiones que ha instalado, use az extension list.
Abra la segunda sesión de la CLI. Si usa el Cloud Shell en un explorador, seleccione el icono Abrir nueva sesión en la barra de herramientas de la primera sesión de la CLI. Si usa la CLI localmente, abra una segunda instancia de la CLI.

Creación y simulación de un dispositivo

En esta sección, creará una identidad de dispositivo para el centro de IoT en la primera sesión de la CLI y, a continuación, simulará un dispositivo con esa identidad del dispositivo. El dispositivo simulado responde a los trabajos que programa en la segunda sesión de la CLI.

Para crear e iniciar un dispositivo simulado:

En la primera sesión de la CLI, ejecute el comando az iot hub device-identity create, reemplazando los siguientes marcadores de posición por sus valores correspondientes. Este comando crea la identidad del dispositivo para el dispositivo simulado.

{DeviceName}. Nombre del dispositivo simulado.

{HubName}. El nombre del centro de IoT.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
En la primera sesión de la CLI, ejecute el comando az iot device simulate, reemplazando los siguientes marcadores de posición por sus valores correspondientes. Este comando simula el dispositivo que creó en el paso anterior. El dispositivo simulado está configurado para devolver un código de estado y una carga cada vez que se invoca un método directo.

{DeviceName}. Nombre del dispositivo simulado.

{HubName}. El nombre del centro de IoT.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --method-response-code 201 \
                       --method-response-payload '{"result":"Direct method successful"}'
```
Sugerencia

De forma predeterminada, el comando az iot device simulate envía 100 mensajes del dispositivo a la nube con un intervalo de 3 segundos entre mensajes. La simulación finaliza después de que se hayan enviado todos los mensajes. Si desea que la simulación se ejecute más tiempo, puede usar el parámetro --msg-count para especificar más mensajes o el parámetro --msg-interval para especificar un intervalo más largo entre los mensajes. También puede volver a ejecutar el comando para reiniciar el dispositivo simulado.

Programar un trabajo para invocar un método directo

En esta sección, programará un trabajo en la segunda sesión de la CLI para invocar un método directo en el dispositivo simulado que se ejecuta en la primera sesión de la CLI.

En la primera sesión de la CLI, confirme que el dispositivo simulado se está ejecutando. Si no es así, vuelva a ejecutar el comando az iot device simulate desde Crear y simular un dispositivo.
En la primera sesión de la CLI, ejecute el comando az iot hub job create, reemplazando los siguientes marcadores de posición por sus valores correspondientes. En este ejemplo, no hay ningún método preexistente para el dispositivo. El comando programa un trabajo que llama a un nombre de método de ejemplo en el dispositivo simulado, lo que proporciona un valor NULL para la carga del método. El método proporciona un código de estado y una carga útil en su respuesta.

{HubName}. El nombre del centro de IoT.

{JobName}. Nombre del trabajo programado. Los nombres de los trabajos son únicos, por lo que elija un nombre de trabajo diferente cada vez que ejecute este comando.

{MethodName}. Nombre del método directo. El dispositivo simulado no tiene un método preexistente, por lo que puede elegir cualquier nombre que desee para este comando.

{DeviceName}. Nombre del dispositivo simulado.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleDeviceMethod \
                      --method-name {MethodName} --method-payload 'null' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Sugerencia

Al programar un comando az iot hub job create que invoca un método directo, debe especificar valores para los parámetros --method-name y --method-payload opcionales. Para los métodos directos que no aceptan una carga, especifique null para el parámetro --method-payload.
En la primera sesión de la CLI, confirme que en la salida se muestra el método de invocación. En la captura de pantalla siguiente, usamos SampleDevice y SampleMethod para los marcadores de posición {DeviceName} y {MethodName}, respectivamente, en el comando az iot hub job create de la CLI del paso anterior.

Programar un trabajo para actualizar las propiedades de un dispositivo gemelo

En esta sección, programará un trabajo en la segunda sesión de la CLI para actualizar una propiedad de dispositivo gemelo deseada en el dispositivo simulado que se ejecuta en la primera sesión de la CLI.

En la primera sesión de la CLI, confirme que el dispositivo simulado se está ejecutando. Si no es así, vuelva a ejecutar el comando az iot device simulate desde Crear y simular un dispositivo.
En la primera sesión de la CLI, ejecute el comando az iot hub job create, reemplazando los siguientes marcadores de posición por sus valores correspondientes. En este ejemplo, estamos programando un trabajo para establecer el valor de la propiedad gemela deseada BuildingNo en 45 para nuestro dispositivo simulado.

{HubName}. El nombre del centro de IoT.

{JobName}. Nombre del trabajo programado. Los nombres de los trabajos son únicos, por lo que elija un nombre de trabajo diferente cada vez que ejecute este comando.

{DeviceName}. Nombre del dispositivo simulado.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleUpdateTwin \
                      --twin-patch '{"properties":{"desired": {"BuildingNo": 45}}}' \
                      --query-condition "deviceId = '{DeviceName}'"
```
En la primera sesión de la CLI, confirme que la salida muestra la actualización correcta de la propiedad del dispositivo gemelo notificado, lo que indica que también se actualizó la propiedad del dispositivo gemelo deseado.

Pasos siguientes

En este artículo, ha usado la CLI de Azure para simular un dispositivo y programar trabajos para ejecutar un método directo y actualizar las propiedades del dispositivo gemelo para ese dispositivo simulado.

Para continuar explorando el centro de IoT y los patrones de administración de dispositivos, actualice una imagen en el Tutorial de Actualización de Dispositivos para Azure IoT Hub mediante la Imagen de Referencia de Raspberry Pi 3 B+.

Compartir vía