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 valores de marca de Atualização de Dispositivo definidos pelo usuário a dispositivos, a Atualização de Dispositivo criará automaticamente grupos com base nas marcas atribuídas e nas propriedades de compatibilidade do dispositivo. Para cada grupo de dispositivos, a Atualização de Dispositivo pode criar vários subgrupos que têm classes de dispositivo diferentes. A Atualização de Dispositivo coloca dispositivos que não têm marcas 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

Azure portal

• 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 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 no dispositivo provisionado.

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

Adicionar marcas aos seus dispositivos

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

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

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

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 marca chamada ADUGroup substitui o valor de ADUGroup existente.
• Você pode usar qualquer valor para a marca, exceto os valores reservados Uncategorized e $default.
• O valor da marca não pode exceder 200 caracteres.
• O valor da marca pode conter caracteres alfanuméricos e os seguintes caracteres especiais: . - _ ~.
• Os valores de nome da marca e do nome do grupo de ADUGroup diferenciam maiúsculas de minúsculas.

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

Adicionar marcas com 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:

• Introdução aos dispositivos gêmeos usando o .NET
• Entender o formato de marcas e propriedades

Adicionar marcas usando trabalhos

Você pode agendar trabalhos para adicionar ou atualizar marcas de Atualização de Dispositivo 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 difundir trabalhos.

Observação

Essa operação conta com a 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

1. No portal do Azure, navegue para o hub IoT.

2. Selecione Dispositivos no Gerenciamento de dispositivos no painel de navegação esquerdo. Se você tiver um dispositivo IoT Edge, selecione IoT Edge.

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

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

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

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

6. Selecione Salvar.

CLI do Azure

Use az iot hub device-twin update ou az iot hub module-twin update para adicionar a marca ADUGroup ao dispositivo ou módulo gêmeo 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"}'

Exibir grupos de dispositivos

Portal do Azure

1. No portal do Azure, navegue até o Hub IoT conectado à 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 atualização da lista de grupos. 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.

Os grupos de Atualização de Dispositivo existentes e as 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 nessa 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 argumento --order-by para ordenar a lista retornada por aspectos como ID do grupo, contagem de dispositivos ou contagem de subgrupos com novas atualizações disponíveis.

Exibir detalhes do dispositivo para um grupo

Azure portal

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 em um grupo para acessar a página de detalhes do dispositivo no Hub IoT.

   

   

CLI do Azure

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 marca ADUGroup para null no 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 ter nenhum dispositivo membro. 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 não for possível excluir um grupo que atenda aos requisitos anteriores, verifique se você tem algum dispositivo não íntegro marcado como parte do grupo. Dispositivos não íntegros não podem receber uma implantação, portanto, eles não aparecem diretamente na lista de dispositivos membros em um grupo.

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

1. No portal do Azure, navegue para o hub IoT.
2. Selecione Atualizações na navegação à esquerda e 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 marca ou excluir o dispositivo antes de 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.

Conteúdo relacionado

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