Administrar grupos de dispositivos para Azure Device Update for IoT Hub

Azure Device Update for IoT Hub permite implementar actualizaciones en grupos definidos por el usuario de dispositivos IoT. Cada dispositivo administrado de Device Update es miembro de un grupo de dispositivos, pero definir grupos de dispositivos es opcional. También puede implementar en el grupo de dispositivos predeterminado que proporciona Device Update.

Si crea y asigna valores de etiqueta de Device Update definidos por el usuario a los dispositivos, Device Update crea automáticamente grupos en función de las etiquetas asignadas y las propiedades de compatibilidad de dispositivos. Para cada grupo de dispositivos, Device Update puede crear varios subgrupos que tengan clases de dispositivo diferentes. Device Update coloca los dispositivos que no tienen etiquetas en el grupo de dispositivos default.

En este artículo se describe cómo usar Azure Portal o la CLI de Azure para crear y administrar etiquetas y grupos de dispositivos de Device Update definidos por el usuario. Para implementar actualizaciones en grupos de dispositivos predeterminados o definidos por el usuario, consulte Implementación de una actualización de dispositivo.

Requisitos previos

Azure Portal

• Una instancia estándar (S1) o superior de Azure IoT Hub con Device Update for IoT Hub habilitado.
• Un dispositivo o simulador de IoT Aprovisionado para Device Update dentro del centro de IoT.
• El agente de Device Update instalado e iniciado en el dispositivo IoT como una identidad de nivel de dispositivo o de módulo.
• Una actualización importada del dispositivo aprovisionado.

CLI de Azure

• Una instancia estándar (S1) o superior de Azure IoT Hub con Device Update for IoT Hub habilitado.

• Un dispositivo o simulador de IoT Aprovisionado para Device Update dentro del centro de IoT.

• El agente de Device Update instalado e iniciado en el dispositivo IoT como una identidad de nivel de dispositivo o de módulo.

• Una actualización importada del dispositivo aprovisionado.

• El entorno de Bash en Azure Cloud Shell para ejecutar comandos de la CLI de Azure. Seleccione Iniciar Cloud Shell para abrir Cloud Shell o seleccione el icono de Cloud Shell en la barra de herramientas superior de Azure Portal.

  

  Nota:

  Si lo prefiere, puede ejecutar los comandos de la CLI de Azure localmente:

  1. Instalación de la CLI de Azure. Ejecute az version para ver la versión instalada de la CLI de Azure y las bibliotecas dependientes, y ejecute az upgrade para instalar la versión más reciente.
  2. Ejecute az login para iniciar sesión en Azure.
  3. Instale la extensión azure-iot cuando se le solicite por primera vez. Para asegurarse de que usa la versión más reciente de la extensión, ejecute az extension update --name azure-iot.

Agregar etiquetas a los dispositivos

Para asignar un grupo de dispositivos de Device Update, agregue la etiqueta ADUGroup a un conjunto de destino de dispositivos conectados de Device Update en IoT Hub. Agregue la etiqueta al dispositivo gemelo si el agente de Device Update se aprovisiona con la identidad del dispositivo o al módulo gemelo correspondiente si el agente de Device Update se aprovisiona con una identidad de módulo.

La etiqueta ADUGroup de Device Update usa un formato de clave-valor, como se muestra en el ejemplo de dispositivo o módulo gemelo siguiente:

"etag": "",
"deviceId": "",
"deviceEtag": "",
"version": <version>,
"tags": {
   "ADUGroup": "<CustomTagValue>"
}

Para más información y ejemplos de sintaxis JSON para elementos gemelos, consulte Descripción y uso de dispositivos gemelos o Descripción y uso de módulos gemelos.

La etiqueta ADUGroup tiene las siguientes propiedades y limitaciones:

