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

Antes de empezar, ten en cuenta los siguientes requisitos:

• Los dispositivos deben incorporarse correctamente a Device Update antes de que se les pueda asignar un grupo.
• Los dispositivos deben informar de un ID de modelo Plug and Play compatible. Para una lista de IDs de modelo compatibles, véase Modelos de actualización de dispositivos.
• En escenarios de IoT Edge, el agente de Actualización de Dispositivos se ejecuta como un módulo y debe informar del ID del modelo a través de la identidad correspondiente.

Agregar etiquetas a los dispositivos

Para asignar un grupo de dispositivos de Device Update, añade la etiqueta ADUGroup a un conjunto de destino de dispositivos conectados a Device Update en IoT Hub. Agregue la etiqueta al gemelo del dispositivo si el agente de Device Update está aprovisionado con la identidad del dispositivo, o al gemelo del módulo correspondiente si el agente de Device Update está aprovisionado 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 la etiqueta puede contener caracteres alfanuméricos y los siguientes caracteres especiales: . - _ ~.
• Los valores del nombre de la etiqueta ADUGroup y del nombre del grupo distinguen entre mayúsculas y 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

Añadir 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.

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.

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

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

Visualización de los detalles del dispositivo de un grupo

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 dispositivos asociados. 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.

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.

Troubleshooting

Si etiquetas un dispositivo pero no ves un grupo, prueba los siguientes pasos para solucionar problemas:

• Verifica que la etiqueta esté configurada correctamente.
• Verifica que el dispositivo incluya un ID válido del modelo Plug and Play y una etiqueta válidaADUGroup.
• Confirma que las rutas de mensajes del IoT Hub están correctamente configuradas. Para más información, véase Enrutamiento de mensajes.
• Asegúrate de que el IoT Hub esté correctamente asociado con la instancia de Actualización de Dispositivo.
• Ejecuta el diagnóstico de actualización de dispositivo y la comprobación del agente.
• Ejecuta la sincronización de dispositivos si es necesario.

Para más información, consulta Plug and Play en Azure Device Update y comprobación del agente de Device Update para Azure IoT Hub.

Contenido relacionado

• Grupos de dispositivos
• Cumplimiento de la actualización de dispositivos
• Implementación de una actualización