Tutorial: provisionar dispositivos usando grupos de registro de chave simétrica

Artigo
03/20/2024

Este tutorial mostra como provisionar com segurança vários dispositivos de chave simétrica para um único Hub IoT usando um grupo de registro.

O Serviço de Provisionamento de Dispositivos no Hub IoT do Azure dá suporte a dois tipos de registros para provisionar dispositivos:

Grupos de registros: usados para inscrever vários dispositivos relacionados. Este tutorial demonstra o provisionamento com grupos de registro.
Registros individuais: usados para inscrever um único dispositivo.

O Serviço de Provisionamento de Dispositivos no Hub IoT do Azure dá suporte a três formas de autenticação para dispositivos de provisionamento:

Certificados X.509
Trusted Platform Module (TPM)
Chaves simétricas – Este tutorial demonstra o atestado de chave simétrica

Alguns dispositivos talvez não tenham um certificado, TPM ou qualquer outro recurso de segurança que possa ser usado para identificar o dispositivo com segurança. Para esses dispositivos, o DPS (Serviço de Provisionamento de Dispositivos) no Hub IoT do Azure inclui atestado de chave simétrica. O atestado de chave simétrica pode ser usado para identificar um dispositivo com base em informações exclusivas, como o endereço MAC ou um número de série.

Neste tutorial, você concluirá os seguintes objetivos:

Definir uma ID de registro exclusiva para cada dispositivo.
Criar um grupo de registro que usa o atestado de chave simétrica.
Produzir uma chave de dispositivo para cada dispositivo usando sua ID de registro exclusiva e a chave de grupo de registro compartilhada.
Provisionar dispositivos usando a chave de dispositivo e o código de exemplo nos SDKs do dispositivo IoT do Azure.

Este tutorial é orientado para uma estação de trabalho baseada no Windows. No entanto, é possível executar os procedimentos no Linux. Para obter um exemplo de Linux, confira Tutorial: Provisão para latência geográfica.

Observação

Se você já concluiu o Guia de início rápido: provisionar um dispositivo de chave simétrica simulado e ainda tem os recursos do Azure e o ambiente de desenvolvimento configurados, continue para Criar um grupo de registro de chave simétrica neste tutorial.

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.

Se você estiver usando um ambiente de desenvolvimento do Windows, instale o Visual Studio 2022 com a carga de trabalho "Desenvolvimento de área de trabalho com C++" habilitada. Também há suporte para o Visual Studio 2019, o Visual Studio 2017 e o Visual Studio 2015. Para Linux ou macOS, confira a seção apropriada em Preparar seu ambiente de desenvolvimento na documentação do SDK.
Instale o sistema de build CMake mais recente. Certifique-se de marcar a opção que adiciona o executável CMake ao seu caminho.

Importante

Confirme que os pré-requisitos do Visual Studio (Visual Studio e a carga de trabalho de 'Desenvolvimento para Desktop com C++') estão instalados no computador antes de iniciar a instalação de CMake. Após a instalação dos pré-requisitos e verificação do download, instale o sistema de compilação CMake. Além disso, esteja ciente de que as versões mais antigas do sistema de build CMake não geram o arquivo de solução usado neste artigo. Use a versão mais recente do CMake.

Instale o SDK do .NET 6.0 ou posterior no computador baseado no Windows. Use o comando a seguir para verificar a versão.
```
dotnet --info
```

Instale o Node.js v4.0+.

Instale o Python 3.7 ou posterior no computador baseado no Windows. Verifique sua versão do Python executando python --version.

Instale o Java SE Development Kit 8 ou posterior no computador.
Baixe e instale o Maven.

Instale a versão mais recente do Git. Verifique se o Git foi adicionado às variáveis de ambiente que podem ser acessadas pela janela de comando. Confira Ferramentas de cliente Git do Software Freedom Conservancy para obter a versão mais recente das ferramentas git a serem instaladas, que inclui o Git Bash, o aplicativo de linha de comando que você pode usar para interagir com seu repositório Git local.

Preparar seu ambiente de desenvolvimento

Nesta seção, você vai preparar um ambiente de desenvolvimento para criar o SDK do dispositivo IoT do Azure para C. O código de exemplo provisiona o dispositivo durante a sequência de inicialização do dispositivo.

