Gerenciar grupos de dispositivos para a Atualização de Dispositivo do Azure para Hub IoT

A Atualização de Dispositivo do Azure para Hub IoT permite implantar atualizações em grupos definidos pelo usuário de dispositivos IoT. Cada dispositivo gerenciado de Atualização de Dispositivo é membro de um grupo de dispositivos, mas definir grupos de dispositivos é opcional. Como alternativa, você pode implantar no grupo de dispositivos padrão que a Atualização de Dispositivo fornece.

Se você criar e atribuir aos dispositivos valores de marcação da Atualização de Dispositivos definidos pelo usuário, a Atualização de Dispositivos criará automaticamente grupos com base nas marcações atribuídas e nas propriedades de compatibilidade dos dispositivos. Para cada grupo de dispositivos, a Atualização de Dispositivo pode criar vários subgrupos que têm classes de dispositivo diferentes. O Device Update coloca dispositivos que não possuem tags no grupo de dispositivos default.

Este artigo descreve como usar o portal do Azure ou a CLI do Azure para criar e gerenciar grupos e marcas de dispositivo definidas pelo usuário. Para implantar atualizações em grupos de dispositivos definidos pelo usuário ou padrão, consulte Implantar uma atualização de dispositivo.

Pré-requisitos

Antes de começar, observe os seguintes pré-requisitos:

Os dispositivos devem ser integrados com sucesso na Atualização de Dispositivo antes que a atribuição de grupos possa ocorrer.
Os dispositivos devem informar um ID de modelo Plug and Play suportado. Para uma lista de IDs de modelo suportados, veja Modelos de Atualização de Dispositivo.
Para cenários de IoT Edge, o agente de Atualização de Dispositivo roda como um módulo e deve reportar o ID do modelo através da identidade apropriada.

Portal do Azure
CLI do Azure

Uma instância Standard (S1) ou superior do Hub IoT do Azure com a Atualização de Dispositivo para Hub IoT habilitada.
Um dispositivo ou simulador de IoT provisionado para a Atualização de Dispositivo dentro do Hub IoT.
O agente do Device Update foi instalado e iniciado no dispositivo com uma identidade de nível de módulo ou de nível de dispositivo.
Uma atualização importada no dispositivo provisionado.

Uma instância Standard (S1) ou superior do Hub IoT do Azure com a Atualização de Dispositivo para Hub IoT habilitada.
Um dispositivo ou simulador de IoT provisionado para a Atualização de Dispositivo dentro do Hub IoT.
O agente do Device Update foi instalado e iniciado no dispositivo com uma identidade de nível de módulo ou de nível de dispositivo.
Uma atualização importada no dispositivo provisionado.
O ambiente Bash no Azure Cloud Shell para executar os comandos da CLI do Azure. Selecione Iniciar o Cloud Shell para abrir o Cloud Shell ou selecione o ícone do Cloud Shell na barra de ferramentas superior do portal do Azure.
Observação

Se preferir, execute os comandos da CLI do Azure localmente:
1. Instalar a CLI do Azure. Execute az version para ver a versão instalada da CLI do Azure e as bibliotecas dependentes e execute az upgrade para instalar a versão mais recente.
2. Entre no Azure executando az login.
3. Instale a extensão azure-iot quando solicitado no primeiro uso. Para verificar se está usando a versão mais recente da extensão, execute az extension update --name azure-iot.

Adicione tags aos seus dispositivos

Para atribuir um grupo de dispositivos do Device Update, adicione a tag ADUGroup a um conjunto de destino de dispositivos conectados ao Device Update no Hub IoT. Adicione a tag ao gêmeo do dispositivo se o agente de Atualização de Dispositivo estiver provisionado com identidade do dispositivo, ou ao gêmeo do módulo correspondente se o agente de Atualização de Dispositivo estiver provisionado com identidade de módulo.

A tag Device Update ADUGroup utiliza um formato de chave-valor, conforme mostrado no seguinte exemplo de gêmeo de dispositivo ou de módulo:

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

Importante

Adicionar a marca ADUGroup não adiciona um dispositivo ao Device Update. A atribuição de grupos só ocorre depois que a Atualização de Dispositivo reconhece e gerencia o dispositivo com sucesso.

