Implante uma atualização usando a Atualização de Dispositivo para Hub IoT do Azure

Artigo
03/09/2023

Saiba como implantar uma atualização em um dispositivo IoT usando a Atualização de Dispositivo para Hub IoT do Azure.

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.
Uma atualização importada no dispositivo provisionado.
Um dispositivo (ou simulador) IoT provisionado para obter uma Atualização de Dispositivo no Hub IoT.
O dispositivo faz parte de pelo menos um grupo padrão ou grupo de atualização criado pelo usuário.

Azure portal
CLI do Azure

Navegadores compatíveis:

Microsoft Edge
Google Chrome

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.

Dica

Os comandos da CLI do Azure neste artigo usam o caractere de barra invertida \ para continuação de linha para que os argumentos de comando sejam mais fáceis de ler. Essa sintaxe funciona em ambientes Bash. Se você estiver executando esses comandos no PowerShell, substitua cada barra invertida por um acento grave ``` ou remova-os inteiramente.

No portal do Azure, navegue para o hub IoT.
Selecione Atualizações no menu de navegação para abrir a página Atualização de Dispositivo da instância do Hub IoT.
Selecione a guia Grupos e Implantações na parte superior da página. Para obter mais informações, confira Grupos de dispositivos.
Exiba a lista de grupos e gráficos de conformidade das atualizações. Você deve ver uma nova atualização disponível para seu grupo padrão ou baseado em marca. Talvez você precise atualizar novamente. Para obter mais informações, confira a Conformidade de Atualização de Dispositivo.
Selecione Implantar ao lado de uma ou mais atualizações disponíveis e confirme se o rótulo descritivo que você adicionou ao importar está presente e parece correto.
Confirme se o grupo correto foi selecionado como o grupo de destino e selecione Implantar.
Para iniciar a implantação, acesse a guia Implantação atual. Selecione o link Implantar ao lado da atualização desejada na seção de Atualizações disponíveis. A melhor atualização disponível para determinado grupo é indicada com a Melhor em destaque.
Agende sua implantação para iniciar imediatamente ou no futuro.

Dica

Por padrão, a data e a hora de Início são definidas como Imediatamente. Lembre-se de selecionar uma data e uma hora diferentes, caso deseje que a implantação comece mais tarde.
Crie uma política de reversão automática, se necessário. Em seguida, selecione Criar.
Em Detalhes da implantação, o Status se torna Ativo. A atualização implantada é marcada com (implantando).
Exiba o gráfico de conformidade para ver se a atualização está em andamento.
Depois de atualizar seu dispositivo com êxito, você verá que o gráfico de conformidade e os detalhes da implantação atualizados refletem as mesmas informações.

O az iot du device group list para verificar a melhor atualização disponível para seu grupo. O comando recebe os seguintes argumentos:

--account: o nome da conta de atualização de dispositivo.
--instance: o nome da instância de Atualização do Dispositivo.
--group-id: a ID do grupo de dispositivos que você está direcionando com essa implantação. Essa ID é o valor da marca ADUGroup ou $default para dispositivos sem marca.
--best-updates: esse sinalizador indica que o comando deve buscar as melhores atualizações disponíveis para o grupo de dispositivos, incluindo uma contagem de quantos dispositivos precisam de cada atualização.
"--resource-group -g": nome do grupo de recursos da conta de Atualização de Dispositivo.
"--update-compliance": esse sinalizador indica que o comando deve buscar informações de conformidade de atualização do grupo de dispositivos, como quantos dispositivos estão na atualização mais recente, quantos precisam de novas atualizações e quantos estão recebendo uma nova atualização no momento.

az iot du device group list \
    --account <Device Update account name> \
    --instance <Device Update instance name>\
    --gid <device group id>\
    --best-updates {false, true}

Use az iot du device deployment create para criar uma implantação para um grupo de dispositivos.

O comando device deployment create usa os seguintes argumentos:

--account: o nome da conta de atualização de dispositivo.
--instance: o nome da instância de Atualização do Dispositivo.
--group-id: a ID do grupo de dispositivos que você está direcionando com essa implantação. Essa ID é o valor da marca ADUGroup ou $default para dispositivos sem marca.
--deployment-id: a ID para identificar essa implantação.
--update-name, --update-provider e --update-version: esses três parâmetros definem o objeto updateId que é um identificador exclusivo para a atualização que você está usando nesta implantação.

az iot du device deployment create \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id> \
    --deployment-id <deployment id> \
    --update-name <update name> \
    --update-provider <update provider> \
    --update-version <update version>

Os argumentos opcionais permitem configurar a implantação. Para obter a lista completa, confira Parâmetros opcionais

Se você quiser criar uma política de reversão automática, adicione os seguintes parâmetros:

--failed-count: o número de dispositivos com falha na implantação que disparará uma reversão.
--failed-percentage: a porcentagem de dispositivos com falha na implantação que disparará uma reversão.
--rollback-update-name, --rollback-update-provider, --rollback-update-version: a updateID para a atualização que o grupo de dispositivos usará se a reversão for iniciada.

az iot du device deployment create \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id> \
    --deployment-id <deployment id> \
    --update-name <update name> \
    --update-provider <update provider> \
    --update-version <update version> \
    --failed-count 10 \
    --failed-percentage 5 \
    --rollback-update-name <rollback update name> \
    --rollback-update-provider <rollback update provider> \
    --rollback-update-version <rollback update version>

Se você quiser que a implantação seja iniciada no futuro, use o parâmetro --start-time para fornecer o datetime de destino para a implantação.

az iot du device deployment create \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id> \
    --deployment-id <deployment id> \
    --update-name <update name> \
    --update-provider <update provider> \
    --update-version <update version> \
    --start-time "2022-12-20T01:00:00"

Monitorar uma implantação de atualização

Azure portal
CLI do Azure

Selecione o grupo no qual você implantou e vá para a guia Atualizações atuais ou Histórico de implantação para confirmar se a implantação está em andamento
Selecione Detalhes ao lado da implantação criada. Aqui, você pode exibir os detalhes da implantação, da atualização e da classe de dispositivo de destino. Opcionalmente, você pode adicionar um nome amigável para a classe de dispositivo.
Selecione Atualizar para exibir os detalhes mais recentes do status.
Você pode ir para a exibição de noções básicas do grupo para pesquisar o status de um dispositivo específico ou filtrar para exibir dispositivos que falharam na implantação

Use az iot du device deployment list para exibir toda a implantação de um grupo de dispositivos.

az iot du device deployment list \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id>

Use az iot du device deployment show para exibir os detalhes de uma implantação específica.

az iot du device deployment show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group ID> \
    --deployment-id <deployment ID>

Adicione o sinalizador --status para retornar informações sobre quantos dispositivos na implantação estão em andamento, concluídos ou com falha.

az iot du device deployment show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group ID> \
    --deployment-id <deployment ID> \
    --status

Tentar executar uma implantação de atualizações novamente

Caso haja falha na implantação por algum motivo, será possível tentar executar a implantação de dispositivos com falha novamente.

Azure portal
CLI do Azure

Acesse a guia Implantação atual na tela Detalhes do grupo.
Selecione Tentar executar dispositivos com falha novamente e aceite a notificação de confirmação.

Use az iot du device deployment retry para repetir uma implantação para um subgrupo de dispositivos de destino.

Esse comando usa o argumento --class-id, que é gerado a partir da ID do modelo e das propriedades de compatibilidade informadas pelo agente de atualização do dispositivo.

az iot du device deployment retry \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --deployment-id <deployment ID> \
    --group-id <device group ID> \
    --class-id <device class ID>

Próximas etapas

Solução de problemas comuns