Em um navegador da Web, acesse a página de versão do SDK de C do Azure IoT.
Copie o nome da marca para a versão mais recente do SDK de C de Azure IoT, por exemplo: lts_03_2024.
Abra o prompt de comando do Windows e execute os seguintes comandos para clonar a última versão do repositório GitHub do SDK do dispositivo IoT do Azure para C. Substitua <release-tag> pela marca que você copiou na etapa anterior.
```
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 pode levar vários minutos para ser concluída.
Quando a operação for concluída, execute os seguintes comandos no diretório azure-iot-sdk-c:
```
mkdir cmake
cd cmake
```
O exemplo de código usa uma chave simétrica para fornecer atestado. Execute o seguinte comando para compilar uma versão do SDK específica para sua plataforma de cliente de desenvolvimento que inclui o cliente de provisionamento de dispositivos:
```
cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
```
Dica

Se cmake não encontrar o compilador do C++, você poderá obter erros de build ao executar o comando acima. Se isso acontecer, tente executar o comando no prompt de comando do Visual Studio.

Quando o build for concluído com êxito, as últimas linhas da saída serão semelhantes à seguinte saída:

$ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 16 2019
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22621.
-- The C compiler identification is MSVC 19.29.30146.0
-- The CXX compiler identification is MSVC 19.29.30146.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: C:/azure-iot-sdk-c/cmake

Abrir um prompt de comando ou terminal do Git Bash.
Clone o repositório do GitHub do SDK da IoT do Azure para C# usando o seguinte comando:
```
git clone https://github.com/Azure/azure-iot-sdk-csharp.git
```

Abrir um prompt de comando ou terminal do Git Bash.
Clone o repositório GitHub SDK do Azure IoT para Node.js usando o seguinte comando:
```
git clone https://github.com/Azure/azure-iot-sdk-node.git --recursive
```

Abrir um prompt de comando ou terminal do Git Bash.
Clone o repositório GitHub SDK do Dispositivo IoT do Azure para Python usando o seguinte comando:
```
git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive
```
Observação

Os exemplos usados neste tutorial estão na ramificação v2 do repositório azure-iot-sdk-python. A V3 do SDK do Python está disponível para uso na versão beta. Para obter informações sobre como atualizar exemplos de código V2 para usar uma versão V3 do SDK do Python, consulte Guia de migração de SDK do Dispositivo IoT do Azure para Python.

Abrir um prompt de comando ou terminal do Git Bash.
Clone o repositório GitHub SDK do Azure IoT para Java usando o seguinte comando:
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```
Acesse o diretório azure-iot-sdk-java raiz e crie o projeto para baixar todos os pacotes necessários. Essa etapa pode levar vários minutos para ser concluída.
```
cd azure-iot-sdk-java
mvn install -DskipTests=true
```

Criar um grupo de registro de chave simétrica

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 se você quiser usar chaves geradas aleatoriamente. Desmarque essa caixa se quiser fornecer suas próprias chaves.
Nome do grupo	Forneça um nome para o grupo de dispositivos. 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 (`'-'`).
Status do provisionamento	Marque a caixa Habilitar este registro se quiser que esse grupo de registro esteja disponível para provisionar dispositivos. Desmarque essa caixa se quiser que o grupo seja desabilitado. Você poderá alterar essa configuração mais tarde.
Reprovisionar política	Escolha uma política de reprovisionamento que reflita como você deseja que o DPS manipule os dispositivos que solicitam o reprovisionamento. Para obter mais informações, veja as Políticas de reprovisionamento

Captura de tela que mostra a adição de um grupo de registro para o atestado da chave simétrica.

Selecione Próximo: hubs IoT.

Na guia hubs IoT da página Adicionar grupo de registro, forneça as seguintes informações para determinar para quais hubs IoT o grupo de registro pode provisionar dispositivos:

Campo	Descrição
Hubs IoT de destino	Selecione um ou mais dos hubs IoT vinculados ou adicione um novo link a um hub IoT. Para saber mais sobre como vincular hubs IoT à instância do DPS, confira Como vincular e gerenciar hubs IoT.
Política de alocação	Se você selecionou mais de um hub IoT vinculado, selecione como deseja atribuir dispositivos aos diferentes hubs. Para saber mais sobre políticas de alocação, confira Como usar políticas de alocação. Se você selecionou apenas um hub IoT vinculado, recomendamos usar a política de distribuição uniformemente ponderada.

Captura de tela que mostra a conexão de hubs IoT ao novo grupo de registro.

Selecione Avançar: Configurações do dispositivo