• Un dispositivo solo puede tener una etiqueta ADUGroup y pertenecer solo a un grupo de Device Update a la vez. Agregar otra etiqueta denominada ADUGroup invalida el valor de ADUGroup existente.
• Puede usar cualquier valor para la etiqueta excepto los valores reservados Uncategorized y $default.
• El valor de etiqueta no puede tener más de 200 caracteres.
• El valor de etiqueta puede contener caracteres alfanuméricos y los caracteres especiales: . - _ ~.
• Los valores de nombre de etiqueta ADUGroup y nombre de grupo distinguen mayúsculas de minúsculas.

En las secciones siguientes se describen varias formas de agregar y actualizar la etiqueta.

Adición de etiquetas con los SDK

Puede actualizar el dispositivo o el módulo gemelo con la etiqueta adecuada mediante RegistryManager después de que inscriba el dispositivo en Device Update. Vea los siguientes artículos para más información:

• Introducción a los dispositivos gemelos con .NET
• Comprender el formato de etiquetas y las propiedades

Adición de etiquetas mediante trabajos

Es posible programar trabajos para agregar o actualizar etiquetas de Device Update en varios dispositivos. Para ver ejemplos, consulte Programación de trabajos en varios dispositivos. Puede actualizar dispositivos gemelos o módulos gemelos mediante trabajos, en función de si el agente de Device Update se aprovisiona con una identidad de dispositivo o módulo. Para obtener más información, consulte Programación y difusión de trabajos.

Nota:

Esta operación va en detrimento de la cuota de mensajes de IoT Hub. Si cambia a 50 000 o más etiquetas de dispositivo o módulo gemelo como máximo a la vez, es posible que tenga que supere la cuota diaria de mensajes de IoT Hub y tenga que comprar más unidades de IoT Hub. Para más información, consulte Cuotas y límites.

Adición de etiquetas mediante la actualización de gemelos

También puede agregar o actualizar la etiqueta ADUGroup directamente en el dispositivo o módulo gemelo.

Azure Portal

1. En Azure Portal, navegue hasta su centro de IoT.

2. Seleccione Dispositivos en Administración de dispositivos en el panel de navegación izquierdo. Si tiene un dispositivo IoT Edge, seleccione IoT Edge en su lugar.

3. En la página Dispositivos, seleccione el dispositivo.

4. En la página del dispositivo, seleccione Dispositivo gemelo en el menú superior o seleccione la identidad del módulo en Identidades de módulo y, a continuación, seleccione el módulo gemelo.

5. En el gemelo, agregue la etiqueta ADUGroup con un valor definido por el usuario, como se indica a continuación. Para actualizar un valor de etiqueta ADUGroup existente, sobrescriba con un valor definido por el usuario diferente.

       "tags": {
               "ADUGroup": "<CustomTagValue>"
               }
   

6. Seleccione Guardar.

CLI de Azure

Use az iot hub device-twin update o az iot hub module-twin update para agregar la etiqueta ADUGroup a un dispositivo o módulo gemelo con un valor adecuado. Con ambos comandos update, el argumento --tags acepta código JSON insertado o una ruta de acceso de archivo al contenido JSON.

Por ejemplo:

az iot hub module-twin update \
    --hub-name <IoT hub name> \
    --device-id <device name> \
    --module-id <module name> \
    --tags '{"ADUGroup": "<custom_tag_value"}'

Visualización de grupos de dispositivos

Azure Portal

1. En Azure Portal, vaya al centro de IoT conectado a la instancia de Device Update.

2. Seleccione la opción Actualizaciones en Administración de dispositivos en el panel de navegación izquierdo.

3. Seleccione la pestaña Grupos e implementaciones.

   

Una vez creado un grupo, se actualiza el gráfico de cumplimiento y la lista de grupos. El gráfico de cumplimiento de Device Update muestra el número de dispositivos en distintos estados de cumplimiento: En la actualización más reciente, Nuevas actualizaciones disponibles y Actualizaciones en curso. Para más información, consulte Cumplimiento de Device Update.

Los grupos de Device Update existentes y las actualizaciones disponibles para los dispositivos de esos grupos aparecen en la lista de grupos. Los dispositivos que no cumplen los requisitos de clase de dispositivo del grupo aparecen en un grupo no válido correspondiente. Puede implementar la mejor actualización disponible en un grupo de esta vista seleccionando Implementar junto al grupo.

