Share via

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

  • Artigo

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

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

  • Grupos de inscrição: utilizados para inscrever vários dispositivos relacionados. Este tutorial demonstra o provisionamento com grupos de inscrição.
  • Inscrições individuais: usadas para registrar um único dispositivo.

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

  • Certificados X.509
  • Módulo de plataforma confiável (TPM)
  • Chaves simétricas - Este tutorial demonstra o atestado de chave simétrica

Alguns dispositivos podem não ter 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 Serviço de Provisionamento de Dispositivo (DPS) do 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ê conclui os seguintes objetivos:

  • Defina um ID de registro exclusivo para cada dispositivo.
  • Crie um grupo de inscrição que use atestado de chave simétrica.
  • Produza uma chave de dispositivo para cada dispositivo usando sua ID de registro exclusiva e chave de grupo de registro compartilhada.
  • Provisione dispositivos usando a chave do dispositivo e o código de exemplo nos SDKs de dispositivo IoT do Azure.

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

Nota

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

Pré-requisitos

  • 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. Visual Studio 2019, Visual Studio 2017 e Visual Studio 2015 também são suportados. Para Linux ou macOS, consulte a seção apropriada em Prepare your development environment na documentação do SDK.

  • Instale o sistema de compilação CMake mais recente. Certifique-se de marcar a opção que adiciona o executável CMake ao seu caminho.

    Importante

    Confirme se os pré-requisitos do Visual Studio (Visual Studio e a carga de trabalho 'Desenvolvimento de área de trabalho com C++') estão instalados em sua máquina, antes de iniciar a CMake instalação. Depois de os pré-requisitos estarem assegurados e a transferência verificada, instale o sistema de compilação CMake. Além disso, esteja ciente de que versões mais antigas do sistema de compilação CMake não conseguem gerar o arquivo de solução usado neste artigo. Certifique-se de usar a versão mais recente do CMake.

  • Instale o .NET SDK 6.0 ou posterior em sua máquina baseada no Windows. Você pode usar o seguinte comando para verificar sua versão.

    dotnet --info
  • Instale o Python 3.7 ou posterior instalado em sua máquina baseada no Windows. Você pode verificar sua versão do Python executando python --version.
  • Instale a versão mais recente do Git. Certifique-se de que o Git é adicionado às variáveis de ambiente acessíveis à janela de comando. Consulte as ferramentas de cliente Git da Software Freedom Conservancy para obter a versão mais recente das ferramentas a serem instaladas, que inclui o Git Bash, o aplicativo de linha de git comando que você pode usar para interagir com seu repositório Git local.

Preparar o ambiente de desenvolvimento

Nesta seção, você prepara 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.

  1. Em um navegador da Web, vá para a página Versão do SDK do Azure IoT C.

  2. Copie o nome da marca para a versão mais recente do Azure IoT C SDK, por exemplo: lts_03_2024.

  3. Abra um prompt de comando do Windows e execute os seguintes comandos para clonar a versão mais recente do SDK do Dispositivo IoT do Azure para o repositório C GitHub. Substitua <release-tag> pela tag copiada 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

    Esta operação pode levar vários minutos para ser concluída.

  4. Quando a operação estiver concluída, execute os seguintes comandos a azure-iot-sdk-c partir do diretório:

    mkdir cmake
cd cmake

  5. O exemplo de código usa uma chave simétrica para fornecer atestado. Execute o seguinte comando para criar uma versão do SDK específica para sua plataforma de cliente de desenvolvimento que inclua o cliente de provisionamento de dispositivo:

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

    Gorjeta

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

  6. Quando a compilação for concluída com êxito, as últimas linhas de 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

  1. Abra um prompt de comando ou um terminal Git Bash.

  2. Clone o SDK do Azure IoT para repositório GitHub C# usando o seguinte comando:

    git clone https://github.com/Azure/azure-iot-sdk-csharp.git

  1. Abra um prompt de comando ou um terminal Git Bash.

  2. Clone o SDK do Azure IoT para Node.js repositório GitHub usando o seguinte comando:

    git clone https://github.com/Azure/azure-iot-sdk-node.git --recursive

  1. Abra um prompt de comando ou um terminal Git Bash.

  2. Clone o SDK do Dispositivo IoT do Azure para repositório GitHub Python usando o seguinte comando:

    git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

    Nota

    Os exemplos usados neste tutorial estão na ramificação v2 do repositório azure-iot-sdk-python. V3 do Python SDK está disponível para uso em 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 do SDK do Dispositivo IoT do Azure para Python.

  1. Abra um prompt de comando ou um terminal Git Bash.

  2. Clone o repositório do SDK do Azure IoT para Java GitHub usando o seguinte comando:

    git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive

  3. Vá para o diretório raiz azure-iot-sdk-java e construa o projeto para baixar todos os pacotes necessários. Esta etapa pode levar vários minutos para ser concluída.

    cd azure-iot-sdk-java
