Tutorial: como realizar o provisionamento para latência geográfica

Artigo
04/06/2023

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) no Hub IoT dá suporte a uma variedade de cenários de alocação por meio de suas políticas de alocação internas e do suporte a políticas de alocação personalizadas.

O provisionamento para geolocalização/latência geográfica é um cenário de alocação comum. Como um dispositivo se move entre locais, a latência de rede é aprimorada fazendo com que o dispositivo seja provisionado para o hub IoT mais próximo de cada localização. Nesse cenário, um grupo de hubs de IoT, que se estendem entre regiões, são selecionados para os registros. A política de alocação de Menor latência é selecionada para esses registros. Essa política faz com que o serviço de provisionamento de dispositivos avaliem a latência de dispositivo e determinar o hub IoT fora do grupo de hubs IoT armário.

Este tutorial usa uma amostra de dispositivo simulado com o SDK C da Internet das Coisas do Azure para demonstrar como provisionar dispositivos entre regiões. Neste tutorial, você executará as seguintes etapas:

Usar a CLI do Azure para criar dois hubs IoT regionais (Oeste dos EUA 2 e Leste dos EUA)
Criar um registro que provisiona dispositivos com base na geolocalização (menor latência)
Usar a CLI do Azure para criar duas VMs do Linux regional para agir como dispositivos nas mesmas regiões (Oeste dos EUA 2 e Leste dos EUA 2)
Preparar o ambiente de desenvolvimento para o SDK de C do IoT do Azure em ambas VMs do Linux
Simular os dispositivos e verificar se eles estão provisionados no hub IoT na região mais próxima.

Importante

Algumas regiões podem, de tempos em tempos, impor restrições sobre a criação de Máquinas Virtuais. No momento da elaboração deste guia, as regiões westus2 e eastus permitiam a criação de VMs. Se não for possível criar uma dessas regiões, você poderá tentar uma região diferente. Para saber mais sobre como escolher regiões geográficas do Azure ao criar VMs, confiraregiões para máquinas virtuais no Azure

Pré-requisitos

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Conclua as etapas em Configurar o Serviço de Provisionamento de Dispositivos no Hub IoT com o portal do Azure.

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para saber mais, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Criar dois Hubs IoT regionais

Nesta seção, você criará um grupo de recursos do Azure e dois novos recursos do hub IoT regionais. Um hub IoT será para a região oeste dos EUA 2 e o outro será para a região leste dos EUA.

Importante

É recomendável que você use esse grupo de recurso para todos os recursos criados neste tutorial. Isso facilitará a limpeza após você terminar.

No Azure Cloud Shell, crie um grupo de recursos com o segunte comando az group create:
```
az group create --name contoso-us-resource-group --location eastus
```
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 demorar um pouco para ser concluído.
Agora, crie um hub IoT no local westus2 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 westus2 --sku S1
```
Esse comando pode demorar um pouco para ser concluído.

Criar um registro para a latência geográfica

Nesta seção, você criará um grupo de registros para seus dispositivos.

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

Entre no portal do Azure e navegue até instância do Serviço de Provisionamento de Dispositivos.
Selecione Gerenciar registros na seção Configurações do menu de navegação.
Selecione Adicionar grupo de registros.

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:

Campo	Descrição
Atestado	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 registro é 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 um traço (`'-'`).

Selecione Próximo: hubs IoT.
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 a ele o acesso iothubowner.
3. Clique em Salvar.
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 Hubs IoT de destino, selecione ambos os hubs IoT.
Para a Política de alocação, selecione Menor latência.
Selecione Examinar + criar.
Na guia Revisar + Criar, verifique todos os valores e, em seguida, selecione Criar.
Depois que o grupo de registro for criado, selecione seu nome contoso-us-devices na lista de grupos de registro.
Copie a Chave primária. Essa chave será usada mais tarde para gerar chaves de dispositivo exclusivas para dispositivos simulados.

Criar VMs do Linux regionais

Nesta seção, você criará duas VMs (máquinas virtuais) regionais do Linux, uma no Oeste dos EUA 2 e outra no Leste dos EUA 2. Essas VMs executarão uma amostra de simulação do 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.

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

--nome: insira um nome exclusivo para seu dispositivo regional VM no Leste dos EUA.

nome de usuário-admin-: usar seu próprio nome de usuário administrador.

-- 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
```
Esse comando vai demorar um pouco para ser concluído.
Quando o comando for concluído, copie o valor publicIpAddress para a sua VM de região do Leste dos EUA.
No Azure Cloud Shell, execute o comando para criar uma região Oeste dos EUA 2 de VM depois de fazer as seguintes alterações de parâmetro no comando:

--nome: insira um nome exclusivo para seu dispositivo regional VM no Oeste dos EUA 2.

nome de usuário-admin-: usar seu próprio nome de usuário administrador.

-- 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
```
Esse comando vai demorar um pouco para ser concluído.
Quando o comando for concluído, copie o valor publicIpAddress para a sua VM de região do Oeste dos EUA 2.
Abra dois shells de linha de comando.
Conecte-se para uma das VMs regionais em cada shell usando o SSH.

Passe o seu nome de usuário administrador e o endereço IP público que você copiou como parâmetros para o SSH. Insira a senha de administrador do servidor quando solicitado.
```
ssh contosoadmin@1.2.3.4

contosoadmin@ContosoSimDeviceEast:~$
```
```
ssh contosoadmin@5.6.7.8

