Administrar grupos de dispositivos en Device Update for IoT Hub

Device Update para IoT Hub permite implementar una actualización en un grupo de dispositivos IoT. Este paso es opcional al implementar actualizaciones en los dispositivos administrados. Puede implementar actualizaciones en los dispositivos mediante el grupo predeterminado que se crea automáticamente. Como alternativa, puede asignar una etiqueta definida por el usuario a los dispositivos y se agruparán automáticamente en función de la etiqueta y las propiedades de compatibilidad del dispositivo.

Nota

Si quiere realizar la implementación en un grupo predeterminado en lugar de en un grupo creado por el usuario, puede ir directamente a Implementación de una actualización

Requisitos previos

• Acceda a una instancia de IoT Hub con Device Update for IoT Hub habilitado. Se recomienda usar un nivel S1 (estándar), o superior, para su instancia de IoT Hub.
• Un dispositivo IoT (o simulador) aprovisionado para Device Update en IoT Hub.
  • Instale e inicie el agente de Device Update en el dispositivo IoT como una identidad de nivel de dispositivo o de módulo.
• Una actualización importada del dispositivo aprovisionado.

Azure Portal

Exploradores admitidos:

• Microsoft Edge
• Google Chrome

CLI de Azure

Un entorno de la CLI de Azure:

• Use el entorno de Bash en Azure Cloud Shell.

  

• O bien, si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure.

  1. Inicie sesión en la CLI de Azure mediante el comando az login.
  2. Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.
  3. Cuando se le solicite, instale las extensiones de la CLI de Azure la primera vez que lo use. Los comandos de este artículo usan la extensión azure-iot. Ejecute az extension update --name azure-iot para asegurarse de usar la versión más reciente de la extensión.

Adición de una etiqueta a los dispositivos

Para crear un grupo de dispositivos, el primer paso consiste en agregar una etiqueta al conjunto de dispositivos de destino en IoT Hub. Las etiquetas solo se pueden agregar correctamente al dispositivo una vez que se ha conectado a Device Update.

Las etiquetas de actualización de dispositivos utilizan el formato del siguiente ejemplo:

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

En las secciones siguientes se describen diferentes formas de agregar y actualizar etiquetas.

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 inscribir el dispositivo en Device Update. Para más información, consulte los siguientes artículos.

• Obtenga información sobre cómo agregar etiquetas con una aplicación de .NET de ejemplo.
• Obtenga información sobre las propiedades de las etiquetas.

Agregue etiquetas 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.

Adición de etiquetas mediante trabajos

Es posible programar un trabajo en varios dispositivos para agregar o actualizar una etiqueta de Device Update. 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 acción va en detrimento de la cuota de mensajes de IoT Hub. Se recomienda cambiar solo 50 000 etiquetas de dispositivo o módulo gemelo como máximo a la vez. De lo contrario, es posible que tenga que comprar más unidades de IoT Hub si supera la cuota diaria de mensajes 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 se pueden agregar o actualizar etiquetas directamente en el dispositivo gemelo o en el módulo gemelo.

Azure Portal

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

2. En Dispositivos o IoT Edge en el panel de navegación izquierdo, busque el dispositivo IoT. Vaya al dispositivo gemelo o al módulo de Device Update y, luego, a su módulo gemelo, en función de si el agente de Device Update está aprovisionado con una identidad de dispositivo o módulo.

3. En los detalles del elemento gemelo, elimine cualquier valor de etiqueta de Device Update existente. Para ello, establézcalo en NULL.

4. Agregue un nuevo valor de etiqueta de Device Update, como se muestra a continuación.

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

CLI de Azure

Use az iot hub device-twin update o az iot hub module-twin update para agregar una etiqueta a un dispositivo o módulo gemelo.

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"}'

Limitaciones

