Tutorial: Provisão para latência de localização geográfica

Este tutorial mostra como provisionar com segurança vários dispositivos de chave simétrica simulados para um grupo de Hubs IoT usando uma política de alocação. O DPS (Serviço de Provisionamento de Dispositivos) do Hub IoT oferece suporte a vários cenários de alocação por meio de suas políticas de alocação internas e seu suporte para políticas de alocação personalizadas.

O provisionamento para geolocalização/latência geográfica é um cenário de alocação comum. À medida que um dispositivo se move entre locais, a latência da rede é melhorada ao ter o dispositivo provisionado para o hub IoT mais próximo de cada local. Nesse cenário, um grupo de hubs IoT, que abrangem várias regiões, são selecionados para inscrições. A política incorporada de alocação de menor latência é selecionada para estas inscrições. Essa política faz com que o Serviço de Provisionamento de Dispositivos avalie a latência do dispositivo e determine o hub IoT mais próximo do grupo de hubs IoT.

Este tutorial usa um exemplo de dispositivo simulado do Azure IoT C SDK para demonstrar como provisionar dispositivos entre regiões. Vai executar os seguintes passos neste tutorial:

Prerequisites

• Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• Conclua as etapas em Guia de início rápido: configurar o Serviço de Provisionamento de Dispositivo do Hub IoT com o portal do Azure.

• Utilize o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale o CLI do Azure. Se estiver a usar Windows ou macOS, considere executar o Azure CLI num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se você estiver usando uma instalação local, entre na CLI do Azure usando o comando az login . Para concluir o processo de autenticação, siga os passos exibidos no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.

  • Quando solicitado, instale a extensão do Azure CLI na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.

  • Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

Criar dois hubs IoT regionais

Nesta seção, você cria um grupo de recursos do Azure e dois novos recursos regionais do hub IoT. Um hub IoT é para a região Oeste dos EUA 2 e o outro é para a região Leste dos EUA .

1. No Azure Cloud Shell, crie um grupo de recursos com o seguinte comando az group create :

   az group create --name contoso-us-resource-group --location eastus
   

2. Crie um hub IoT no local eastus e adicione-o ao grupo de recursos criado com o seguinte comando az iot hub create (substitua {unique-hub-name} pelo seu próprio nome exclusivo):

   az iot hub create --name {unique-hub-name} --resource-group contoso-us-resource-group --location eastus --sku S1
   

   Esse comando pode levar alguns minutos para ser concluído.

3. Agora, crie um hub IoT no local westus2 e adicione-o ao grupo de recursos que você criou com o seguinte comando az iot hub create (substitua {unique-hub-name} por seu próprio nome exclusivo):

   az iot hub create --name {unique-hub-name} --resource-group contoso-us-resource-group --location westus2 --sku S1
   

   Esse comando pode levar alguns minutos para ser concluído.

Criar um registro para latência geográfica

Nesta seção, você cria um novo grupo de inscrição para seus dispositivos.

Para simplificar, este tutorial usa o atestado de chave simétrica com a inscrição. Para obter uma solução mais segura, considere usar o atestado de certificado X.509 com uma cadeia de confiança.

1. Entre no portal do Azure e navegue até sua instância do Serviço de Provisionamento de Dispositivo.

2. Selecione Gerenciar inscrições na seção Configurações do menu de navegação.

3. Selecione Adicionar grupo de inscrição.

4. Na guia Registro + provisionamento da página Adicionar grupo de registro, forneça as seguintes informações para configurar os detalhes do grupo de registro:

   Field	Description
   Attestation	Selecione Chave simétrica como o mecanismo de atestado.
   Configurações de chave simétrica	Marque a caixa Gerar chaves simétricas automaticamente .
   Nome do grupo	Nomeie seu grupo contoso-us-devices ou forneça seu próprio nome de grupo. O nome do grupo de inscrição é uma cadeia de caracteres que não diferencia maiúsculas de minúsculas (até 128 caracteres) de caracteres alfanuméricos mais os caracteres especiais: '-', '.', '_', ':'. O último caractere deve ser alfanumérico ou hífen ('-').

5. Selecione Next: Hubs IoT.

