Como migrar automaticamente um hub IoT com a CLI do Azure

  • Artigo

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

Os passos neste artigo são úteis se quiser:

  • Atualize do escalão gratuito para um hub IoT de escalão básico ou standard.
  • Mover um hub IoT para uma nova região.
  • Exporte as informações de estado do hub IoT para ter como cópia de segurança.
  • Aumente o número de partições para um hub IoT.
  • Configure um hub para um ambiente de desenvolvimento, em vez de produção.

Comparar os passos de migração automática e manual

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

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

    • Migra o registo do dispositivo, as informações de encaminhamento e ponto final e outros detalhes de configuração, como implementações IoT Edge ou configurações automáticas de gestão de dispositivos.
    • É mais fácil para migrar um pequeno número de dispositivos (por exemplo, até 10 000).
    • Não requer uma conta de Armazenamento do Azure.
    • Recolhe cadeias de ligação para encaminhamento e pontos finais de carregamento de ficheiros e inclui-as na saída do modelo arm.

  • O processo manual:

    • Migra o registo do dispositivo e as informações de encaminhamento e ponto final. Tem de 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).
    • Utiliza uma conta de Armazenamento do Azure para transferir o registo do dispositivo.
    • Limpa as cadeias de ligação para os pontos finais de encaminhamento e carregamento de ficheiros a partir da saída do modelo do ARM e tem de voltar a adicioná-las manualmente.

Pré-requisitos

  • CLI do Azure

    As funcionalidades descritas neste artigo requerem 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 a extensão, execute az extension update --name azure-iot.

    Se ainda tiver a extensão azure-cli-iot-ext legada 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, referimo-nos a uma combinação de três aspetos:

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

    • Tempo de retenção do hub de eventos incorporado
    • Certificados
    • Propriedades da cloud para o dispositivo
    • Desativar SAS do dispositivo
    • Desativar autenticação local
    • Ativar notificações de carregamento de ficheiros
    • Ponto final de armazenamento de carregamento de ficheiros
    • Identidades
      • Identidades atribuídas pelo utilizador
      • Identidades atribuídas pelo sistema (ativadas ou desativadas)
    • Conjuntos de regras de rede
    • Encaminhamento
      • Pontos finais personalizados
      • Rota de contingência
      • Rotas
    • Etiquetas

  • Configurações. Este aspeto destina-se a aspetos de um hub IoT que não estão representados num modelo do ARM. Especificamente, este aspeto abrange as configurações automáticas de gestão de dispositivos e implementações de IoT Edge.

  • Dispositivos. Este aspeto representa as informações no seu registo de dispositivos, que incluem:

    • Identidades de dispositivos e duplos
    • Identidades de módulos e duplos

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

Exportar o estado de um hub IoT

Utilize o comando az iot hub state export para exportar o estado de um hub IoT para um ficheiro JSON.

Se quiser executar os passos de exportação e importação num comando, consulte a secção mais adiante neste artigo para Migrar um hub IoT.

Ao exportar o estado de um hub IoT, pode escolher os aspetos a exportar.

Parâmetro Detalhes
--aspects Os aspetos do estado a exportar. Especifique um ou mais dos valores aceites: arm, configurações ou dispositivos. Se este parâmetro for deixado de fora, os três aspetos serão exportados.
--state-file -f O caminho para o ficheiro onde as informações de estado são escritas.
--replace -r Se este parâmetro estiver incluído, o comando de exportação substitui o conteúdo do ficheiro de estado.
--hub-name -n
ou
--login -l		 O nome do hub IoT de origem (-n) ou a cadeia de ligação do hub IoT de origem (-l). Se ambos forem fornecidos, a cadeia de ligação tem prioridade.
--resource-group -g O nome do grupo de recursos do hub IoT de origem.

O exemplo seguinte exporta todos os aspetos do estado de um hub IoT para um ficheiro com o nome myHub-state:

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

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

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

Exportar pontos finais