Na guia Configurações do dispositivo da página Adicionar grupo de registro, forneça as seguintes informações para definir como os dispositivos provisionados recentemente serão configurados:

Campo	Descrição
IoT Edge	Marque a caixa Habilitar IoT Edge em dispositivos provisionados se todos os dispositivos provisionados por meio desse grupo executarão o Azure IoT Edge. Desmarque essa caixa se esse grupo for somente para dispositivos não habilitados para IoT Edge. Todos os dispositivos em um grupo serão habilitados para IoT Edge ou nenhum poderá ser.
Marcas de dispositivo	Use esta caixa de texto para fornecer as marcas que deseja aplicar aos dispositivos gêmeos dos dispositivos provisionados.
Propriedades desejadas	Use esta caixa de texto para fornecer as propriedades desejadas que você quer aplicar aos dispositivos gêmeos dos dispositivos provisionados.

Para saber mais, veja Noções básicas e uso de dispositivos gêmeos no Hub IoT.

Selecione Avançar: Revisar + criar.
Na guia Examinar + criar, verifique todos os valores e selecione Criar.

Quando você cria o grupo de registro, o DPS gera uma chave primária e uma chave secundária e as adiciona à entrada de registro. Seu grupo de registro de chave simétrica é exibido na coluna Nome do Grupo na guia Grupos de Registro.

Abra o registro e copie o valor da Chave Primária. Essa chave é a sua chave de grupo.

Escolher uma ID de registro exclusiva para o dispositivo

Uma ID de registro exclusiva deve ser definida para identificar cada dispositivo. Você pode usar o endereço MAC, o número de série ou qualquer informação exclusiva do dispositivo.

Neste exemplo, usamos uma combinação de um endereço MAC e o número de série que formam a seguinte cadeia de caracteres de uma ID de registro.

sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6

Crie IDs de registro exclusivas para cada dispositivo. A ID de registro é uma cadeia de caracteres que não diferencia maiúsculas de minúsculas (até 128 caracteres) de caracteres alfanuméricos e os seguintes caracteres especiais: - . _ :. O último caractere deve ser alfanumérico ou um traço (-).

Derivar uma chave de dispositivo

Para gerar chaves do dispositivo, use a chave primária do grupo de registro para calcular um hash HMAC-SHA256 da ID de registro de cada dispositivo. Em seguida, o resultado é convertido no formato Base 64 para cada dispositivo.

Aviso

O código do dispositivo para cada dispositivo deve incluir apenas a chave de dispositivo derivada para esse dispositivo. Não inclua a chave primária do grupo no código de dispositivo. Uma chave de grupo comprometida tem o potencial de comprometer a segurança de todos os dispositivos que estão sendo autenticados com ela.

A extensão de IoT para a CLI do Azure fornece o comando az iot dps enrollment-group compute-device-key para gerar chaves de dispositivo derivadas. Esse comando pode ser usado em sistemas baseados no Windows e no Linux.

Substitua o valor do parâmetro --key pela Chave Primária do seu grupo de registros.

Substitua o valor do parâmetro --registration-id por sua ID de registro.

az iot dps enrollment-group compute-device-key --key <group_primary_key> --registration-id <device_registration_id>

Resultados de exemplo:

"Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc="

No Windows, você poderá usar o PowerShell para gerar a chave de dispositivo derivada, conforme mostrado no exemplo a seguir.

Substitua o valor de KEY pela Chave Primária do seu grupo de registro.

Substitua o valor de REG_ID pela sua ID de registro.

$KEY='<group_primary_key>'
$REG_ID='<device_registration_id>'

$hmacsha256 = New-Object System.Security.Cryptography.HMACSHA256
$hmacsha256.key = [Convert]::FromBase64String($KEY)
$sig = $hmacsha256.ComputeHash([Text.Encoding]::ASCII.GetBytes($REG_ID))
$derivedkey = [Convert]::ToBase64String($sig)
echo "`n$derivedkey`n"

Resultados de exemplo:

Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

No Linux, você poderá usar o openssl para gerar a chave de dispositivo derivada, conforme mostrado no exemplo a seguir.

Substitua o valor de KEY pela Chave Primária do seu grupo de registro.

Substitua o valor de REG_ID pela sua ID de registro.

KEY=<group_primary_key>
REG_ID=<device_registration_id>

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

Resultados de exemplo:

Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

Seu dispositivo usa a chave de dispositivo derivada dele e a ID de registro exclusiva para executar o atestado de chave simétrica com o registro durante o provisionamento.

