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

A Atualização de Dispositivo para o 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 tag definida pelo usuário aos seus dispositivos e eles serão agrupados automaticamente com base na tag e nas propriedades de compatibilidade do dispositivo.

Nota

Se você quiser implantar em um grupo padrão em vez de um grupo criado pelo usuário, continue para Como implantar uma atualização.

Pré-requisitos

• Acesso a um Hub IoT com a Atualização de Dispositivo para o Hub IoT habilitada. Recomendamos que você use uma camada S1 (Padrão) ou superior para seu Hub IoT.
• Um dispositivo IoT (ou simulador) provisionado para 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 para o dispositivo provisionado.

Portal do Azure

Browsers suportados:

• 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 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 o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.
  3. Quando solicitado, instale as extensões da CLI do Azure na primeira utilização. Os comandos neste artigo usam a extensão azure-iot . Execute az extension update --name azure-iot para se certificar de que está a utilizar a versão mais recente da extensão.

Adicionar uma etiqueta aos seus dispositivos

Para criar um grupo de dispositivos, a primeira etapa é adicionar uma tag ao conjunto de dispositivos de destino no Hub IoT. As etiquetas só podem ser adicionadas com êxito ao seu dispositivo depois de este ter sido ligado à Atualização de Dispositivo.

As tags 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 de sintaxe JSON gêmea, consulte Compreender e usar gêmeos de dispositivo ou Entender e usar gêmeos de módulo.

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

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 que podem estar em inglês:

• Saiba como adicionar tags usando um aplicativo .NET de exemplo.
• Saiba mais sobre as propriedades das tags.

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

Adicionar tags usando trabalhos

Você pode agendar um trabalho em vários dispositivos para adicionar ou atualizar uma tag de Atualização de Dispositivo. 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 ação conta na sua cota de mensagens do Hub IoT. Recomendamos alterar apenas até 50.000 tags gêmeas de dispositivo ou módulo de cada vez, caso contrário, talvez seja necessário comprar mais unidades do Hub IoT se exceder sua cota diária de mensagens do Hub IoT. Para obter mais informações, consulte Cotas e limitação.

Adicionar tags atualizando gêmeos

As tags também podem ser adicionadas ou atualizadas diretamente em gêmeos de dispositivo ou módulo.

Portal do Azure

1. No Portal do Azure, navegue para o seu 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 de Atualização de Dispositivo e, em seguida, seu módulo gêmeo, dependendo se o agente de Atualização de Dispositivo é provisionado com uma identidade de dispositivo ou módulo.

3. Nos detalhes gêmeos, exclua qualquer valor de tag de Atualização de Dispositivo existente definindo-os como nulo.

4. Adicione um novo valor de tag de 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 tag a um dispositivo ou módulo twin.

Para ambos os update comandos, o --tags argumento aceita json embutido ou um caminho de arquivo para 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 tag, exceto para Uncategorized e $default, que são valores reservados.
• 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 nomes de tags e grupos diferenciam maiúsculas de minúsculas.
• Um dispositivo só pode ter uma etiqueta com o nome ADUGroup. Quaisquer adições de uma tag com esse nome substituirão o valor existente para o nome da tag ADUGroup.
• Um dispositivo só pode pertencer a um grupo.

Ver grupos de dispositivos

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

Portal do Azure

1. No portal do Azure, navegue até o hub IoT que você conectou anteriormente à sua instância de Atualização de Dispositivo.

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

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

   

4. Depois que um grupo for criado, você verá que 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.

   

5. Você deve ver os grupos existentes e quaisquer atualizações disponíveis para os dispositivos nesses grupos na lista de grupos. Se houver dispositivos que não atendam aos requisitos de classe de dispositivo do grupo, eles aparecerão em um grupo inválido correspondente. Você pode implantar a melhor atualização disponível em um grupo a partir desse modo de exibição selecionando o 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 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 os grupos retornados com base em aspetos como ID do 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 que você deseja exibir.

2. Na página de detalhes do grupo, você pode ver uma lista de dispositivos que fazem parte do grupo, juntamente com suas propriedades de atualização de dispositivo. Nessa exibição, você também pode 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 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, 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>

Remover um dispositivo de um grupo de dispositivos

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

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

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

Eliminar grupos de dispositivos

Embora os grupos de dispositivos sejam criados automaticamente, os grupos, as classes de dispositivos e as implantações não são limpos automaticamente para mantê-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. Mais informações

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

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

• O grupo não deve ter dispositivos membros. Isso significa que nenhum dispositivo provisionado na instância de Atualização de Dispositivo deve ter uma tag ADUGroup com um valor correspondente ao nome do grupo selecionado.
• O grupo NÃO deve ser um grupo padrão.
• O grupo não deve ter NENHUMA implantação ativa ou cancelada associada a ele.

Nota

Se você ainda não conseguir excluir um grupo depois de 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 dentro de um grupo. Pode validar se tem dispositivos não saudáveis acedendo a "Localizar dispositivos em falta" no separador Diagnóstico na experiência do Portal de Atualização de Dispositivos. Caso você tenha dispositivos não íntegros marcados como parte do grupo, você precisará modificar o valor da tag ou excluir o dispositivo completamente antes de tentar excluir seu grupo.

Passos Seguintes

• Implantar uma atualização

• Saiba mais sobre grupos de dispositivos

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