contosoadmin@ContosoSimDeviceWest:~$
```

Preparar o ambiente de desenvolvimento do SDK de C do IoT do Azure

Nesta seção, você clonará o SDK do Azure IoT C em cada VM. O SDK contém uma amostra que simula o provisionamento de dispositivos de cada região.

Para cada VM:

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

Localize e copie o nome da tag para a versão mais recente do SDK.
Clonar o SDK do dispositivo IoT do Azure para C nas duas VMs. Use a tag que você encontrou na etapa anterior como o valor para o parâmetro -b, por exemplo: lts_01_2023.
```
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
Essa operação deve demorar alguns minutos.
Crie uma nova pasta cmake dentro do repositório e mude para a pasta.
```
mkdir ~/azure-iot-sdk-c/cmake
cd ~/azure-iot-sdk-c/cmake
```
Execute o comando a seguir, que cria uma versão do SDK específica para a plataforma cliente de desenvolvimento:
```
cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
```

Após o sucesso da compilação, 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 registros em grupo, você não usa as chaves de registro de grupo diretamente. Em vez disso, você deriva uma chave exclusiva da chave do grupo de registro para cada dispositivo.

Nesta parte do tutorial, você gerará uma chave de dispositivo por meio da chave mestra do grupo a fim de calcular um HMAC-SHA256 da ID de registro exclusiva do dispositivo. Em seguida, o resultado será convertido no formato Base64.

Importante

Não inclua a chave mestra de grupo em seu código de dispositivo.

Para tanto dispositivos eastus quanto westus 2:

Gere sua chave exclusiva usando openssl. Você usará o script de shell Bash a seguir (substitua {primary-key}pela Chave Primária do grupo de registro que copiou anteriormente e substitua por {contoso-simdevice} sua própria ID de registro exclusiva para cada dispositivo. A ID do registro é 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 um traço ('-').
```
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
```
O script produzirá algo como a seguinte chave:
```
p3w2DQr9WqEGBLUSlFi1jPQ7UWQL4siAGy75HFTFbf8=
```
Agora, cada dispositivo tem sua própria chave de dispositivo derivada e a ID de registro exclusiva para executar o atestado de chave simétrica com o grupo de registro durante o processo de provisionamento.

Simular os dispositivos de cada região

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

Esse código de exemplo simula uma sequência de inicialização do dispositivo que envia a solicitação de provisionamento à sua instância do Serviço de Provisionamento de Dispositivos. A sequência de inicialização fará com que o dispositivo seja reconhecido e atribuído ao Hub IoT que esteja mais próximo baseado em latência.

No portal do Azure, selecione a guia Visão Geral de seu Serviço de Provisionamento de Dispositivos e anote o valor de Escopo da ID.
Em ambas as 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
```
Em ambos as VMS,localize a constante id_scope e substitua o valor pelo seu valor de Escopo de ID copiado anteriormente.
```
static const char* id_scope = "0ne00002193";
```
Em ambos as VMS, encontre a definição da função main() no mesmo arquivo. Verifique se a hsm_type variável é definida como SECURE_DEVICE_TYPE_SYMMETRIC_KEY conforme mostrado abaixo para coincidir com o método de atestado de grupo de registro.

Salve suas alterações para os 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;
```
Em ambas as VMs, localize a chamada para prov_dev_set_symmetric_key_info() em prov_dev_client_sample.c que é comentado.
```
// Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
```
Remova as marcas de comentário das chamadas de função e substitua os valores de espaço reservado (incluindo os colchetes angulares) pelas IDs de registro exclusivo e chaves de dispositivo derivadas para cada dispositivo que você derivou na seção anterior. As chaves mostradas abaixo são exemplos. Use as chaves que você gerou 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=");
```
Em ambas as VMs, salve o arquivo.

Em ambas as VMs, navegue até a pasta de exemplo mostrada abaixo e compilar o exemplo.

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

Depois que 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 de regiões 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 VM do Oeste 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:

Limpar recursos

Caso planeje continuar a trabalhar com recursos criados neste tutorial, você poderá mantê-los. Caso contrário, use as etapas a seguir para excluir todos os recursos criados por este tutorial, a fim de evitar cobranças desnecessárias.

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

Importante

A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Caso tenha criado o Hub IoT dentro de um grupo de recursos existente que contém recursos que você deseja manter, exclua apenas o próprio recurso do Hub IoT em vez de excluir o grupo de recursos.

Para excluir o grupo de recursos por nome:

Entre no portal do Azure.
Selecione Grupos de recursos.
Na caixa de texto Filtrar por nome..., digite o nome do grupo de recursos que contém seus recursos, contoso-us-resource-group.
À direita do seu grupo de recursos, na lista de resultados, clique em ..., depois em Excluir grupo de recursos.
Você receberá uma solicitação para confirmar a exclusã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 nele, serão excluídos.

Próximas etapas

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

Noções básicas sobre políticas de alocação personalizadas

Tutorial: como realizar o provisionamento para latência geográfica

Pré-requisitos

Criar dois Hubs IoT regionais

Criar um registro para a latência geográfica

Criar VMs do Linux regionais

Preparar o ambiente de desenvolvimento do SDK de C do IoT do Azure

Derivar chaves de dispositivo exclusivas

Simular os dispositivos de cada região

Limpar recursos

Próximas etapas

Recursos adicionais