Preparar e executar o código de provisionamento de dispositivos

Nesta seção, você atualiza o código de exemplo de dispositivo para enviar a sequência de inicialização do dispositivo para a instância do Serviço de Provisionamento de Dispositivos. Essa sequência de inicialização faz com que o dispositivo seja reconhecido, autenticado e atribuído a um hub IoT vinculado à instância do Serviço de Provisionamento de Dispositivos.

O código de provisionamento de exemplo realiza as seguintes tarefas, em ordem:

Autentica seu dispositivo com o recurso de Provisionamento de Dispositivos usando os três seguintes parâmetros:
- O escopo de ID do Serviço de Provisionamento de Dispositivos
- A ID do registro do dispositivo.
- A chave de dispositivo derivada para seu dispositivo.
Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivos.

Para atualizar e executar o exemplo de provisionamento com as informações do seu dispositivo:

No menu principal do seu Serviço de Provisionamento de Dispositivos, selecione Visão geral.
Copie o valor de Escopo da ID.
No Visual Studio, abra o arquivo da solução azure_iot_sdks.sln que foi gerado pela execução do CMake. O arquivo da solução deve estar no seguinte local:
```
\azure-iot-sdk-c\cmake\azure_iot_sdks.sln
```
Dica

Se o arquivo não foi gerado em seu diretório do CMake, verifique se você usou uma versão recente do sistema de build do CMake.
Na janela Gerenciador de Soluções do Visual Studio, acesse a pasta Provision_Samples. Expanda o projeto de exemplo chamado prov_dev_client_sample. Expanda Arquivos de Origem e abra prov_dev_client_sample.c.
Localize a constante id_scope e substitua o valor pelo valor de Escopo de ID copiado do portal do Azure.
```
static const char* id_scope = "0ne00002193";
```
Encontre a definição da função main() no mesmo arquivo. Certifique-se de que a variável hsm_type está configurada para SECURE_DEVICE_TYPE_SYMMETRIC_KEY, conforme mostrado abaixo:
```
SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
//hsm_type = SECURE_DEVICE_TYPE_X509;
hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
```
Localize a chamada para prov_dev_set_symmetric_key_info() em prov_dev_client_sample.c que está comentado.
```
// Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
```
Remova a marca de comentário da chamada de função e substitua os valores de espaço reservado (incluindo os sinais de maior e menor) pela ID de registro escolhida em Escolher uma ID de registro exclusiva para o dispositivo e a chave de dispositivo derivada que você gerou em Derivar uma chave de dispositivo.
```
// Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6", "Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=");
```
Cuidado

Entenda que essa etapa deixa a chave de dispositivo derivada incluída como parte da imagem para cada dispositivo, o que não é uma prática recomendada de segurança. Esse é um motivo por que é preciso geralmente ponderar vantagens e desvantagens entre segurança e facilidade de uso. Você deve examinar completamente a segurança de seus dispositivos com base nos próprios requisitos.
Salve o arquivo.
Clique com botão direito do mouse no projeto prov_dev_client_sample e selecione Definir como Projeto de Inicialização.
No menu do Visual Studio, selecione Depurar>Iniciar sem depuração para executar a solução. Na recompilação do prompt de projeto, selecione Sim para recompilar o projeto antes da execução.

A seguinte saída é um exemplo do dispositivo que se conecta com êxito à instância de Serviço de provisionamento a ser atribuída a um hub IoT:
```
Provisioning API Version: 1.9.1

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-hub-2.azure-devices.net, deviceId: sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
Press enter key to exit:
```

O código de provisionamento de exemplo realiza as seguintes tarefas:

Autentica seu dispositivo com o recurso de Provisionamento de Dispositivos usando os três seguintes parâmetros:
- O escopo de ID do Serviço de Provisionamento de Dispositivos
- A ID do registro do dispositivo.
- A chave de dispositivo derivada para seu dispositivo.
Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivos.
Envia uma mensagem de teste para o hub IoT.

Para atualizar e executar o exemplo de provisionamento com as informações do seu dispositivo:

No menu principal do seu Serviço de Provisionamento de Dispositivos, selecione Visão geral.
Copie o valor de Escopo da ID.

Abra um prompt de comando e acesse o SymmetricKeySample no repositório de SDKs clonados:

cd .\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample

