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. Como alternativa, você pode implantar no grupo de dispositivos padrão fornecido pela Atualização de Dispositivo.

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 Dispositivo coloca dispositivos que não têm marcas no grupo de default dispositivos.

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

Portal do Azure

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

CLI do Azure

• Uma instância Standard (S1) ou superior do Hub IoT do Azure com a Atualização de Dispositivo para o Hub IoT habilitada.

• Um dispositivo ou simulador IoT provisionado para Atualização de Dispositivo dentro do hub IoT.

• O agente de Atualização de Dispositivo instalado e iniciado no dispositivo como uma identidade no nível do módulo ou 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 marca a um conjunto de dispositivos conectados de Atualização de Dispositivo de destino no Hub IoT. Adicione a tag ao gêmeo de dispositivo se o agente de Atualização de Dispositivo estiver provisionado com identidade de dispositivo ou ao gêmeo de módulo correspondente se o agente de Atualização de Dispositivo for provisionado com uma identidade de módulo.

A tag Atualização de ADUGroup dispositivo usa um formato chave-valor, conforme mostrado no seguinte exemplo de dispositivo ou módulo gêmeo:

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

Para obter mais informações e exemplos de sintaxe JSON gêmea, consulte Compreender e usar gêmeos de dispositivo ou Entender e usar gêmeos de módulo.

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 de nome de ADUGroup tag e nome de grupo diferenciam maiúsculas de 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:

• Introdução aos gêmeos de dispositivo usando o .NET
• Compreender o formato de tags e propriedades

Adicionar tags usando trabalhos

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. Você pode atualizar gêmeos de dispositivo ou gêmeos de módulo usando trabalhos, dependendo se o agente de Atualização de Dispositivo é provisionado com uma identidade de dispositivo ou módulo. Para obter mais informações, consulte Agendar e transmitir trabalhos.

Nota

Essa operação conta na sua cota 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 Cotas e limitação.

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

1. No Portal do Azure, navegue para o seu hub IoT.

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

3. Na página Dispositivos, selecione o dispositivo.

4. Na página do dispositivo, selecione Gêmeo do dispositivo no menu superior ou selecione a identidade do módulo em Identidades do módulo e, em seguida, selecione o gêmeo do módulo.

5. No gêmeo, adicione a ADUGroup tag com um valor definido pelo usuário, da seguinte maneira. Para atualizar um valor de tag existente ADUGroup , substitua-o por um valor diferente definido pelo usuário.

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

6. Selecione Guardar.

CLI do Azure

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

Ver grupos de dispositivos

Portal do Azure

1. No portal do Azure, navegue até o hub IoT conectado à sua instância de Atualização de Dispositivo.

2. Selecione a opção Atualizações em Gerenciamento de dispositivos na navegação à esquerda.

3. Selecione a guia Grupos e implantações .

   

Depois de criar um grupo, o gráfico 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: 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.

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

CLI do Azure

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>

Você pode usar o --order-by argumento para ordenar a lista retornada por aspetos como 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

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

   

2. Selecione um dispositivo individual dentro de um grupo para ir para a página de detalhes do dispositivo no Hub IoT.

   

   

CLI do Azure

Use az iot du device group show para visualizar 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 ADUGroup etiqueta para null no gémeo e selecione Guardar.

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

Esta ação elimina a etiqueta de grupo do gémeo do dispositivo 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 deve ser um default grupo.
• Não deve ter dispositivos membros. 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 você não conseguir excluir um grupo que atenda aos requisitos anteriores, verifique se você tem dispositivos não íntegros marcados como parte do grupo. Os dispositivos não íntegros não podem receber uma implantação, portanto, eles não aparecem diretamente na lista de dispositivos membros de um grupo.

Para verificar se você tem algum dispositivo não íntegro:

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

Se você tiver dispositivos não íntegros 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 há nenhum dispositivo associado ou histórico de implantação.

Conteúdos relacionados

• Grupos de dispositivos
• Conformidade com a Atualização de Dispositivo
• Implantar uma atualização