Gerenciar dispositivos em massa no aplicativo do Azure IoT Central
É possível usar o Azure IoT Central para gerenciar seus dispositivos conectados em escala usando trabalhos. Os trabalhos permitem fazer atualizações em massa nas propriedades do dispositivo e da nuvem, bem como executar comandos. Este artigo mostra como usar trabalhos em seu próprio aplicativo e como usar os recursos de importação e exportação.
Para saber como gerenciar trabalhos usando a API REST do IoT Central, consulte Como usar a API REST do IoT Central para gerenciar dispositivos.
Dica
Ao criar um trabalho recorrente, entre em seu aplicativo usando uma conta Microsoft ou uma conta do Microsoft Entra. Se você entrar usando um grupo do Microsoft Entra, é possível que o token do Microsoft Entra associado ao grupo expire em algum momento no futuro e faça com que o trabalho falhe.
Criar e executar um trabalho
O exemplo a seguir mostra como criar e executar um trabalho para definir o limite de luz de um grupo de dispositivos. Use o assistente de trabalho para criar e executar trabalhos. Você pode salvar um trabalho para ser executado posteriormente:
Selecione Trabalhos no painel esquerdo.
Selecione + Novo.
Na página Configurar seu trabalho, insira um nome e uma descrição para identificar o trabalho que você está criando.
Se o aplicativo usar organizações, selecione a organização a qual o trabalho deve ser associado. Somente os usuários na organização podem ver ou modificar o trabalho. A função de usuário determina as permissões que o usuário tem.
Selecione o grupo de dispositivos de destino ao qual você deseja aplicar o trabalho. Se seu aplicativo usar organizações, a organização selecionada determinará os grupos de dispositivos disponíveis. É possível ver quantos dispositivos usam sua configuração de trabalho abaixo da caixa de seleção Grupo de dispositivos.
Escolha Propriedade de nuvem, Propriedade, Comando, Alterar modelo de dispositivo ou Alterar manifesto de implantação de borda como o Tipo de trabalho. Para configurar:
- Um trabalho de Propriedade, selecione uma propriedade e defina seu novo valor. Um trabalho de propriedade pode definir várias propriedades.
- Um trabalho de Comando, escolha o comando a ser executado.
- Um trabalho de Alteração de modelo de dispositivo, selecione o modelo de dispositivo para atribuir aos dispositivos no grupo de dispositivos.
- Um trabalho de alteração de manifesto de implantação de borda, selecione o manifesto de implantação do IoT Edge para atribuir aos dispositivos IoT Edge no grupo de dispositivos.
Selecione Salvar e saia para adicionar o trabalho à lista de trabalhos salvos na página Trabalhos. Posteriormente, você pode retornar a um trabalho na lista de trabalhos salvos.
Selecione Avançar para ir para a página Opções de entrega. A página Opções de entrega permite definir as opções de entrega do trabalho: Lotes e Limite de cancelamento:
Os lotes permitem escalonar trabalhos para um grande número de dispositivos. O trabalho é dividido em vários lotes e cada um contém um subconjunto dos dispositivos. Os lotes são enfileirados e executados em sequência.
O limite de cancelamento permite cancelar automaticamente um trabalho se o número de erros exceder o limite definido. O limite pode ser aplicado a todos os dispositivos no trabalho ou a lotes individuais.
Selecione Avançar para ir para a página Agendamento. A página Agendamento permite habilitar um agendamento para executar o trabalho no futuro.
Escolha uma opção de recorrência para o agendamento. É possível configurar o trabalho para ser executado:
- Uma vez
- Diário
- Semanalmente
Defina uma data e hora de início para um trabalho agendado. A data e a hora são específicas do seu fuso horário e não da hora local do dispositivo.
Para encerrar um agendamento recorrente, escolha:
- Neste dia para definir uma data de término para o agendamento.
- Após para definir o número de vezes que o trabalho será executado.
Os trabalhos agendados sempre são executados nos dispositivos em um grupo de dispositivos, mesmo que a associação ao grupo de dispositivos mude ao longo do tempo.
Selecione Avançar para ir à página Revisão. A página Revisão mostra os detalhes de configuração do trabalho. Selecione Agendamento para agendar o trabalho:
A página detalhes do trabalho mostra informações sobre os trabalhos agendados. Quando o trabalho agendado for executado, você verá uma lista das instâncias de trabalho. A execução do trabalho agendado também faz parte da lista de trabalhos Últimos 30 dias.
Nessa página, você pode Desagendar o trabalho ou Editar o trabalho agendado. É possível retornar a um trabalho agendado na lista de trabalhos agendados.
No assistente de trabalho, você pode optar por não agendar um trabalho e executá-lo imediatamente.
Um trabalho passa pelas etapas Pendente, Em execução e Concluído. Os detalhes de execução do trabalho contêm métricas de resultado, detalhes de duração e uma grade da lista de dispositivos.
Quando o trabalho for concluído, você poderá selecionar o Log de resultados para baixar um arquivo CSV dos detalhes do trabalho, incluindo os dispositivos e os status. Essas informações podem ser úteis para solucionar problemas:
O trabalho agora aparece na lista Últimos 30 dias na página Trabalhos. Esta página mostra os trabalhos atualmente em execução e o histórico de todos os trabalhos executados ou salvos anteriormente.
Observação
É possível exibir 30 dias de histórico dos trabalhos executados anteriormente.
Gerenciar trabalhos
Para interromper um trabalho em execução, abra-o e clique em Parar. O status do trabalho é alterado para refletir que ele foi interrompido. A seção Resumo mostra quais dispositivos foram concluídos, falharam ou ainda estão pendentes.
Quando um trabalho está parado, você pode clicar em Continuar para retomar a execução. Você verá que o status do trabalho é alterado para mostrar que ele está novamente em execução. A seção de Resumo continua a ser atualizada com o progresso mais recente.
Copiar um trabalho
Para copiar um trabalho existente, selecione um trabalho executado. Clique em Copiar na página de resultados do trabalho ou na página de detalhes do trabalho. Uma cópia da configuração do trabalho é aberta para você editar e a cópia é anexada ao nome do trabalho.
Exibir status do trabalho
Depois que um trabalho é criado, a coluna Status é atualizada com a mensagem de status de trabalho mais recente. A tabela a seguir lista os status de trabalho possíveis:
| Mensagem de status | Significado do status |
|---|---|
| Concluído | Esse trabalho foi executado em todos os dispositivos. |
| Com falha | Esse trabalho falhou e não foi totalmente executado nos dispositivos. |
| Pendente | Esse trabalho ainda não começou a ser executado em dispositivos. |
| Executando | Esse trabalho está sendo executado nos dispositivos. |
| Interrompido | Um usuário interrompeu manualmente este trabalho. |
| Canceled | Este trabalho foi cancelado porque o limite definido na página Opções de entrega foi excedido. |
A mensagem de status é seguida por uma visão geral dos dispositivos no trabalho. A tabela a seguir lista os valores de status de dispositivo possíveis:
| Mensagem de status | Significado do status |
|---|---|
| Com sucesso | O número de dispositivos em que o trabalho foi executado com êxito. |
| Com falha | O número de dispositivos em que o trabalho não foi executado. |
Para ver o status do trabalho e todos os dispositivos afetados, abra o trabalho. Ao lado de cada nome de dispositivo, você verá uma das seguintes mensagens de status:
| Mensagem de status | Significado do status |
|---|---|
| Concluído | O trabalho foi executado neste dispositivo. |
| Com falha | Houve falha ao executar o trabalho neste dispositivo. A mensagem de erro mostra mais informações. |
| Pendente | O trabalho ainda não foi executado neste dispositivo. |
Para baixar um arquivo CSV que inclui os detalhes do trabalho e a lista de dispositivos e seus valores de status, clique em Log de resultados.
Filtrar a lista de dispositivos
É possível filtrar a lista de dispositivos na página Detalhes do trabalho. Basta selecionar o ícone de filtro. Você pode filtrar o campo ID do dispositivo ou Status:
Personalizar colunas na lista de dispositivos
É possível adicionar colunas à lista de dispositivos. Basta clicar no ícone de opções de coluna:
Use a caixa de diálogo Opções de coluna para escolher as colunas da lista de dispositivos. Selecione as colunas que você deseja exibir, clique na seta para a direita e em OK. Para selecionar todas as colunas disponíveis, escolha Selecionar tudo. As colunas selecionadas aparecem na lista de dispositivos.
As colunas selecionadas persistem em uma sessão de usuário ou em sessões de usuário que têm acesso ao aplicativo.
Executar trabalhos novamente
É possível executar novamente um trabalho que tenha dispositivos com falha. Selecione Executar novamente em um caso de falha.
Insira um nome de trabalho e uma descrição e, em seguida, selecione Executar novamente o trabalho. Um novo trabalho é enviado para repetir a ação em dispositivos com falha.
Observação
Não é possível executar mais de cinco trabalhos ao mesmo tempo em um aplicativo do Azure IoT Central.
Quando um trabalho é concluído e você exclui um dispositivo que está na lista de dispositivos do trabalho, a entrada do dispositivo aparece como excluído no nome do dispositivo. O link de detalhes não está disponível para o dispositivo excluído.
Importar dispositivos
Para registrar um grande número de dispositivos ao seu aplicativo, você pode importar em massa os dispositivos de um arquivo CSV. Você pode encontrar um arquivo CSV de exemplo no repositório de exemplos do Azure. O arquivo CSV deve incluir os seguintes cabeçalhos da coluna:
| Coluna | Descrição |
|---|---|
| IOTC_DEVICEID | A ID do dispositivo é uma identificação exclusiva que este dispositivo usa para se conectar. A identificação do dispositivo pode conter letras, números e o caractere - sem espaços. O tamanho máximo é de 128 caracteres. |
| IOTC_DEVICENAME | Opcional. O nome do dispositivo é um nome amigável exibido em todo o aplicativo. Se não for especificado, o nome do dispositivo será o mesmo que a ID do dispositivo. O tamanho máximo é de 148 caracteres. |
Para dispositivos de registro em massa no aplicativo:
Escolha Dispositivos no painel esquerdo.
No painel esquerdo, escolha o modelo de dispositivo para o qual você deseja criar os dispositivos em massa.
Observação
Se você ainda não tiver um modelo de dispositivo, você pode importar dispositivos em Todos os dispositivos e registrá-los sem um modelo. Depois que os dispositivos foram importados, você pode migrá-los a um modelo.
Selecione Importar.
Selecione uma organização para atribuir os dispositivos. Todos os dispositivos que você está importando são atribuídos à mesma organização. Para atribuir dispositivos a organizações diferentes, crie vários arquivos de importação, um para cada organização. Como alternativa, carregue-os todos na organização raiz e, em seguida, na interface do usuário, reatribua-os às organizações corretas.
Selecione o arquivo CSV que contém a lista de identidades dos dispositivos a serem importados.
A importação do dispositivo é iniciada após o upload do arquivo. Você pode acompanhar o status da importação no painel de Operações de dispositivo. Esse painel aparece automaticamente depois que a importação é iniciada ou você pode acessá-la por meio do ícone de sino no canto superior direito.
Depois que a importação estiver concluída, uma mensagem de êxito será exibida na painel de Operações de dispositivo.
Se a operação de importação do dispositivo falhar, uma mensagem de erro será exibida no painel de Operações de dispositivo. É gerado um arquivo de log captura todos os erros que você pode baixar.
Caso seus dispositivos usem tokens SAS para autenticar, exporte um arquivo CSV do aplicativo IoT Central. O arquivo CSV exportado inclui as IDs de dispositivo e as chaves SAS.
Caso seus dispositivos usem certificados X. 509 para autenticar, gere certificados X. 509 secundários para os dispositivos usando o certificado raiz ou intermediário no seu grupo de registro X.509. Use as identificações do dispositivo importadas como o valor CNAME nos certificados secundários.
Exportar dispositivos
Para conectar um dispositivo real à IoT Central, você precisa de sua cadeia de conexão. Você pode exportar detalhes do dispositivo em massa para obter as informações necessárias para criar strings de conexão de dispositivo. O processo de exportação cria um arquivo CSV com a identidade do dispositivo, o nome do dispositivo e chaves para todos os dispositivos selecionados.
Para exportar em massa os dispositivos do seu aplicativo:
Escolha Dispositivos no painel esquerdo.
No painel esquerdo, escolha o modelo de dispositivo para o qual você deseja exportar os dispositivos.
Selecione os dispositivos que você deseja exportar e, em seguida, selecione a ação de Exportar.
O processo de exportação tem início. Você pode acompanhar o status usando o painel de Operações de dispositivo.
Quando a exportação for concluída, será mostrada uma mensagem com um link para baixar o arquivo gerado.
Selecione o link Baixar Arquivo para baixar o arquivo para uma pasta local no disco.
O arquivo CSV exportado contém as seguintes colunas: ID do dispositivo, nome do dispositivo, chaves de dispositivo e impressões digitais de certificado X509:
- IOTC_DEVICEID
- IOTC_DEVICENAME
- IOTC_SASKEY_PRIMARY
- IOTC_SASKEY_SECONDARY
- IOTC_X509THUMBPRINT_PRIMARY
- IOTC_X509THUMBPRINT_SECONDARY
Para obter mais informações sobre como conectar dispositivos reais ao seu aplicativo IoT Central, confira Como os dispositivos se conectam.
Próximas etapas
Agora que você aprendeu a gerenciar dispositivos em massa no aplicativo do Azure IoT Central, a próxima etapa sugerida é aprender a Editar um modelo de dispositivo.