Na pasta SymmetricKeySample, abra Parameters.cs em um editor de texto. Esse arquivo mostra os parâmetros referenciados pelo exemplo. Somente os três primeiros parâmetros obrigatórios são usados neste artigo durante a execução do exemplo. Examine o código deste arquivo. Nenhuma alteração é necessária.

Parâmetro	Obrigatório	Descrição
`--i` ou `--IdScope`	True	O Escopo da ID da instância do DPS
`--r` ou `--RegistrationId`	True	A ID do registro do 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 (`'-'`).
`--p` ou `--PrimaryKey`	True	A chave primária de um registro individual ou a chave de dispositivo derivada de um registro de grupo.
`--g` ou `--GlobalDeviceEndpoint`	Falso	O ponto de extremidade global no qual os dispositivos se conectarão. Usa como padrão `global.azure-devices-provisioning.net`
`--t` ou `--TransportType`	Falso	O transporte a ser usado para se comunicar com a instância de provisionamento de dispositivos. Assume o padrão de `Mqtt`. Os valores possíveis incluem `Mqtt`, `Mqtt_WebSocket_Only`, `Mqtt_Tcp_Only`, `Amqp`, `Amqp_WebSocket_Only`, `Amqp_Tcp_only` e `Http1`.

Na pasta SymmetricKeySample, abra ProvisioningDeviceClientSample.cs em um editor de texto. Esse arquivo mostra como a classe SecurityProviderSymmetricKey funciona com a classe ProvisioningDeviceClient para provisionar o dispositivo de chave simétrica simulada. Examine o código deste arquivo. Nenhuma alteração é necessária.
Compile e execute o código de exemplo usando o seguinte comando:
- Substitua <id-scope> pelo Escopo de ID copiado do portal do Azure.
- Substitua <registration-id> pela ID de registro escolhida em Escolher uma ID de registro exclusiva para o dispositivo.
- Substitua <primarykey> pela chave de dispositivo derivada que você gerou.
```
dotnet run --i <id-scope> --r <registration-id> --p <primarykey>
```

Você deverá ver algo semelhante à saída a seguir. Uma cadeia de caracteres "TestMessage" é enviada ao Hub como uma mensagem de teste.

D:\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample>dotnet run --i 0ne00000A0A --r sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6 --p sbDDeEzRuEuGKag+kQKV+T1QGakRtHpsERLP0yPjwR93TrpEgEh/Y07CXstfha6dhIPWvdD1nRxK5T0KGKA+nQ==

Initializing the device provisioning client...
Initialized for registration Id sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6.
Registering with the device provisioning service...
Registration status: Assigned.
Device sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6 registered to contoso-hub-2.azure-devices.net.
Creating symmetric key authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.

O código de provisionamento de exemplo realiza as seguintes tarefas, em ordem:

Autentica seu dispositivo com o recurso de Provisionamento de Dispositivos usando os quatro seguintes parâmetros:
- PROVISIONING_HOST
- PROVISIONING_IDSCOPE
- PROVISIONING_REGISTRATION_ID
- PROVISIONING_SYMMETRIC_KEY
Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivos.
Envia uma mensagem de telemetria de teste para o hub IoT.

Para atualizar e executar o exemplo de provisionamento com as informações do seu dispositivo:

No menu principal do seu Serviço de Provisionamento de Dispositivos, selecione Visão geral.
Copie o valor de Escopo da ID.
Abra um prompt de comando para executar comandos do Node.js e navegue até o seguinte diretório:
```
cd azure-iot-sdk-node\provisioning\device\samples
```
Na pasta provisionamento/dispositivo/exemplos, abra register_symkey.js e examine o código.

O exemplo é padrão usa MQTT como o protocolo de transporte. Se você quiser usar um protocolo diferente, comente a linha a seguir e remova a marca de comentário da linha para o protocolo apropriado.
```
var ProvisioningTransport = require('azure-iot-provisioning-device-mqtt').Mqtt;
```
Observe que o código de exemplo define um payload personalizado:
```
provisioningClient.setProvisioningPayload({a: 'b'});
```
Você pode comentar esse código, pois ele não é necessário para este tutorial. É possível usar um payload personalizado quando você utiliza um webhook de alocação personalizado para atribuir seu dispositivo a um Hub IoT. Para saber mais, confira Tutorial: Usar políticas de alocação personalizadas.

