Gerenciar grupos de dispositivos na Atualização de Dispositivo para Hub IoT

A Atualização de Dispositivo para Hub IoT permite implantar uma atualização em um grupo de dispositivos IoT. Esta etapa é opcional ao implantar atualizações em seus dispositivos gerenciados. Você pode implantar atualizações em seus dispositivos usando o grupo padrão criado para você. Como alternativa, você pode atribuir uma marca definida pelo usuário aos seus dispositivos e eles serão agrupados automaticamente com base na marca e nas propriedades de compatibilidade do dispositivo.

Observação

Caso queira implantar em um grupo padrão, e não em um grupo criado pelo usuário, prossiga para Como implantar uma atualização.

Pré-requisitos

• Acesso a um Hub IoT com a Atualização de Dispositivo para Hub IoT habilitada. Recomendamos usar uma camada S1 (Standard) ou posterior para o Hub IoT.
• Um dispositivo (ou simulador) IoT provisionado para obter uma Atualização de Dispositivo no Hub IoT.
  • Instale e inicie o agente de Atualização de Dispositivo em seu dispositivo IoT como uma identidade no nível do módulo ou do dispositivo.
• Uma atualização importada no dispositivo provisionado.

Azure portal

Navegadores compatíveis:

• Microsoft Edge
• Google Chrome

CLI do Azure

Um ambiente da CLI do Azure:

• Use o ambiente Bash no Azure Cloud Shell.

  

• Ou, se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure

  1. Entre na CLI do Azure usando o comando az login.
  2. Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
  3. Quando solicitado, instale as extensões da CLI do Azure no primeiro uso. Os comandos neste artigo usam a extensão azure-iot. Execute az extension update --name azure-iot para verificar se está usando a versão mais recente da extensão.

Adicionar uma marca aos seus dispositivos

Para criar um grupo de dispositivos, o primeiro passo é adicionar uma marca ao conjunto de destino de dispositivos no Hub IoT. As marcas só podem ser adicionadas com êxito ao seu dispositivo depois que ele estiver conectado à Atualização de Dispositivo.

As marcas de Atualização de Dispositivo usam o formato no exemplo a seguir:

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

As seções a seguir descrevem diferentes maneiras de adicionar e atualizar marcas.

Adicionar marcas com SDKs

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

• Saiba como adicionar marcas usando um aplicativo .NET de exemplo.
• Saiba mais sobre as propriedades de marca.

Adicione marcas ao dispositivo gêmeo se o agente da 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.

Adicionar marcas usando trabalhos

Você pode agendar um trabalho em vários dispositivos para adicionar ou atualizar uma marca de Atualização de Dispositivo. 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 ação é contabilizada na cota de mensagens do Hub IoT. Recomendamos alterar apenas até 50.000 marcas de dispositivo ou módulo gêmeo de uma vez; caso contrário, poderá ser necessário comprar mais unidades do Hub IoT se você exceder a cota diária de mensagens do Hub IoT. Para obter mais informações, confira Cotas e limitação.

Adicionar marcas atualizando gêmeos

Marcas também podem ser adicionadas ou atualizadas diretamente em dispositivos ou módulos gêmeos.

Azure portal

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

2. Em Dispositivos ou IoT Edge no painel de navegação esquerdo, localize seu dispositivo IoT. Navegue até o dispositivo gêmeo ou o módulo da Atualização de Dispositivo e, em seguida, seu módulo gêmeo, dependendo de o agente da Atualização de Dispositivo ser provisionada com uma identidade do módulo ou dispositivo.

3. Nos detalhes do gêmeo, exclua todos os valores de marca existentes da Atualização de dispositivo definindo-os como null.

4. Adicione um novo valor de marca da Atualização de dispositivo, conforme mostrado abaixo.

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

CLI do Azure

Use az iot hub device-twin update ou az iot hub module-twin update para adicionar uma marca a um dispositivo ou módulo gêmeo.

Para ambos os comandos update, o argumento --tags aceita JSON em linha ou um caminho de arquivo para o conteúdo 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"}'

Limitações