mvn install -DskipTests=true

Criar um grupo de inscrição de chave simétrica

  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:

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

    Screenshot that shows adding an enrollment group for symmetric key attestation.

  5. Selecione Next: Hubs IoT.

  6. 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 hubs IoT vinculados ou adicione um novo link a um hub IoT. Para saber mais sobre como vincular hubs IoT à sua instância DPS, consulte Como vincular e gerenciar hubs IoT.
    Política de afetaçã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, consulte Como usar políticas de alocação.

    Se você selecionou apenas um hub IoT vinculado, recomendamos usar a política de distribuição ponderada uniformemente.

    Screenshot that shows connecting IoT hubs to the new enrollment group.

  7. Selecione Next: Configurações do dispositivo

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

    Campo Descrição
    IoT Edge Verifique a opção Habilitar o 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 apenas para dispositivos não habilitados para IoT Edge. Todos os dispositivos de um grupo serão habilitados para IoT Edge ou nenhum poderá ser.
    Tags de dispositivo Use esta caixa de texto para fornecer as tags que você deseja aplicar aos gêmeos de dispositivos provisionados.
    Propriedades desejadas Use esta caixa de texto para fornecer as propriedades desejadas que você deseja aplicar aos gêmeos de dispositivos provisionados.

    Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

  9. Selecione Seguinte: Rever + criar.

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

Quando você cria o grupo de registro, o DPS gera uma chave primária e uma chave secundária e, em seguida, adiciona-as à entrada de registro. Seu grupo de inscrição de chave simétrica aparece na coluna Nome do grupo na guia Grupos de Inscrição.

Abra o registro e copie o valor da Chave Primária. Esta chave é a chave do seu grupo.

Escolha um ID de registo exclusivo para o dispositivo

Deve ser definido um ID de registo único para identificar cada dispositivo. Você pode usar o endereço MAC, número de série ou qualquer informação exclusiva do dispositivo.

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

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

Crie IDs de registro exclusivos 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 seguintes carateres especiais: - . _ :. O último caractere deve ser alfanumérico ou traço (-).

Derivar uma chave de dispositivo

Para gerar chaves de dispositivo, use a chave primária do grupo de registro para calcular um hash HMAC-SHA256 da ID de registro de cada dispositivo. O resultado é então 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 do 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 IoT para a CLI do Azure fornece o comando az iot dps enrollment-group compute-device-key para gerar chaves de dispositivo derivadas. Este comando pode ser usado a partir de sistemas baseados em Windows e Linux.

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

Substitua o --registration-id valor do parâmetro pelo seu ID de registro.

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

Exemplo de resultado:

"Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc="

Cada dispositivo usa sua chave de dispositivo derivada e ID de registro exclusivo para executar o atestado de chave simétrica com o grupo de registro durante o provisionamento.

Preparar e executar o código de provisionamento do dispositivo