Para obter mais informações e exemplos da sintaxe de gêmeo JSON, consulte Entender e usar dispositivos gêmeos ou Entender e usar módulos gêmeos.

A marca ADUGroup tem as seguintes propriedades e limitações:

Um dispositivo só pode ter uma marca ADUGroup e pertencer a apenas um grupo de Atualização de Dispositivo por vez. Adicionar outra tag chamada de ADUGroup substitui o valor existente de ADUGroup.
Você pode usar qualquer valor para a tag, exceto os valores reservados Uncategorized e $default.
O valor da etiqueta não pode ter mais de 200 caracteres.
O valor da etiqueta pode conter caracteres alfanuméricos e os seguintes caracteres especiais: . - _ ~.
Os valores de nome da tag ADUGroup e do nome do grupo diferenciam letras maiúsculas de minúsculas.

As seções a seguir descrevem várias maneiras de adicionar e atualizar a tag.

Adicionar tags usando SDKs

Você pode atualizar o dispositivo ou módulo gêmeo com a marca apropriada usando RegistryManager depois de registrar o dispositivo com a Atualização do Dispositivo. Para obter mais informações, consulte os seguintes artigos:

Adicionar tags usando tarefas

Você pode agendar tarefas para adicionar ou atualizar tags do Device Update em vários dispositivos. Para obter exemplos de operações de trabalho, confira Agendar trabalhos em vários dispositivos. Você pode atualizar dispositivos gêmeos ou módulos gêmeos usando trabalhos dependendo de o agente de Atualização de Dispositivo estar provisionado com uma identidade de dispositivo ou módulo. Para obter mais informações, confira Agendar e transmitir tarefas.

Observação

Esta operação é contabilizada na cota de mensagens do Hub IoT. Se você alterar 50.000 ou mais marcas de dispositivo ou módulo gêmeo de cada vez, poderá exceder sua cota diária de mensagens do Hub IoT e precisar comprar mais unidades do Hub IoT. Para obter mais informações, confira Cotas e limitação.

Adicionar marcas atualizando gêmeos

Você também pode adicionar ou atualizar a marca ADUGroup diretamente no dispositivo ou módulo gêmeo.

Portal do Azure
CLI do Azure

No portal do Azure, navegue para o hub IoT.
Selecione Dispositivos no Gerenciamento de dispositivos no painel de navegação esquerdo. Se você tiver um dispositivo IoT Edge, selecione IoT Edge.
Na página Dispositivos, selecione seu dispositivo.
Na página do dispositivo, selecione Dispositivo gêmeo no menu superior ou selecione a identidade do módulo em identidades do módulo e selecione o módulo gêmeo.
No twin, adicione a ADUGroup tag com um valor definido pelo usuário. Para atualizar um valor de marca de ADUGroup existente, substitua-o por um valor diferente definido pelo usuário.
```
    "tags": {
            "ADUGroup": "<CustomTagValue>"
            }
```
Selecione Salvar.

Use az iot hub device-twin update ou az iot hub module-twin update para adicionar a tag ADUGroup ao gêmeo do dispositivo ou do módulo com um valor apropriado. Para ambos os comandos update, o argumento --tags aceita JSON embutido ou um caminho para um arquivo JSON.

Por exemplo:

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

No portal do Azure, vá ao hub IoT conectado à sua instância de Atualização de Dispositivo.
Selecione a opção Atualizações em Gerenciamento de Dispositivos na navegação à esquerda.
Selecione a guia Grupos e Implantações.

Quando você cria um grupo, o quadro de conformidade e a lista de grupos são atualizados. O gráfico de conformidade da Atualização de Dispositivo mostra a contagem de dispositivos em vários estados de conformidade: Com a atualização mais recente, Novas atualizações disponíveis e Atualizações em andamento. Para obter mais informações, confira a Conformidade da Atualização de Dispositivo.

A lista de grupos mostra os grupos de Atualização de Dispositivos existentes e quaisquer atualizações disponíveis para os dispositivos nesses grupos. Dispositivos que não atendem aos requisitos de classe de dispositivo do grupo aparecem em um grupo correspondente inválido. Você pode implantar a melhor atualização disponível para um grupo nessa exibição selecionando Implantar ao lado do grupo.