• Você pode adicionar qualquer valor à sua marca, exceto por Uncategorized ou $default, que são valores reservados.
• 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 nomes de marcas e de grupos diferenciam maiúsculas de minúsculas.
• Um dispositivo só pode ter uma marca com o nome ADUGroup. Qualquer adição de uma marca com o nome substituirá o valor existente para o nome de marca ADUGroup.
• Um dispositivo só pode pertencer a um grupo.

Exibir grupos de dispositivos

Os grupos são criados automaticamente com base nas marcas atribuídas, bem como nas propriedades de compatibilidade dos dispositivos. Um grupo pode ter vários subgrupos com classes de dispositivo diferentes.

Azure portal

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

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

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

   

4. Depois que o grupo for criado, você verá que a lista de gráficos e grupos de conformidade será atualizada. 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.

   

5. Você deve ver os grupos existentes e as atualizações disponíveis para os dispositivos nesses grupos na lista de grupos. Se houver dispositivos que não atendem aos requisitos de classe de dispositivo do grupo, eles aparecerão em um grupo inválido correspondente. É possível implantar a melhor atualização disponível em um grupo dessa exibição clicando no botão 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 da 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 os grupos retornados com base em aspectos como ID de 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 que deseja exibir.

2. Na página de detalhes do grupo, você pode ver uma lista de dispositivos que fazem parte do grupo junto com suas propriedades de atualização de dispositivo. Nessa exibição, também é possível ver as informações de conformidade de atualização para todos os dispositivos que são membros do grupo. O gráfico de conformidade mostra a contagem de dispositivos em vários estados de conformidade.

   

3. Você também pode selecionar um dispositivo individual dentro de um grupo para ser redirecionado para 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 --update-compliance opcional retorna informações de conformidade para o grupo de dispositivos, incluindo quantos dispositivos estão em sua atualização mais recente, quantos precisam de novas atualizações e quantos estão em andamento para uma nova atualização.

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>

Como remover um dispositivo de um grupo de dispositivos

Para remover um dispositivo de um grupo de dispositivos, o valor da marca ADUGroup deve ser alterado para "nulo".

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

Isso excluirá a marca ADUGroup do dispositivo gêmeo e removerá o dispositivo de seu grupo de dispositivos.

Excluir grupos de dispositivos

Embora os grupos de dispositivos sejam criados automaticamente, grupos, classes de dispositivo e implantações não são limpos automaticamente para retê-los para registros históricos ou outras necessidades do usuário. Os grupos de dispositivos podem ser excluídos por meio do portal do Azure selecionando e excluindo individualmente os grupos desejados ou chamando a API DELETE no grupo. Saiba mais

Se um dispositivo for conectado novamente para este grupo depois que o grupo for excluído, enquanto o grupo for recriado automaticamente, não haverá nenhum dispositivo ou histórico de implantação associados.

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

• O grupo não deve ter NENHUM dispositivo membro. Isso significa que nenhum dispositivo provisionado na instância de Atualização de Dispositivo deve ter uma marca ADUGroup com um valor que corresponda ao nome do grupo selecionado.
• O grupo NÃO deve ser um grupo padrão.
• O grupo NÃO deve ter implantações ativas ou canceladas associadas a ele.

Observação

Se você ainda não conseguir excluir um grupo após atender aos requisitos acima, valide se você tem algum dispositivo não íntegro marcado como parte do grupo. Dispositivos não íntegros são dispositivos que não podem receber uma implantação e, como resultado, não aparecem diretamente na lista de dispositivos membros em um grupo. Você pode validar se tem algum dispositivo não íntegro acessando "Localizar dispositivos ausentes" na guia Diagnóstico na experiência do Portal de Atualização de Dispositivo. Caso você tenha dispositivos não íntegros marcados como parte do grupo, será necessário modificar o valor da marca ou excluir totalmente o dispositivo antes de tentar excluir seu grupo.

Próximas etapas

• Implantar uma atualização

• Saiba mais sobre os grupos de dispositivos

• Saiba mais sobre a conformidade da Atualização de Dispositivo