Compartilhar via

Como migrar automaticamente um hub IoT utilizando a CLI do Azure

  • Artigo

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

As etapas deste artigo são úteis se você desejar:

  • Atualizar um Hub IoT do nível gratuito para um nível básico ou padrão.
  • Transferir um Hub IoT para uma nova região.
  • Exportar as informações de estado do Hub IoT para servir de backup.
  • Aumentar o número de partições de um Hub IoT.
  • Configurar um hub para um ambiente de desenvolvimento, em vez de produção.

Comparar 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 processo é adequado para seu cenário.

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

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

  • O processo manual:

    • Migra o registro do seu dispositivo e suas informações de roteamento e ponto de extremidade. Você precisa recriar manualmente outros detalhes da 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.
    • Remove as cadeias de conexão para roteamento e pontos de extremidade de upload de arquivo que usam a autenticação baseada em chave da saída do modelo do ARM, e você precisa adicioná-los manualmente de volta.

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 sua versão de 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 aspectos:

  • Recursos do Azure Resource Manager (ARM). Esse aspecto é 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 de seu hub IoT no portal do Microsoft Azure. As informações capturadas como parte do aspecto do Azure Resource Manager incluem:

    • Tempo de retenção do hub de eventos interno
    • Certificados
    • Propriedades da nuvem para dispositivo
    • Desabilitar a SAS do dispositivo
    • Desabilitar a autenticação local
    • Habilitar as notificações de upload de arquivos
    • Ponto de extremidade de armazenamento do upload de arquivos
    • Identidades
      • Identidades atribuídas pelo usuário
      • Identidades atribuídas pelo sistema (habilitadas ou desabilitadas)
    • Conjuntos de regras de rede
    • Roteamento
      • Pontos de extremidade personalizados
      • Rota de fallback
      • Rotas
    • Marcações

  • Configurações. Este aspecto refere-se aos aspectos de um hub IoT que não são representados em um modelo do ARM. Especificamente, esse aspecto abrange as configurações automáticas de gerenciamento de dispositivos e as implantações do IoT Edge.

  • Dispositivos. Esse aspecto representa as informações no registro do seu dispositivo, que incluem:

    • Identidades dos dispositivo e gêmeos
    • Identidades dos 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ê deseja 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 aspectos exportar.

Parâmetro Detalhes
--aspects Os aspectos do estado a serem exportados. Especifique um ou mais dos valores aceitos: ARM, configurações ou dispositivos. Se esse parâmetro for omitido, todos os três aspectos serão exportados.
--state-file -f O caminho para o arquivo no qual as informações do estado são gravadas.
--replace -r Se esse parâmetro estiver incluído, o comando exportar substituirá o conteúdo do arquivo de estado.
--hub-name -n
or
--login -l		 O nome do hub IoT de origem (-n) ou da 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 do hub de IoT de origem.

O exemplo a seguir exporta todos os aspectos 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 somente os dispositivos e os aspectos 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

Exportar pontos de extremidade

Se você optar por exportar o aspecto do Azure Resource Manager de um hub IoT, o comando exportar recuperará as cadeias de conexão de qualquer ponto de extremidade que tenha autenticação baseada em chave e as incluirá no modelo do ARM de saída.

O comando exportar 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 todas as rotas que usam esse ponto de extremidade não serão exportadas.

Importar o estado de um hub IoT

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

Se você deseja 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 aspectos do estado a serem importados. Especifique um ou mais dos valores aceitos: ARM, configurações ou dispositivos. Se esse parâmetro for omitido, todos os três aspectos serão importados.
--state-file -f O caminho para o arquivo do estado exportado.
--replace -r Se esse parâmetro estiver incluído, o comando importar excluirá o estado atual do hub de destino.
--hub-name -n
or
--login -l		 O nome do hub IoT de destino (-n) ou da 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 do hub de IoT de destino.

O exemplo a seguir importa todos os aspectos para um novo hub IoT, que será criado caso ainda não exista:

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

O exemplo a seguir importa apenas os aspectos 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

Crie um novo hub de IoT com importação do estado

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

Se quiser criar um novo Hub IoT, você deve incluir o aspecto arm no comando importar. Se arm não estiver incluído no comando e o hub de destino não existir, o comando importar falhará.

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

Atualizar um hub IoT existente com a importação do estado

Se o hub IoT de destino já existir, o aspecto arm não será necessário para o comando az iot hub state import. Se você incluir o aspecto arm, 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 do Hubs de Eventos interno
  • Residência de dadosResidência de dados
  • Recursos

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

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

  • ARM: todos os certificados enviados no hub de destino serão excluídos. Se um certificado estiver presente, ele precisará de uma Etag para ser atualizado.
  • Dispositivos: todos os dispositivos e módulos, de borda e que não são de borda, serão excluídos.
  • Configurações: todas as configurações de gerenciamento de dispositivos e implantações do IoT Edge foram 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.

Esse comando envolve as etapas de exportação e importação em um único comando, mas não tem arquivos de saída. Todas as diretrizes 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 comando state migrate.

Se você estiver migrando um registro de dispositivos com vários dispositivos (por exemplo, algumas centenas ou alguns milhares), talvez seja mais fácil e rápido executar os comandos exportar e importar separadamente, em vez de executar o comando migrar.

Parâmetro Detalhes
--aspects Os aspectos do estado a serem migrados. Especifique um ou mais dos valores aceitos: ARM, configurações ou dispositivos. Se esse parâmetro for omitido, todos os três aspectos serão migrados.
--replace -r Se esse parâmetro for incluído, o comando migrar 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 da 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 de 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 da cadeia de conexão do hub IoT de origem (--ol). Se ambos forem fornecidos, a cadeia de conexão terá prioridade. Utilize a cadeia de caracteres de conexão para evitar a necessidade de entrar na sessão da CLI do Azure.
--origin-resource-group --og O nome do grupo de recursos do hub de IoT de origem.

O exemplo a seguir migra todos os aspectos do hub de origem para o hub de destino, que será criado se 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 você não puder exportar ou importar dispositivos ou configurações, verifique se tem acesso a essas propriedades. Uma maneira de verificar seu acesso é executando os comandos az iot hub device-identity list ou az iot hub configuration list.

Se o comando az iot hub state migrate falhar, tente executar os comandos exportar e importar separadamente. Os dois comandos resultam na mesma funcionalidade que o comando migrar sozinho, mas executando-os separadamente, você pode revisar os arquivos de estado criados a partir do comando exportar.

Próximas etapas

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