O método provisioningClient.register() tenta o registro do seu dispositivo.
No prompt de comando, execute os seguintes comandos para definir as variáveis de ambiente usadas pela amostra:
- O primeiro comando define a variável de ambiente PROVISIONING_HOST para o Ponto de extremidade global do dispositivo. Esse ponto de extremidade é o mesmo para todas as instâncias do DPS.
- Substitua <id-scope> pelo Escopo de ID copiado do portal do Azure.
- Substitua <registration-id> pela ID de registro escolhida em Escolher uma ID de registro exclusiva para o dispositivo.
- Substitua <derived-device-key> pela chave de dispositivo derivada que você gerou em Derivar uma chave de dispositivo.
```
set PROVISIONING_HOST=global.azure-devices-provisioning.net
```
```
set PROVISIONING_IDSCOPE=<id-scope>
```
```
set PROVISIONING_REGISTRATION_ID=<registration-id>
```
```
set PROVISIONING_SYMMETRIC_KEY=<derived-device-key>
```
Crie e execute o código de exemplo usando os seguintes comandos:
```
 npm install
```
```
node register_symkey.js
```

Agora você deverá ver algo semelhante à saída a seguir. Uma cadeia de caracteres "Olá, Mundo" é enviada ao hub como uma mensagem de teste.

registration succeeded
assigned hub=contoso-hub-2.azure-devices.net
deviceId=sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
payload=undefined
Client connected
send status: MessageEnqueued

O código de provisionamento de exemplo realiza as seguintes tarefas, em ordem:

Autentica seu dispositivo com o recurso de Provisionamento de Dispositivos usando os quatro seguintes parâmetros:
- PROVISIONING_HOST
- PROVISIONING_IDSCOPE
- PROVISIONING_REGISTRATION_ID
- PROVISIONING_SYMMETRIC_KEY
Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivos.
Envia uma mensagem de teste para o hub IoT.

Para atualizar e executar o exemplo de provisionamento com as informações do seu dispositivo:

No menu principal do seu Serviço de Provisionamento de Dispositivos, selecione Visão geral.
Copie o valor de Escopo da ID.
Abra um prompt de comando e acesse o diretório em que o arquivo de exemplo, provision_symmetric_key.py, está localizado.
```
cd azure-iot-sdk-python\samples\async-hub-scenarios
```
No prompt de comando, execute os seguintes comandos para definir as variáveis de ambiente usadas pela amostra:
- O primeiro comando define a variável de ambiente PROVISIONING_HOST para o Ponto de extremidade global do dispositivo. Esse ponto de extremidade é o mesmo para todas as instâncias do DPS.
- Substitua <id-scope> pelo Escopo de ID copiado do portal do Azure.
- Substitua <registration-id> pela ID de registro escolhida em Escolher uma ID de registro exclusiva para o dispositivo.
- Substitua <derived-device-key> pela chave de dispositivo derivada que você gerou em Derivar uma chave de dispositivo.
```
set PROVISIONING_HOST=global.azure-devices-provisioning.net
```
```
set PROVISIONING_IDSCOPE=<id-scope>
```
```
set PROVISIONING_REGISTRATION_ID=<registration-id>
```
```
set PROVISIONING_SYMMETRIC_KEY=<derived-device-key>
```
Instale a biblioteca azure-iot-device executando o comando a seguir.
```
pip install azure-iot-device
```
Execute o código de exemplo do Python em provision_symmetric_key.py.
```
python provision_symmetric_key.py
```

Agora você deverá ver algo semelhante à saída a seguir. Algumas mensagens de exemplo de telemetria da velocidade do vento também são enviadas para o hub como um teste.

D:\azure-iot-sdk-python\samples\async-hub-scenarios>python provision_symmetric_key.py
The complete registration result is
sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
contoso-hub-2.azure-devices.net
initialAssignment
null
Will send telemetry from the provisioned device
sending message #1
sending message #2
sending message #3
sending message #4
sending message #5
sending message #6
sending message #7
sending message #8
sending message #9
sending message #10
done sending message #1
done sending message #2
done sending message #3
done sending message #4
done sending message #5
done sending message #6
done sending message #7
done sending message #8
done sending message #9
done sending message #10

O código de provisionamento de exemplo realiza as seguintes tarefas, em ordem:

Autentica seu dispositivo com o recurso de Provisionamento de Dispositivos usando os quatro seguintes parâmetros:
- GLOBAL_ENDPOINT
- SCOPE_ID
- REGISTRATION_ID
- SYMMETRIC_KEY
Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivos.
Envia uma mensagem de teste para o hub IoT.