Nesta seção, você atualiza o código de exemplo do dispositivo para enviar a sequência de inicialização do dispositivo para sua instância do Serviço de Provisionamento de Dispositivo. 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 Dispositivo.

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

  1. Autentica seu dispositivo com seu recurso de provisionamento de dispositivo usando os três parâmetros a seguir:

    • O escopo de ID do seu Serviço de Provisionamento de Dispositivo
    • O ID de registo do seu dispositivo.
    • A chave de dispositivo derivada para o seu dispositivo.

  2. Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivo.

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

  1. No menu principal do seu Serviço de Provisionamento de Dispositivo, selecione Visão geral.

  2. Copie o valor ID Scope .

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. No Visual Studio, abra o ficheiro de solução azure_iot_sdks.sln gerado ao executar o CMake. O ficheiro de solução deve estar na seguinte localização:

    
\azure-iot-sdk-c\cmake\azure_iot_sdks.sln

    Gorjeta

    Se o arquivo não foi gerado em seu diretório cmake, certifique-se de usar uma versão recente do sistema de compilação CMake.

  4. Na janela Gerenciador de Soluções do Visual Studio, vá para 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.

  5. Localize a id_scope constante e substitua o valor pelo valor ID Scope que você copiou do portal do Azure.

    static const char* id_scope = "0ne00002193";

  6. Localize a definição da função main() no mesmo ficheiro. Certifique-se de que a variável hsm_type está definida como 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;

  7. Encontre a chamada para prov_dev_set_symmetric_key_info() em prov_dev_client_sample.c que é comentada.

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

    Descomente a chamada de função e substitua os valores de espaço reservado (incluindo os colchetes angulares) pela ID de registro escolhida em Escolha uma ID de registro exclusiva para o dispositivo e a chave de dispositivo derivada gerada 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=");

    Atenção

    Lembre-se de que esta etapa deixa a chave de dispositivo derivada incluída como parte da imagem de cada dispositivo, o que não é uma prática recomendada de segurança. Esta é uma das razões pelas quais a segurança e a facilidade de utilização são muitas vezes compensações. Deve rever totalmente a segurança dos seus dispositivos com base nos seus próprios requisitos.

  8. Guarde o ficheiro.

  9. Clique com o botão direito do mouse no projeto prov_dev_client_sample e selecione Definir como projeto de inicialização.

  10. No menu do Visual Studio, selecione Debug (Depurar) >Start without debugging (Iniciar sem depuração) para executar a solução. No prompt de reconstrução do projeto, selecione Sim para reconstruir o projeto antes de ser executado.

    A saída a seguir é um exemplo do dispositivo que se conecta com êxito à instância do 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:

  1. Autentica seu dispositivo com seu recurso de provisionamento de dispositivo usando os três parâmetros a seguir:

    • O escopo de ID do seu Serviço de Provisionamento de Dispositivo
    • O ID de registo do seu dispositivo.
    • A chave de dispositivo derivada para o seu dispositivo.

  2. Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivo.

  3. Envia uma mensagem de telemetria de teste para o hub IoT.

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

  1. No menu principal do seu Serviço de Provisionamento de Dispositivo, selecione Visão geral.

  2. Copie o valor ID Scope .

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Abra um prompt de comando e vá para o SymmetricKeySample no repositório clonado do SDK:

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

  4. Na pasta SymmetricKeySample, abra Parameters.cs em um editor de texto. Este arquivo mostra os parâmetros referenciados pelo exemplo. Somente os três primeiros parâmetros necessários são usados neste artigo ao executar o exemplo. Revise o código neste arquivo. Não são necessárias alterações.

    Parâmetro Necessário Description
    --i ou --IdScope True O escopo de ID da instância do DPS
    --r ou --RegistrationId True O ID de registo do 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 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 False O ponto de extremidade global ao qual os dispositivos devem se conectar. O padrão é global.azure-devices-provisioning.net
    --t ou --TransportType False O transporte a ser usado para se comunicar com a instância de provisionamento de dispositivo. O padrão é Mqtt. Os valores possíveis incluem Mqtt, Mqtt_WebSocket_Only, Mqtt_Tcp_Only, Amqp, Amqp_WebSocket_Only, Amqp_Tcp_onlye Http1.

  5. Na pasta SymmetricKeySample, abra ProvisioningDeviceClientSample.cs em um editor de texto. Este arquivo mostra como a classe SecurityProviderSymmetricKey é usada junto com a classe ProvisioningDeviceClient para provisionar seu dispositivo de chave simétrica simulada. Revise o código neste arquivo. Não são necessárias alterações.

  6. Crie e execute o código de exemplo usando o seguinte comando:

    dotnet run --i <id-scope> --r <registration-id> --p <primarykey>

  7. Você deve ver algo semelhante à saída a seguir. Uma cadeia de caracteres "TestMessage" é enviada para o 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, na ordem:

  1. Autentica seu dispositivo com seu recurso de provisionamento de dispositivo usando os quatro parâmetros a seguir:

    • PROVISIONING_HOST
    • PROVISIONING_IDSCOPE
    • PROVISIONING_REGISTRATION_ID
    • PROVISIONING_SYMMETRIC_KEY

  2. Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivo.

  3. Envia uma mensagem de telemetria de teste para o hub IoT.

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

  1. No menu principal do seu Serviço de Provisionamento de Dispositivo, selecione Visão geral.

  2. Copie o valor ID Scope .

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Abra um prompt de comando para executar comandos Node.js e vá para o seguinte diretório:

    cd azure-iot-sdk-node\provisioning\device\samples

  4. Na pasta provisionamento/dispositivo/exemplos, abra register_symkey.js e revise o código.

    O exemplo assume como padrão MQTT como o protocolo de transporte. Se você quiser usar um protocolo diferente, comente a linha a seguir e remova o comentário da linha para o protocolo apropriado.

    var ProvisioningTransport = require('azure-iot-provisioning-device-mqtt').Mqtt;

    Observe também que o código de exemplo define uma carga útil personalizada:

    provisioningClient.setProvisioningPayload({a: 'b'});

    Você pode comentar este código, pois ele não é necessário para este tutorial. Uma carga útil personalizada pode ser usada quando você usa um webhook de alocação personalizado para atribuir seu dispositivo a um Hub IoT. Para obter mais informações, consulte Tutorial: Usar políticas de alocação personalizadas.

    O provisioningClient.register() método tenta o registo do seu dispositivo.

  5. No prompt de comando, execute os seguintes comandos para definir as variáveis de ambiente usadas pelo exemplo:

    • O primeiro comando define a PROVISIONING_HOST variável de ambiente como o ponto de extremidade do dispositivo Global. 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> pelo ID de registro que você escolheu em Escolha um ID de registro exclusivo para o dispositivo.
    • Substitua <defived-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>

  6. Crie e execute o código de exemplo usando os seguintes comandos:

     npm install

    node register_symkey.js

  7. Agora você deve ver algo semelhante à saída a seguir. Uma cadeia de caracteres "Hello World" é enviada para o 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, na ordem:

  1. Autentica seu dispositivo com seu recurso de provisionamento de dispositivo usando os quatro parâmetros a seguir:

    • PROVISIONING_HOST
    • PROVISIONING_IDSCOPE
    • PROVISIONING_REGISTRATION_ID
    • PROVISIONING_SYMMETRIC_KEY

  2. Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivo.

  3. Envia uma mensagem de telemetria de teste para o hub IoT.

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

  1. No menu principal do seu Serviço de Provisionamento de Dispositivo, selecione Visão geral.

  2. Copie o valor ID Scope .

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Abra um prompt de comando e vá para o diretório onde o arquivo de exemplo, provision_symmetric_key.py, está localizado.

    cd azure-iot-sdk-python\samples\async-hub-scenarios

  4. No prompt de comando, execute os seguintes comandos para definir as variáveis de ambiente usadas pelo exemplo:

    • O primeiro comando define a PROVISIONING_HOST variável de ambiente como o ponto de extremidade do dispositivo Global. 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> pelo ID de registro que você escolheu em Escolha um ID de registro exclusivo para o dispositivo.
    • Substitua <defived-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>

  5. Instale a biblioteca azure-iot-device executando o seguinte comando.

    pip install azure-iot-device

  6. Execute o código de exemplo Python no provision_symmetric_key.py.

    python provision_symmetric_key.py

  7. Agora você deve ver algo semelhante à saída a seguir. Alguns exemplos de mensagens de telemetria de 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, na ordem:

  1. Autentica seu dispositivo com seu recurso de provisionamento de dispositivo usando os quatro parâmetros a seguir:

    • GLOBAL_ENDPOINT
    • SCOPE_ID
    • REGISTRATION_ID
    • SYMMETRIC_KEY

  2. Atribui o dispositivo ao hub IoT já vinculado à sua instância do Serviço de Provisionamento de Dispositivo.

  3. Envia uma mensagem de telemetria de teste para o hub IoT.

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

  1. No menu principal do seu Serviço de Provisionamento de Dispositivo, selecione Visão geral.

  2. Copie o valor ID Scope .

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. 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

  4. Defina o valor das seguintes variáveis para seu DPS e registro de 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 de dispositivo global: 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] pelo ID de registro que você escolheu em Escolha um ID de registro exclusivo 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]";

    Atenção

    Lembre-se de que esta etapa deixa a chave de dispositivo derivada incluída como parte da imagem de cada dispositivo, o que não é uma prática recomendada de segurança. Esta é uma das razões pelas quais a segurança e a facilidade de utilização são muitas vezes compensações. Deve rever totalmente a segurança dos seus dispositivos com base nos seus próprios requisitos.

  5. Abra um prompt de comando para a construção. Vá para a pasta de projeto de exemplo de provisionamento do repositório Java SDK.

    cd azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-symmetrickey-individual-sample

  6. Compile o exemplo.

    mvn clean install

  7. Vá para a target pasta e execute o arquivo criado .jar . No comando, substitua java o espaço reservado {version} pela versão no nome do .jar arquivo em sua máquina.

    cd target