Se optar por exportar o aspeto Resource Manager do Azure de um hub IoT, o comando de exportação obtém as cadeias de ligação para quaisquer pontos finais que tenham autenticação baseada em chaves e inclua-as no modelo arm de saída.

O comando de exportação também verifica todos os pontos finais para verificar se o recurso ao qual se liga ainda existe. Caso contrário, esse ponto final e quaisquer rotas que utilizem esse ponto final não serão exportadas.

Importar o estado de um hub IoT

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

Se quiser executar os passos de exportação e importação num comando, consulte a secção mais adiante neste artigo para Migrar um hub IoT.

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

O exemplo seguinte 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 seguinte importa apenas os aspetos de dispositivos e configurações para um novo hub IoT, que já tem de 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

Pode utilizar o az iot hub state import comando para criar um novo hub IoT ou para escrever num hub IoT existente.

Se quiser criar uma nova Hub IoT, tem de incluir o arm aspeto no comando de importação. Se arm não estiver incluído no comando e o hub de destino não existir, o comando de importação falhará.

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

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

Se o hub IoT de destino já existir, o arm aspeto não é necessário para o az iot hub state import comando. Se 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:

  • Localização
  • SKU
  • Contagem de partições dos Hubs de Eventos incorporadas
  • Residência dos dados
  • Funcionalidades

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

Se incluir o --replace sinalizador no comando de importação, os seguintes aspetos do hub IoT são removidos do hub de destino antes de o estado do hub ser carregado:

  • ARM: todos os certificados carregados no hub de destino são eliminados. Se um certificado estiver presente, precisa de um etag para ser atualizado.
  • Dispositivos: todos os dispositivos e módulos, edge e não edge, são eliminados.
  • Configurações: todas as configurações do ADM e IoT Edge implementações são eliminadas.

Migrar um hub IoT

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

Este comando molda os passos de exportação e importação num único comando, mas não tem ficheiros de saída. Todas as orientações e limitações descritas nas secçõ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 estiver a migrar um registo de dispositivos com muitos dispositivos (por exemplo, algumas centenas ou alguns milhares), poderá considerar 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 do estado a migrar. Especifique um ou mais dos valores aceites: arm, configurações ou dispositivos. Se este parâmetro ficar de fora, os três aspetos serão migrados.
--replace -r Se este parâmetro estiver incluído, o comando migrar elimina o estado atual do hub de destino.
--destination-hub --dh
ou
--destination-hub-login --dl		 O nome do hub IoT de destino (--dh) ou a cadeia de ligação do hub IoT de destino (--dl). Se ambos forem fornecidos, a cadeia de ligação tem prioridade.
--destination-resource-group --dg Nome do grupo de recursos do hub IoT de destino. O grupo de recursos de destino é necessário se o hub de destino não existir.
--origin-hub --oh
ou
--origin-hub-login --ol		 O nome do hub IoT de origem (--oh) ou a cadeia de ligação para o hub IoT de origem (--ol). Se ambos forem fornecidos, a cadeia de ligação tem prioridade. Utilize a cadeia de ligação para evitar ter de iniciar sessão na sessão da CLI do Azure.
--origin-resource-group --og O nome do grupo de recursos do hub IoT de origem.

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

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

Resolver problemas de migração

Se não conseguir exportar ou importar dispositivos ou configurações, verifique se tem acesso a essas propriedades. Uma forma de verificar o seu acesso é ao executar os az iot hub device-identity list comandos ou az iot hub configuration list .

Se o az iot hub state migrate comando falhar, experimente executar os comandos de exportação e importação separadamente. Os dois comandos resultam apenas na mesma funcionalidade que o comando de migração, mas ao executá-los separadamente, pode rever os ficheiros de estado criados a partir do comando exportar.

Passos seguintes

Para obter mais informações sobre como realizar operações em massa no registo de identidades num hub IoT, veja Importar e exportar identidades de dispositivos Hub IoT.