Para atualizar e executar o exemplo de provisionamento com as informações do seu dispositivo:

No menu principal do seu Serviço de Provisionamento de Dispositivos, selecione Visão geral.
Copie o valor de Escopo da ID.
Abra o código de exemplo do dispositivo Java para edição. O caminho completo para o código de exemplo do dispositivo é:

azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-symmetrickey-individual-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningSymmetricKeyIndividualEnrollmentSample.java
Defina o valor das seguintes variáveis para o registro do DPS e do dispositivo:
- Substitua [Your scope ID here] pelo Escopo de ID copiado do portal do Azure.
- Substitua [Your Provisioning Service Global Endpoint here] pelo Ponto de extremidade global do dispositivo: global.azure-devices-provisioning.net. Esse ponto de extremidade é o mesmo para todas as instâncias do DPS.
- Substitua [Enter your Symmetric Key here] pela chave de dispositivo derivada que você gerou em Derivar uma chave de dispositivo.
- Substitua [Enter your Registration ID here] pela ID de registro escolhida em Escolher uma ID de registro exclusiva para o dispositivo.
```
private static final String SCOPE_ID = "[Your scope ID here]";
private static final String GLOBAL_ENDPOINT = "[Your Provisioning Service Global Endpoint here]";
private static final String SYMMETRIC_KEY = "[Enter your Symmetric Key here]";
private static final String REGISTRATION_ID = "[Enter your Registration ID here]";
```
Cuidado

Entenda que essa etapa deixa a chave de dispositivo derivada incluída como parte da imagem para cada dispositivo, o que não é uma prática recomendada de segurança. Esse é um motivo por que é preciso geralmente ponderar vantagens e desvantagens entre segurança e facilidade de uso. Você deve examinar completamente a segurança de seus dispositivos com base nos próprios requisitos.
Abra um prompt de comando para criação. Acesse a pasta de projeto de exemplo de provisionamento do repositório do SDK do Java.
```
cd azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-symmetrickey-individual-sample
```
Compile o exemplo.
```
mvn clean install
```
Vá para a pasta target e execute o arquivo .jar criado. No comando java, substitua o espaço reservado {version} pela versão no nome do arquivo .jar no computador.
```
cd target
java -jar ./provisioning-symmetrickey-individual-sample-{version}-with-deps.jar
```

Agora você deverá ver algo semelhante à saída a seguir.