• Puede agregar cualquier valor a la etiqueta excepto Uncategorized y $default, que son valores reservados.
• El valor de etiqueta no puede tener más de 200 caracteres.
• El valor de etiqueta puede contener caracteres alfanuméricos y los siguientes caracteres especiales: . - _ ~.
• Los nombres de etiquetas y grupos distinguen mayúsculas de minúsculas.
• Un dispositivo solo puede tener una etiqueta con el nombre ADUGroup. Cualquier adición de una etiqueta con ese nombre reemplazará el valor existente del nombre de etiqueta ADUGroup.
• Un dispositivo solo puede pertenecer a un grupo.

Visualización de grupos de dispositivos

Los grupos se crean automáticamente en función de las etiquetas asignadas, así como de las propiedades de compatibilidad de los dispositivos. Un grupo puede tener varios subgrupos con diferentes clases de dispositivo.

Azure Portal

1. En Azure Portal, vaya al centro de IoT que conectó anteriormente a la instancia de Device Update.

2. Seleccione la opción Actualizaciones en Administración de dispositivos en la barra de navegación izquierda.

3. Seleccione la pestaña Grupos e implementaciones.

   

4. Una vez creado el grupo, verá que se han actualizado la lista de grupos y el gráfico de cumplimiento. 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.

   

5. Debería ver los grupos existentes y las actualizaciones disponibles para los dispositivos de esos grupos en la lista de grupos. Si hay dispositivos que no cumplen los requisitos de clase de dispositivo del grupo, se mostrarán en un grupo no válido correspondiente. Puede implementar la mejor actualización disponible en un grupo de esta vista seleccionando el botón Implementar junto al grupo.

CLI de Azure

Use az iot du device group list para ver todos los grupos de 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 los grupos devueltos 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 que quiere ver.

2. En la página de detalles del grupo puede ver una lista de dispositivos que forman parte del grupo junto con sus propiedades de actualización de dispositivos. En esta vista, también puede ver la información de Update Compliance para todos los dispositivos que son miembros del grupo. El gráfico de cumplimiento muestra el recuento de dispositivos en varios estados de cumplimiento.

   

3. También puede seleccionar un dispositivo individual de un grupo para que el sistema lo redirija 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, cuántos necesitan nuevas actualizaciones y cuántos están en curso para una nueva actualización.

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>

Eliminación de un dispositivo de un grupo de dispositivos

Para quitar un dispositivo de un grupo de dispositivos, el valor de la etiqueta ADUGroup debe cambiarse a "null".

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

Esto eliminará la etiqueta ADUGroup del dispositivo gemelo y quitará el dispositivo de su grupo de dispositivos.

Eliminación de grupos de dispositivos

Aunque los grupos de dispositivos se crean automáticamente, los grupos, las clases de dispositivo y las implementaciones no se limpian automáticamente a fin de conservarlos para los registros históricos u otras necesidades del usuario. Los grupos de dispositivos se pueden eliminar mediante Azure Portal seleccionando y eliminando individualmente los grupos deseados, o llamando a DELETE API en el grupo. Más información

Si alguna vez se vuelve a conectar un dispositivo de este grupo después de haberlo eliminado, aunque el grupo se vuelva a crear automáticamente, no habrá ningún dispositivo ni historial de implementación asociado.

Para eliminarlo, el grupo debe cumplir los siguientes requisitos:

• El grupo 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 seleccionado.
• El grupo NO debe ser un grupo predeterminado.
• El grupo NO debe tener implementaciones activas ni canceladas asociadas.

Nota

Si sigue sin poder eliminar un grupo después de cumplir los requisitos anteriores, valide si tiene algún dispositivo incorrecto etiquetado como parte del grupo. Los dispositivos incorrectos son dispositivos que no pueden recibir una implementación y, como resultado, no se muestran directamente en la lista de dispositivos miembros de un grupo. Para validar si tiene algún dispositivo incorrecto, vaya a "Find missing devices" en la pestaña "Diagnostics" de la experiencia del portal de Device Update. En caso de que tenga dispositivos incorrectos etiquetados como parte del grupo, deberá modificar el valor de la etiqueta o eliminar el dispositivo por completo antes de intentar eliminar el grupo.

Pasos siguientes

• Implementación de una actualización

• Más información sobre los grupos de dispositivos

• Más información sobre el cumplimiento de Device Update