CLI de Azure

Use az iot du device group list para ver todos los grupos del dispositivos en una instancia de Device Update.

az iot du device group list \
    --account <Device Update account name> \
    --instance <Device Update instance name>

Puede usar el argumento --order-by para ordenar la lista devuelta en función de aspectos como el identificador de grupo, el recuento de dispositivos o el recuento de subgrupos con nuevas actualizaciones disponibles.

Visualización de los detalles del dispositivo de un grupo

Azure Portal

1. En la pestaña Grupos e implementaciones, seleccione el nombre del grupo.

   La página Detalles del grupo muestra el gráfico de cumplimiento de actualizaciones con el recuento de dispositivos miembros del grupo en varios estados de cumplimiento y la lista de dispositivos miembros del grupo con sus propiedades de actualización de dispositivos.

   

2. Seleccione un dispositivo individual de un grupo para que el sistema vaya a la página de detalles del dispositivo en IoT Hub.

   

   

CLI de Azure

Use az iot du device group show para ver los detalles de un grupo de dispositivos específico.

• La marca opcional --best-updates devuelve una lista de las mejores actualizaciones disponibles para el grupo de dispositivos, incluido un recuento de cuántos dispositivos necesitan cada actualización.

• La marca opcional --update-compliance devuelve información de cumplimiento sobre el grupo de dispositivos, incluido el número de dispositivos en su actualización más reciente, necesitan nuevas actualizaciones y tienen actualizaciones en curso.

az iot du device group show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <value of the ADUGroup tag for this group>
    --best-updates
    --update-compliance

Eliminar un dispositivo de un grupo de dispositivos

Para quitar un dispositivo de un grupo de dispositivos, cambie el valor de etiqueta ADUGroup a null en el gemelo y seleccione Guardar.

    "tags": {
            "ADUGroup": "null"
            }

Esta acción elimina la etiqueta de grupo del dispositivo gemelo y quita el dispositivo de su grupo de dispositivos.

Eliminación de un grupo de dispositivos

Device Update crea grupos de dispositivos automáticamente y conserva los grupos de dispositivo, las clases de dispositivo y las implementaciones para registros históricos u otras necesidades del usuario en lugar de limpiarlos automáticamente. Puede eliminar grupos de dispositivos a través de Azure Portal seleccionando y eliminando individualmente los grupos, o llamando al comando az iot du device group delete de la CLI de Azure en el grupo.

Para eliminarlo, el grupo debe cumplir los siguientes requisitos:

• No debe ser un grupo default.
• No debe tener ningún dispositivo miembro. Esto significa que ningún dispositivo aprovisionado en la instancia de Device Update debe tener una etiqueta ADUGroup con un valor que coincida con el nombre del grupo.
• No debe tener implementaciones activas ni canceladas asociadas.

Nota:

Si no puede eliminar un grupo que cumpla los requisitos anteriores, compruebe si tiene algún dispositivo incorrecto etiquetado como parte del grupo. Los dispositivos incorrectos no pueden recibir una implementación, por lo que no aparecen directamente en la lista de dispositivos miembros de un grupo.

Para comprobar si tiene algún dispositivo incorrecto:

1. En Azure Portal, navegue hasta su centro de IoT.
2. Seleccione Actualizaciones en el menú de navegación izquierdo y, a continuación, seleccione la pestaña Diagnósticos.
3. Expanda la sección Búsqueda de dispositivos que faltan.

Si tiene dispositivos incorrectos etiquetados como parte del grupo, debe cambiar el valor de etiqueta o eliminar el dispositivo para poder eliminar el grupo.

Si un dispositivo se asigna de nuevo a un nombre de grupo eliminado, Device Update vuelve a crear el grupo automáticamente, pero no hay ningún historial de implementación o dispositivo asociado.

Contenido relacionado

• Grupos de dispositivos
• Cumplimiento de Device Update
• Implementación de una actualización