Starting...
Beginning setup.
WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
2022-10-07 18:14:48,388 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.2
2022-10-07 18:14:48,390 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
Waiting for Provisioning Service to register
2022-10-07 18:14:48,392 INFO (global.azure-devices-provisioning.net-002edcf5-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
2022-10-07 18:14:48,518 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
2022-10-07 18:14:48,521 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using symmetric key
2022-10-07 18:14:49,252 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
2022-10-07 18:14:49,253 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
2022-10-07 18:14:52,459 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
IotHUb Uri : contoso-hub-2.azure-devices.net
Device ID : sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
2022-10-07 18:14:58,424 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-10-07 18:14:58,436 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-10-07 18:14:58,440 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.1
2022-10-07 18:14:58,450 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2022-10-07 18:14:58,471 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2022-10-07 18:14:59,314 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2022-10-07 18:14:59,315 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6/messages/devicebound/#
2022-10-07 18:14:59,378 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6/messages/devicebound/# was acknowledged
2022-10-07 18:14:59,379 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2022-10-07 18:14:59,381 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2022-10-07 18:14:59,383 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2022-10-07 18:14:59,389 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2022-10-07 18:14:59,392 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
2022-10-07 18:14:59,395 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2022-10-07 18:14:59,404 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Sending message from device to IoT Hub...
2022-10-07 18:14:59,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
Press any key to exit...
2022-10-07 18:14:59,409 DEBUG (contoso-hub-2.azure-devices.net-sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6-c32c76d0-Cxn0e70bbf7-8476-441d-8626-c17250585ee6-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
2022-10-07 18:14:59,777 DEBUG (MQTT Call: sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
2022-10-07 18:14:59,779 DEBUG (contoso-hub-2.azure-devices.net-sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6-c32c76d0-Cxn0e70bbf7-8476-441d-8626-c17250585ee6-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] ) with status OK
Message received! Response status: OK

Confirmar o registro de provisionamento de dispositivos

Neste tutorial, você usou a política de alocação de Configuração estática para atribuir dispositivos que se registram no mesmo hub IoT por meio do grupo de registros. No entanto, para alocações em que um dispositivo pode ser provisionado em um dos vários hubs IoT, você pode examinar os registros de registro do grupo a fim de ver para qual hub IoT o dispositivo foi provisionado:

No portal do Azure, acesse a sua instância do DPS.
No menu Configurações, selecione Gerenciar registros.
Selecione Grupos de registro.
Selecione o grupo de registro que você criou para este tutorial.
Na página Detalhes do Grupo de Registro, selecione Status do registro.
Localize a ID do dispositivo para a coluna ID do dispositivo e anote o hub IoT na coluna Hub IoT atribuído.

Você pode selecionar o registro do dispositivo para ver mais detalhes, como o gêmeo inicial atribuído ao dispositivo.

Para verificar o dispositivo no hub IoT:

No portal do Azure, acesse o hub IoT ao qual seu dispositivo foi atribuído.
No menu Gerenciamento de dispositivo, selecione Dispositivos.
Se o dispositivo tiver sido provisionado com êxito, a ID do dispositivo deverá aparecer na lista, com o Status definido como Habilitado. Se você não encontrar seu dispositivo, selecione Atualizar.

Observação

Se você tiver alterado o estado de dispositivo gêmeo inicial do valor padrão no grupo de registros, um dispositivo pode efetuar pull do estado de dispositivo gêmeo desejado do hub e agir de acordo. Para saber mais, veja Noções básicas e uso de dispositivos gêmeos no Hub IoT.

Provisionar mais dispositivos

Para provisionar mais dispositivos por meio do grupo de registros, siga as etapas nas seções anteriores para:

Escolher uma ID de registro exclusiva para o dispositivo.
Derivar uma chave de dispositivo. Como você fez anteriormente, use a chave primária para o grupo de registro como a chave de grupo.
Executar o código de provisionamento de dispositivos. Substitua os artefatos necessários pela nova chave de dispositivo derivada e pela ID de registro.

Limpar os recursos

Se planejar continuar trabalhando e explorando o dispositivo cliente de exemplo, não limpe os recursos criados neste tutorial. Caso contrário, use as etapas a seguir para excluir todos os recursos criados neste tutorial.

Excluir seu grupo de registros

Excluir um grupo de registros não exclui os registros de registro associados a ele. Esses registros órfãos são contabilizados na cota de registros da instância do DPS. Por esse motivo, é uma prática recomendada excluir todos os registros de registro associados a um grupo antes de excluir o grupo de registros propriamente dito.

No portal do Azure, acesse a sua instância do DPS.
No menu Configurações, selecione Gerenciar registros.
Selecione a guia Grupos de registro.
Selecione o nome do grupo de registro usado para este tutorial para abrir a página de detalhes.
Na página Detalhes do registro, selecione Status do registro. Em seguida, marque a caixa de seleção ao lado do cabeçalho da coluna ID do Dispositivo para selecionar todos os registros do grupo de registro. Selecione Excluir na parte superior da página para excluir os registros.
Volte para a página Gerenciar registros.
Marque a caixa de seleção ao lado do nome do grupo de registro que você usou para este tutorial.
Na parte superior da página, selecione Excluir.

Excluir registros de dispositivo do Hub IoT

No portal do Azure, acesse o hub IoT ao qual seu dispositivo foi atribuído.
Selecione Dispositivos na seção Gerenciamento de dispositivos do menu de navegação.
Marque a caixa de seleção ao lado da ID do dispositivo dos dispositivos registrados neste tutorial.
Na parte superior da página, selecione Excluir.

Próximas etapas

Neste tutorial, você provisionou vários dispositivos para um único hub IoT usando um grupo de registro. A seguir, aprenda como provisionar dispositivos IoT em vários hubs.

Tutorial: Gerenciar a atribuição do hub IoT com políticas de alocação personalizadas

Compartilhar via

Tutorial: provisionar dispositivos usando grupos de registro de chave simétrica

Pré-requisitos

Preparar seu ambiente de desenvolvimento

Criar um grupo de registro de chave simétrica

Escolher uma ID de registro exclusiva para o dispositivo

Derivar uma chave de dispositivo

Preparar e executar o código de provisionamento de dispositivos

Confirmar o registro de provisionamento de dispositivos

Provisionar mais dispositivos

Limpar os recursos

Excluir seu grupo de registros

Excluir registros de dispositivo do Hub IoT

Próximas etapas

Comentários

Recursos adicionais