Partilhar via

Como migrar automaticamente um hub IoT usando a CLI do Azure

  • Artigo

Use a CLI do Azure para migrar um hub IoT para uma nova região, uma nova camada ou uma nova configuração.

As etapas neste artigo são úteis se você quiser:

  • Atualize da camada gratuita para um hub IoT de camada básica ou padrão.
  • Mova um hub IoT para uma nova região.
  • Exporte informações de estado do hub IoT para ter como backup.
  • Aumente o número de partições para um hub IoT.
  • Configure um hub para um ambiente de desenvolvimento, em vez de produção.

Compare as etapas de migração automática e manual

O resultado deste artigo é semelhante a Como migrar um hub IoT do Azure usando modelos do Azure Resource Manager, mas com um processo diferente. Antes de começar, decida qual é o processo certo para o seu cenário.

  • O processo da CLI do Azure (este artigo):

    • Migra o registro do dispositivo, as informações de roteamento e ponto final e outros detalhes de configuração, como implantações do IoT Edge ou configurações de gerenciamento automático de dispositivos.
    • É mais fácil para migrar pequenos números de dispositivos (por exemplo, até 10.000).
    • Não requer uma conta de Armazenamento do Azure.
    • Coleta cadeias de conexão para pontos de extremidade de roteamento e upload de arquivos que usam autenticação baseada em chave e as inclui na saída do modelo ARM.

  • O processo manual:

    • Migra o registro do dispositivo e as informações de roteamento e ponto final. Você precisa recriar manualmente outros detalhes de configuração no novo hub IoT.
    • É mais rápido para migrar um grande número de dispositivos (por exemplo, mais de 100.000).
    • Usa uma conta de Armazenamento do Azure para transferir o registro do dispositivo.
    • Esfrega cadeias de conexão para pontos de extremidade de roteamento e upload de arquivos que usam autenticação baseada em chave da saída do modelo ARM, e você precisa adicioná-los manualmente novamente.

Pré-requisitos

  • CLI do Azure

    Os recursos descritos neste artigo exigem a versão 0.20.0 ou mais recente da extensão azure-iot . Para verificar a versão da extensão, execute az --version. Para atualizar sua extensão, execute az extension update --name azure-iot.

    Se você ainda tiver a extensão azure-cli-iot-ext herdada instalada, remova essa extensão antes de adicionar a extensão azure-iot.

Estado do hub IoT

Quando falamos em migrar o estado de um hub IoT, estamos nos referindo a uma combinação de três aspetos:

  • Recursos do Azure Resource Manager (ARM). Esse aspeto é tudo o que pode ser definido em um modelo de recurso e é a mesma informação que você obteria se exportasse o modelo de recurso do seu hub IoT no portal do Azure. As informações capturadas como parte do aspeto do Azure Resource Manager incluem:

    • Tempo de retenção do hub de eventos integrado
    • Certificados
    • Propriedades da nuvem para o dispositivo
    • Desativar SAS do dispositivo
    • Desativar autenticação local
    • Ativar notificações de carregamento de ficheiros
    • Ponto de extremidade de armazenamento de upload de arquivo
    • Identidades
      • Identidades atribuídas pelo usuário
      • Identidades atribuídas pelo sistema (ativadas ou desativadas)
    • Conjuntos de regras de rede
    • Roteamento
      • Pontos finais personalizados
      • Rota de fallback
      • Rotas
    • Etiquetas

  • Configurações. Esse aspeto é para aspetos de um hub IoT que não são representados em um modelo ARM. Especificamente, esse aspeto abrange configurações de gerenciamento automático de dispositivos e implantações do IoT Edge.

  • Dispositivos. Este aspeto representa as informações no registo do dispositivo, que incluem:

    • Identidades de dispositivos e gêmeos
    • Identidades de módulos e gêmeos

Qualquer propriedade ou configuração do Hub IoT não listada aqui pode não ser exportada ou importada corretamente.

Exportar o estado de um hub IoT

Use o comando az iot hub state export para exportar o estado de um hub IoT para um arquivo JSON.

Se você quiser executar as etapas de exportação e importação em um comando, consulte a seção mais adiante neste artigo para Migrar um hub IoT.

Ao exportar o estado de um hub IoT, você pode escolher quais aspetos exportar.

Parâmetro Detalhes
--aspects Os aspetos estatais para exportar. Especifique um ou mais dos valores aceitos: arm, configurações ou dispositivos. Se esse parâmetro for deixado de fora, todos os três aspetos serão exportados.
--state-file -f O caminho para o arquivo onde as informações de estado são gravadas.
--replace -r Se esse parâmetro for incluído, o comando export substituirá o conteúdo do arquivo de estado.
--hub-name -n
or
--login -l		 O nome do hub IoT de origem (-n) ou a cadeia de conexão do hub IoT de origem (-l). Se ambos forem fornecidos, a cadeia de conexão terá prioridade.
--resource-group -g O nome do grupo de recursos para o hub IoT de origem.

O exemplo a seguir exporta todos os aspetos do estado de um hub IoT para um arquivo chamado myHub-state:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

O exemplo a seguir exporta apenas os dispositivos e os aspetos do Azure Resource Manager do estado de um hub IoT e substitui o conteúdo do arquivo existente:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

Pontos finais de exportação

Se você optar por exportar o aspeto do Azure Resource Manager de um hub IoT, o comando export recuperará as cadeias de conexão para quaisquer pontos de extremidade que tenham autenticação baseada em chave e as incluirá no modelo ARM de saída.

