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

A Atualização de Dispositivo do Azure para o Hub IoT permite implantar atualizações em grupos de dispositivos IoT definidos pelo usuário. Cada dispositivo gerenciado pela Atualização de Dispositivo é membro de um grupo de dispositivos, mas a definição de grupos de dispositivos é opcional. Em alternativa, pode implementar no grupo predefinido de dispositivos fornecido pelo Device Update.

Se você criar e atribuir valores de tag de Atualização de Dispositivo definidos pelo usuário a dispositivos, a Atualização de Dispositivo criará automaticamente grupos com base nas tags atribuídas e nas propriedades de compatibilidade de dispositivos. Para cada grupo de dispositivos, a Atualização de Dispositivo pode criar vários subgrupos com classes de dispositivos diferentes. A Atualização de Dispositivos coloca os dispositivos que não têm etiquetas no grupo de dispositivos default.

Este artigo descreve como usar o portal do Azure ou a CLI do Azure para criar e gerenciar tags e grupos de dispositivos de Atualização de Dispositivo definidos 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, note os seguintes pré-requisitos:

Os dispositivos devem ser integrados com sucesso na Atualização de Dispositivos antes que a atribuição de grupos possa ocorrer.
Os dispositivos devem reportar 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 Device Update executa-se 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 Atualização de Dispositivos para o Hub IoT ativada.
Um dispositivo IoT ou simulador aprovisionado para Device Update no hub IoT.
O agente de Atualização do Dispositivo foi instalado e iniciado no dispositivo, quer como identidade ao nível do módulo, quer ao nível do dispositivo.
Uma atualização importada para o dispositivo provisionado.

Uma instância Standard (S1) ou superior de Hub IoT do Azure com a Atualização de Dispositivos para o Hub IoT ativada.
Um dispositivo IoT ou simulador provisionado para o Device Update no hub IoT.
O agente de Atualização de Dispositivos foi instalado e iniciado no dispositivo, quer como uma identidade ao nível do módulo, quer ao nível do dispositivo.
Uma atualização importada para o 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.
Nota

Se preferir, você pode executar 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 azure-iot extensão quando solicitado na primeira utilização. Para se certificar de que está a utilizar a versão mais recente da extensão, execute az extension update --name azure-iot.

Adicionar etiquetas aos seus dispositivos

Para atribuir um grupo de dispositivos de Atualização de Dispositivo, adicione a ADUGroup etiqueta a um conjunto alvo de dispositivos ligados à Atualização de Dispositivo no Hub IoT. Adicione a etiqueta ao gémeo do dispositivo se o agente de Atualização de Dispositivos estiver provisionado com a identidade do dispositivo, ou ao gémeo do módulo correspondente se o agente de Atualização de Dispositivos estiver provisionado com uma identidade de módulo.

A etiqueta Device Update ADUGroup utiliza um formato de chave-valor, como mostrado no exemplo seguinte de gémeo do dispositivo ou do módulo:

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

Importante

Adicionar a tag ADUGroup não adiciona um dispositivo ao Device Update. A atribuição de grupo só ocorre depois de a Atualização do Dispositivo reconhecer e gerir com sucesso o dispositivo.

Para obter mais informações e exemplos da sintaxe JSON dos dispositivos gémeos, consulte Compreender e utilizar gémeos de dispositivos ou Compreender e utilizar gémeos de módulos.

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

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

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

Adicionar tags com SDKs

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

Adicionar etiquetas usando tarefas

Você pode agendar trabalhos para adicionar ou atualizar tags de Atualização de Dispositivo em vários dispositivos. Para obter exemplos de operações de trabalho, consulte Agendar trabalhos em vários dispositivos. Pode atualizar duplos de dispositivo ou duplos de módulo através de tarefas, consoante o agente do Device Update esteja aprovisionado com uma identidade de dispositivo ou de módulo. Para obter mais informações, consulte Agendar e transmitir trabalhos.

Nota

Esta operação é contabilizada para a sua quota de mensagens do Hub IoT. Se você alterar 50.000 ou mais tags gêmeas de dispositivo ou módulo 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, consulte Quotas e limitação de débito.

Adicionar tags atualizando gêmeos

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

Portal do Azure
CLI do Azure

No Portal do Azure, navegue para o seu hub IoT.
Selecione Dispositivos em Gerenciamento de dispositivos no painel de navegação esquerdo. Se você tiver um dispositivo IoT Edge, selecione IoT Edge em vez disso.
Na página Dispositivos, selecione o dispositivo.
Na página do dispositivo, selecione Duplo do dispositivo no menu superior ou selecione a identidade do módulo em Identidades do módulo e, em seguida, selecione o duplo do módulo.
No twin, adiciona a ADUGroup tag com um valor definido pelo utilizador. Para atualizar um valor de tag existente ADUGroup , substitua-o por um valor diferente definido pelo usuário.
```
    "tags": {
            "ADUGroup": "<CustomTagValue>"
            }
```
Selecione Guardar.

Use az iot hub device-twin update ou az iot hub module-twin update para adicionar a ADUGroup tag ao dispositivo ou módulo twin com um valor apropriado. Para ambos os update comandos, o --tags argumento 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 Azure, aceda ao hub IoT ligado à sua instância de Atualização de Dispositivo.
Selecione a opção Atualizações em Gerenciamento de dispositivos na navegação à esquerda.
Selecione o separador Grupos e Implementações.

Quando crias um grupo, o quadro de conformidade e a lista de grupos atualizam-se. O gráfico de conformidade da Atualização de Dispositivo mostra a contagem de dispositivos em vários estados de conformidade: Na última atualização, Novas atualizações disponíveis e Atualizações em andamento. Para obter mais informações, consulte Conformidade com a 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 desses grupos. Dispositivos que não cumprem os requisitos de classe de dispositivo do grupo aparecem num grupo correspondente inválido. Você pode implantar a melhor atualização disponível para um grupo a partir dessa 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 devolvida por ID de grupo, contagem de dispositivos ou contagem de subgrupos com novas atualizações disponíveis.

Ver 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 das atualizações com a contagem de dispositivos do grupo em vários estados de conformidade, e a lista de dispositivos do grupo com as respetivas propriedades de atualização do dispositivo.
Selecione um dispositivo individual dentro de um grupo para ir para a página de detalhes do dispositivo no Hub IoT.

Utilize az iot du device group show para ver os 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 Guardar.

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

Esta ação remove a etiqueta de grupo do device twin 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 dispositivos 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 az iot du device group delete comando da CLI do Azure no grupo.

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

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

Nota

Se não conseguir eliminar um grupo que cumpra os requisitos anteriores, verifique se tem dispositivos com problemas de funcionamento identificados como fazendo parte do grupo. Os dispositivos com falhas não podem receber uma implantação, por isso não aparecem diretamente na lista dos dispositivos membros de um grupo.

Para verificar se tem algum dispositivo com problemas:

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

Se tiver dispositivos em estado não íntegro identificados com uma etiqueta como fazendo parte do grupo, terá de alterar o valor da etiqueta ou eliminar o dispositivo antes de poder eliminar 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 há nenhum dispositivo associado ou histórico de implantação.

Troubleshooting

Se identificar um dispositivo mas não vir nenhum grupo, tente os seguintes passos de resolução de problemas:

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

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

Comentários

Esta página foi útil?

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