java -jar ./provisioning-symmetrickey-individual-sample-{version}-with-deps.jar

  8. Agora você deve 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 [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] )
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 [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] )
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 [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] )
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 [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] ) with status OK
Message received! Response status: OK

Confirme o registro de provisionamento do dispositivo

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

  1. No portal do Azure, vá para sua instância do DPS.

  2. No menu Configurações, selecione Gerenciar inscrições.

  3. Selecione Grupos de inscrição.

  4. Selecione o grupo de inscrição que você criou para este tutorial.

  5. Na página Detalhes do Grupo de Inscrição , selecione Status do registro.

  6. Encontre o 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 seu hub IoT:

  1. No portal do Azure, vá para o hub IoT ao qual seu dispositivo foi atribuído.

  2. No menu Gerenciamento de dispositivos, selecione Dispositivos.

  3. Se o dispositivo tiver sido provisionado com êxito, o ID do dispositivo deverá aparecer na lista, com Status definido como habilitado. Se não vir o dispositivo, selecione Atualizar.

    Device is registered with the IoT hub

Nota

Se você alterou o estado gêmeo inicial do dispositivo a partir do valor padrão no grupo de registro, um dispositivo pode extrair o estado gêmeo desejado do hub e agir de acordo. Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

Provisionar mais dispositivos

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

  1. Escolha um ID de registo exclusivo para o dispositivo.

  2. Derive uma chave de dispositivo. Como fez anteriormente, use a chave primária para o grupo de inscrição como a chave de grupo.

  3. Execute o código de provisionamento do dispositivo. Substitua os artefatos necessários pela nova chave de dispositivo derivada e ID de registro.