6. Use as seguintes etapas para adicionar seus dois hubs IoT ao grupo de registro:

   1. Na guia Hubs IoT da página Adicionar grupo de registro , selecione Adicionar link ao hub IoT na seção Hubs IoT de destino .

   2. Na página Adicionar link ao hub IoT , selecione o hub IoT que você criou na região eastus e atribua-lhe o acesso iothubowner .

   3. Selecione Guardar.

   4. Selecione Adicionar link ao hub IoT novamente e siga as mesmas etapas para adicionar o hub IoT que você criou na região westus2 .

   5. No menu suspenso Hub IoT de destino , selecione ambos os hubs IoT.

7. Para a Política de alocação, selecione Menor latência.

8. Selecione Verificar + criar.

9. No separador Rever + criar, verifique todos os seus valores e, em seguida, selecione Criar.

10. Depois que seu grupo de inscrição for criado, selecione seu nome contoso-us-devices na lista de grupos de registro.

11. Copie a chave primária. Essa chave é usada posteriormente para gerar chaves de dispositivo exclusivas para ambos os dispositivos simulados.

Criar máquinas virtuais regionais Linux

Nesta seção, você cria duas máquinas virtuais (VMs) Linux regionais, uma no Oeste dos EUA 2 e outra no Leste dos EUA 2. Essas VMs executam um exemplo de simulação de dispositivo de cada região para demonstrar o provisionamento de dispositivos para dispositivos de ambas as regiões.

Para facilitar a limpeza, adicione essas VMs ao mesmo grupo de recursos que contém os hubs IoT que foram criados, contoso-us-resource-group.

1. No Azure Cloud Shell, execute o seguinte comando para criar uma VM da região Leste dos EUA depois de fazer as seguintes alterações de parâmetro no comando:

   --name: insira um nome exclusivo para sua VM de dispositivo regional do Leste dos EUA .

   --admin-username: Use seu próprio nome de usuário admin.

   --admin-password: Use sua própria senha de administrador.

   az vm create \
   --resource-group contoso-us-resource-group \
   --name ContosoSimDeviceEast \
   --location eastus \
   --image Canonical:UbuntuServer:18.04-LTS:18.04.201809110 \
   --admin-username contosoadmin \
   --admin-password myContosoPassword2018 \
   --authentication-type password
   --public-ip-sku Standard
   

   Este comando leva alguns minutos para ser concluído.

2. Quando o comando for concluído, copie o valor publicIpAddress para sua VM da região Leste dos EUA.

3. No Azure Cloud Shell, execute o comando para criar uma VM de região West US 2 depois de fazer as seguintes alterações de parâmetro no comando:

   --name: insira um nome exclusivo para sua VM de dispositivo regional West US 2 .

   --admin-username: Use seu próprio nome de usuário admin.

   --admin-password: Use sua própria senha de administrador.

   az vm create \
   --resource-group contoso-us-resource-group \
   --name ContosoSimDeviceWest2 \
   --location westus2 \
   --image Canonical:UbuntuServer:18.04-LTS:18.04.201809110 \
   --admin-username contosoadmin \
   --admin-password myContosoPassword2018 \
   --authentication-type password
   --public-ip-sku Standard
   

   Este comando leva alguns minutos para ser concluído.

4. Quando o comando estiver concluído, copie o valor publicIpAddress para sua VM da região West US 2.

5. Abra dois shells de linha de comando.

6. Conecte-se a uma das VMs regionais em cada shell usando SSH.

   Passe seu nome de usuário admin e o endereço IP público que você copiou como parâmetros para SSH. Digite a senha de administrador quando solicitado.

   ssh contosoadmin@1.2.3.4
   
   contosoadmin@ContosoSimDeviceEast:~$
   

   ssh contosoadmin@5.6.7.8
   
   contosoadmin@ContosoSimDeviceWest:~$
   

Preparar o ambiente de desenvolvimento do Azure IoT C SDK

Nesta seção, você clona o Azure IoT C SDK em cada VM. O SDK contém um exemplo que simula um provisionamento de dispositivo de cada região.

Para cada VM:

1. Instale CMake, g++, gcc e Git usando os seguintes comandos:

   sudo apt-get update
   sudo apt-get install cmake build-essential libssl-dev libcurl4-openssl-dev uuid-dev git-all
   

2. Localize e copie o nome da tag para a versão mais recente do SDK.

3. Clone o SDK do Azure IoT Device para C em ambas as VMs. Use a tag que você encontrou na etapa anterior como o valor para o -b parâmetro, por exemplo: lts_03_2025.

   git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
   cd azure-iot-sdk-c
   git submodule update --init
   

   Esta operação deve demorar vários minutos a ser concluída.