O comando export também verifica todos os pontos de extremidade para verificar se o recurso ao qual ele se conecta ainda existe. Caso contrário, esse ponto de extremidade e quaisquer rotas que usem esse ponto de extremidade não serão exportados.

Importar o estado de um hub IoT

Use o comando az iot hub state import para importar informações de estado de um arquivo exportado para um hub IoT novo ou existente.

Se você quiser executar as etapas de exportação e importação em um comando, consulte a seção mais adiante neste artigo para Migrar um hub IoT.

Parâmetro Detalhes
--aspects Os aspetos estatais a importar. Especifique um ou mais dos valores aceitos: arm, configurações ou dispositivos. Se esse parâmetro for deixado de fora, todos os três aspetos serão importados.
--state-file -f O caminho para o arquivo de estado exportado.
--replace -r Se esse parâmetro estiver incluído, o comando import excluirá o estado atual do hub de destino.
--hub-name -n
or
--login -l		 O nome do hub IoT de destino (-n) ou a cadeia de conexão do hub IoT de destino (-l). Se ambos forem fornecidos, a cadeia de conexão terá prioridade.
--resource-group -g O nome do grupo de recursos para o hub IoT de destino.

O exemplo a seguir importa todos os aspetos para um novo hub IoT, que é criado se ainda não existir:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

O exemplo a seguir importa apenas os aspetos de dispositivos e configurações para um novo hub IoT, que já deve existir, e substitui quaisquer dispositivos e configurações existentes:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

Criar um novo hub IoT com importação de estado

Você pode usar o az iot hub state import comando para criar um novo hub IoT ou para gravar em um hub IoT existente.

Se quiser criar um novo Hub IoT, inclua o arm aspeto no comando import. Se arm não estiver incluído no comando e o hub de destino não existir, o comando import falhará.

Se o hub de destino não existir, o --resource-group parâmetro também será necessário para o comando import.

Atualizar um hub IoT existente com importação de estado

Se o hub IoT de destino já existir, o arm aspeto não será necessário para o az iot hub state import comando. Se você incluir o arm aspeto, todas as propriedades do recurso serão substituídas, exceto as seguintes propriedades que não podem ser alteradas após a criação do hub:

  • Location
  • SKU
  • Contagem de partições de Hubs de Eventos integrada
  • Residência de dados
  • Funcionalidades

Se o --resource-group for especificado no comando import e for diferente do grupo de recursos atual do hub IoT, o comando falhará porque tenta criar um novo hub com o mesmo nome do que já existe.

Se você incluir o --replace sinalizador no comando import, os seguintes aspetos do hub IoT serão removidos do hub de destino antes que o estado do hub seja carregado:

  • ARM: Todos os certificados carregados no hub de destino são excluídos. Se um certificado estiver presente, ele precisa de um etag para ser atualizado.
  • Dispositivos: Todos os dispositivos e módulos, borda e não borda, são excluídos.
  • Configurações: todas as configurações de gerenciamento de dispositivos e implantações do IoT Edge são excluídas.

Migrar um hub IoT

Use o comando az iot hub state migrate para migrar o estado de um hub IoT para um hub IoT novo ou existente.

Este comando encapsula as etapas de exportação e importação em um único comando, mas não tem arquivos de saída. Todas as orientações e limitações descritas nas seções Exportar o estado de um hub IoT e Importar o estado de um hub IoT também se aplicam ao state migrate comando.

Se você estiver migrando um registro de dispositivo com muitos dispositivos (por exemplo, algumas centenas ou alguns milhares), pode ser mais fácil e rápido executar os comandos de exportação e importação separadamente em vez de executar o comando migrar.

Parâmetro Detalhes
--aspects Os aspetos estatais para migrar. Especifique um ou mais dos valores aceitos: arm, configurações ou dispositivos. Se esse parâmetro for deixado de fora, todos os três aspetos serão migrados.
--replace -r Se esse parâmetro for incluído, o comando migrate excluirá o estado atual do hub de destino.
--destination-hub --dh
or
--destination-hub-login --dl		 O nome do hub IoT de destino (--dh) ou a cadeia de conexão do hub IoT de destino (--dl). Se ambos forem fornecidos, a cadeia de conexão terá prioridade.
--destination-resource-group --dg Nome do grupo de recursos para o hub IoT de destino. O grupo de recursos de destino será necessário se o hub de destino não existir.
--origin-hub --oh
or
--origin-hub-login --ol		 O nome do hub IoT de origem (--oh) ou a cadeia de conexão do hub IoT de origem (--ol). Se ambos forem fornecidos, a cadeia de conexão terá prioridade. Use a cadeia de conexão para evitar ter que entrar na sessão da CLI do Azure.
--origin-resource-group --og O nome do grupo de recursos para o hub IoT de origem.

O exemplo a seguir migra todos os aspetos do hub de origem para o hub de destino, que é criado se ele não existir:

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

Solucionar problemas de migração

Se não for possível exportar ou importar dispositivos ou configurações, verifique se você tem acesso a essas propriedades. Uma maneira de verificar seu acesso é executando os az iot hub device-identity list comandos or az iot hub configuration list .

Se o az iot hub state migrate comando falhar, tente executar os comandos export e import separadamente. Os dois comandos resultam na mesma funcionalidade que o comando migrate sozinho, mas ao executá-los separadamente você pode revisar os arquivos de estado criados a partir do comando export.

Próximos passos

Para obter mais informações sobre como executar operações em massa no registro de identidade em um hub IoT, consulte Importar e exportar identidades de dispositivo do Hub IoT.