Clean up resources (Limpar recursos)

Se você planeja continuar trabalhando e explorando o exemplo de cliente de dispositivo, não limpe os recursos criados neste tutorial. Se você não planeja continuar, use as etapas a seguir para excluir todos os recursos criados neste tutorial.

Excluir seu grupo de inscrição

A exclusão de um grupo de inscrição não exclui os registros de registro associados a ele. Esses registros órfãos contam para a cota de registros da instância DPS. Por esse motivo, é uma prática recomendada excluir todos os registros de registro associados a um grupo de inscrição antes de excluir o próprio grupo de inscrição.

  1. No portal do Azure, vá para sua instância do DPS.

  2. No menu Configurações, selecione Gerenciar inscrições.

  3. Selecione a guia Grupos de inscrição.

  4. Selecione o nome do grupo de inscrição que você usou para este tutorial para abrir sua página de detalhes.

  5. Na página Detalhes da inscrição, 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 de registro para o grupo de registro. Selecione Excluir na parte superior da página para excluir os registros de registro.

  6. Volte para a página Gerenciar inscrições .

  7. Marque a caixa de seleção ao lado do nome do grupo de inscrição usado para este tutorial.

  8. Na parte superior da página, selecione Eliminar.

Excluir registros de dispositivos do Hub IoT

  1. No portal do Azure, vá para o hub IoT ao qual seu dispositivo foi atribuído.

  2. Selecione Dispositivos na seção Gerenciamento de dispositivos do menu de navegação.

  3. Marque a caixa de seleção ao lado da ID do dispositivo dos dispositivos registrados neste tutorial.

  4. Na parte superior da página, selecione Eliminar.

Próximos passos

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

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