4. Crie uma nova pasta cmake dentro do repositório e mude para essa pasta.

   mkdir ~/azure-iot-sdk-c/cmake
   cd ~/azure-iot-sdk-c/cmake
   

5. Execute o seguinte comando, que cria uma versão do SDK específica para sua plataforma de cliente de desenvolvimento:

   cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
   

6. Quando a compilação for bem-sucedida, as últimas linhas de saída serão semelhantes à seguinte saída:

   -- IoT Client SDK Version = 1.7.0
   -- Provisioning SDK Version = 1.7.0
   -- Looking for include file stdint.h
   -- Looking for include file stdint.h - found
   -- Looking for include file stdbool.h
   -- Looking for include file stdbool.h - found
   -- target architecture: x86_64
   -- Performing Test CXX_FLAG_CXX11
   -- Performing Test CXX_FLAG_CXX11 - Success
   -- Found OpenSSL: /usr/lib/x86_64-linux-gnu/libcrypto.so (found version "1.1.1")
   -- Found CURL: /usr/lib/x86_64-linux-gnu/libcurl.so (found version "7.58.0")
   -- Found CURL: /usr/lib/x86_64-linux-gnu/libcurl.so
   -- target architecture: x86_64
   -- iothub architecture: x86_64
   -- Configuring done
   -- Generating done
   -- Build files have been written to: /home/contosoadmin/azure-iot-sdk-c/azure-iot-sdk-c
   

Derivar chaves de dispositivo exclusivas

Ao usar o atestado de chave simétrica com inscrições de grupo, você não usa as chaves de grupo de inscrição diretamente. Em vez disso, você deriva, para cada dispositivo, uma chave exclusiva a partir da chave do grupo de registro.

Nesta parte do tutorial, você gera uma chave de dispositivo a partir da chave mestra de grupo para calcular um HMAC-SHA256 do ID de registro exclusivo para o dispositivo. O resultado é então convertido no formato Base64.

Para ambos os dispositivoseastus e westus2:

1. Gere sua chave exclusiva usando openssl. Use o seguinte shell script Bash (substitua {primary-key} pela Chave Primária do grupo de registro que você copiou anteriormente e substitua {contoso-simdevice}por sua própria ID de registro exclusiva para cada dispositivo. O ID de registo é uma cadeia de caracteres que não diferencia maiúsculas de minúsculas (até 128 caracteres) de carateres alfanuméricos mais os carateres especiais: '-', '.', '_', ':'. O último caractere deve ser alfanumérico ou hífen ('-').

   KEY={primary-key}
   REG_ID={contoso-simdevice}
   
   keybytes=$(echo $KEY | base64 --decode | xxd -p -u -c 1000)
   echo -n $REG_ID | openssl sha256 -mac HMAC -macopt hexkey:$keybytes -binary | base64
   

2. O script produz algo como a seguinte chave:

   p3w2DQr9WqEGBLUSlFi1jPQ7UWQL4siAGy75HFTFbf8=
   

3. Agora, cada dispositivo tem sua própria chave de dispositivo derivada e ID de registro exclusivo para executar o atestado de chave simétrica com o grupo de registro durante o processo de provisionamento.

Simule os dispositivos de cada região

Nesta seção, você atualiza um exemplo de provisionamento no Azure IoT C SDK para ambas as VMs regionais.

O código de exemplo simula uma sequência de inicialização de dispositivo que envia a solicitação de provisionamento para sua instância do Serviço de Provisionamento de Dispositivo. A sequência de inicialização faz com que o dispositivo seja reconhecido e atribuído ao hub IoT mais próximo com base na latência.

1. No portal do Azure, selecione a guia Visão geral do seu Serviço de Provisionamento de Dispositivo e anote o valor do Escopo da ID .

   

2. Em ambos os VMS, abra ~/azure-iot-sdk-c/provisioning_client/samples/prov_dev_client_sample/prov_dev_client_sample.c para edição.

   vi ~/azure-iot-sdk-c/provisioning_client/samples/prov_dev_client_sample/prov_dev_client_sample.c
   

3. Em ambas as VMs, localize a id_scope constante e substitua o valor pelo valor do Escopo de ID copiado anteriormente.

   static const char* id_scope = "0ne00002193";
   

4. Em ambas as VMs, localize a definição para a main() função no mesmo arquivo. Verifique se a hsm_type variável está definida como SECURE_DEVICE_TYPE_SYMMETRIC_KEY conforme mostrado no exemplo de código a seguir para corresponder ao método de atestado do grupo de inscrição.

   Salve suas alterações nos arquivos em ambas as VMs.

   SECURE_DEVICE_TYPE hsm_type;
   //hsm_type = SECURE_DEVICE_TYPE_TPM;
   //hsm_type = SECURE_DEVICE_TYPE_X509;
   hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
   

5. Em ambas as VMs, encontre a chamada para prov_dev_set_symmetric_key_info() em prov_dev_client_sample.c que está comentada.

   // Set the symmetric key if using they auth type
   //prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
   

   Descomente as chamadas de função e substitua os valores de espaço reservado (incluindo os colchetes angulares) pelos IDs de registro exclusivos e chaves de dispositivo derivadas para cada dispositivo derivado na seção anterior. As teclas mostradas nas chamadas de função a seguir são exemplos. Use as chaves geradas anteriormente.

   Leste dos EUA:

   // Set the symmetric key if using they auth type
   prov_dev_set_symmetric_key_info("contoso-simdevice-east", "p3w2DQr9WqEGBLUSlFi1jPQ7UWQL4siAGy75HFTFbf8=");
   

   Oeste dos EUA:

   // Set the symmetric key if using they auth type
   prov_dev_set_symmetric_key_info("contoso-simdevice-west", "J5n4NY2GiBYy7Mp4lDDa5CbEe6zDU/c62rhjCuFWxnc=");
   

6. Em ambas as VMs, salve o arquivo.

7. Em ambas as VMs, navegue até a pasta de exemplo mostrada no script Bash a seguir e crie o exemplo.

   cd ~/azure-iot-sdk-c/cmake/provisioning_client/samples/prov_dev_client_sample/
   cmake --build . --target prov_dev_client_sample --config Debug
   

8. Quando a compilação for bem-sucedida, execute prov_dev_client_sample.exe em ambas as VMs para simular um dispositivo de cada região. Observe que cada dispositivo é alocado para o hub IoT mais próximo da região do dispositivo simulado.

   Execute a simulação:

   ~/azure-iot-sdk-c/cmake/provisioning_client/samples/prov_dev_client_sample/prov_dev_client_sample
   

   Exemplo de saída da VM do Leste dos EUA:

   contosoadmin@ContosoSimDeviceEast:~/azure-iot-sdk-c/cmake/provisioning_client/samples/prov_dev_client_sample$ ./prov_dev_client_sample
   Provisioning API Version: 1.2.9
   
   Registering Device
   
   Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
   Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
   Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
   
   Registration Information received from service: contoso-east-hub.azure-devices.net, deviceId: contoso-simdevice-east
   Press enter key to exit:
   
   

   Exemplo de saída da Máquina Virtual do Oeste Ocidental dos EUA

   contosoadmin@ContosoSimDeviceWest:~/azure-iot-sdk-c/cmake/provisioning_client/samples/prov_dev_client_sample$ ./prov_dev_client_sample
   Provisioning API Version: 1.2.9
   
   Registering Device
   
   Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
   Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
   Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
   
   Registration Information received from service: contoso-west-hub.azure-devices.net, deviceId: contoso-simdevice-west
   Press enter key to exit:
   

Limpeza de recursos

Se você planeja continuar trabalhando com recursos criados neste tutorial, você pode deixá-los. Caso contrário, use as etapas a seguir para excluir todos os recursos criados por este tutorial para evitar cobranças desnecessárias.

As etapas aqui pressupõem que você criou todos os recursos neste tutorial conforme instruído no mesmo grupo de recursos chamado contoso-us-resource-group.

Para excluir o grupo de recursos pelo nome:

1. Inicie sessão no portal Azure.

2. Selecione Grupos de recursos.

3. Na caixa de texto Filtrar por nome..., digite o nome do grupo de recursos que contém seus recursos, contoso-us-resource-group.

4. À direita do seu grupo de recursos na lista de resultados, selecione ... e, em seguida , Excluir grupo de recursos.

5. É-lhe pedido que confirme a eliminação do grupo de recursos. Digite o nome do grupo de recursos novamente para confirmar e selecione Excluir. Após alguns instantes, o grupo de recursos e todos os recursos contidos no mesmo são eliminados.

Próximos passos

Para saber mais sobre políticas de alocação personalizadas, consulte