Use az iot du device group list para exibir todos os grupos de dispositivos em uma instância de Atualização de Dispositivo.

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

Use o --order-by argumento para ordenar a lista retornada por ID de grupo, contagem de dispositivos ou contagem de subgrupos com novas atualizações disponíveis.

Exibir detalhes do dispositivo para um grupo

Portal do Azure
CLI do Azure

Na guia Grupos e Implantações, selecione o nome do grupo.

A página Detalhes do Grupo mostra o gráfico de conformidade de atualização com a contagem de dispositivos membros do grupo em vários estados de conformidade e a lista de dispositivos membros do grupo com suas propriedades de atualização de dispositivo.
Selecione um dispositivo individual em um grupo para acessar a página de detalhes do dispositivo no Hub IoT.

Use az iot du device group show para exibir detalhes de um grupo de dispositivos específico.

O sinalizador opcional --best-updates retorna uma lista das melhores atualizações disponíveis para o grupo de dispositivos, incluindo uma contagem de quantos dispositivos precisam de cada atualização.
O sinalizador opcional --update-compliance retorna informações de conformidade para o grupo de dispositivos, incluindo quantos dispositivos estão em sua atualização mais recente, precisam de novas atualizações ou têm atualizações em andamento.

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

Remover um dispositivo de um grupo de dispositivos

Para remover um dispositivo de um grupo de dispositivos, altere o valor da tag ADUGroup para null no dispositivo gêmeo e selecione Salvar.

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

Essa ação exclui a marca de grupo do dispositivo gêmeo e remove o dispositivo do grupo de dispositivos.

Excluir um grupo de dispositivos

A Atualização de Dispositivo cria automaticamente grupos de dispositivos e retém grupos de dispositivos, classes de dispositivo e implantações para registros históricos ou outras necessidades do usuário, em vez de limpá-los automaticamente. Você pode excluir grupos de dispositivos por meio do portal do Azure selecionando e excluindo individualmente os grupos ou chamando o comando az iot du device group delete CLI do Azure no grupo.

Para ser excluído, um grupo deve atender aos seguintes requisitos:

Não deve ser um grupo default.
Não deve haver dispositivos associados. Ou seja, nenhum dispositivo provisionado na instância de Atualização de Dispositivo pode ter uma marca ADUGroup com um valor que corresponda ao nome do grupo.
Não deve ter implantações ativas ou canceladas associadas.

Observação

Se você não conseguir excluir um grupo que atenda aos requisitos anteriores, verifique se há dispositivos em estado não íntegro marcados como parte do grupo. Dispositivos não saudáveis não podem receber uma implantação, por isso não aparecem diretamente na lista de dispositivos membros de um grupo.

Para verificar se você tem algum dispositivo com problemas:

No portal do Azure, navegue para o hub IoT.
Selecione Atualizações na navegação à esquerda e selecione a guia Diagnóstico.
Expanda a seção Localizar dispositivos ausentes.

Se você tiver dispositivos em estado não íntegro marcados como parte do grupo, deverá alterar o valor da tag ou excluir o dispositivo antes de poder excluir o grupo.

Se um dispositivo for atribuído a um nome de grupo excluído novamente, a Atualização de Dispositivo recriará automaticamente o grupo, mas não haverá nenhum dispositivo ou histórico de implantação associado.

Troubleshooting

Se você marcar um dispositivo mas não vê um grupo, tente os seguintes passos de solução de problemas:

Verifique se a tag está configurada corretamente.
Verifique se o dispositivo inclui um ID de modelo Plug and Play válido e uma etiqueta válidaADUGroup.
Confirme se as rotas de mensagens do Hub IoT estão corretamente configuradas. Para mais informações, veja Roteamento de mensagens.
Certifique-se de que o Hub IoT esteja corretamente associado à instância de Atualização de Dispositivo.
Execute os diagnósticos do Device Update e a verificação do agente.
Execute a sincronização do dispositivo se necessário.

Para mais informações, veja Plug and Play no Azure Device Update e Device Update para a verificação do agente do Hub IoT do Azure.

Comentários

Esta página foi útil?

Última atualização em 2026-09-17