Démarrage rapide : Provisionner un appareil à clé symétrique simulé

• Si vous utilisez un environnement de développement Windows, installez Visual Studio 2019 avec la charge de travail « Desktop Development en C++ » activée. Visual Studio 2015 et Visual Studio 2017 sont également pris en charge. Pour Linux ou macOS, consultez la section appropriée de Préparer votre environnement de développement dans la documentation du kit de développement logiciel (SDK).

• Installez le kit SDK .NET 6.0 sur votre machine Windows. Vous pouvez exécuter la commande suivante pour vérifier votre version.

  dotnet --info
  

• Installez Node.js v4.0+.

• Installez Python 3.7 ou une version ultérieure sur votre machine Windows. Vous pouvez vérifier votre version de Python en exécutant python --version.

• Installez Java SE Development Kit 8 ou une version ultérieure sur votre machine.

• Téléchargez et installez Maven.

Dans cette section, vous allez préparer un environnement de développement qui est utilisé pour générer le SDK C Azure IoT . L’exemple de code tente de provisionner l’appareil pendant la séquence de démarrage de ce dernier.

1. Téléchargez le dernier système de génération CMake.

   Important

   Vérifiez que les prérequis de Visual Studio (Visual Studio et la charge de travail « Développement Desktop en C++ ») sont installés sur votre machine avant de commencer l’installation de CMake. Une fois les composants requis en place et le téléchargement effectué, installez le système de génération de CMake. Sachez également que les versions antérieures du système de génération CMake ne permettent pas de générer le fichier solution utilisé dans cet article. Veillez à utiliser la dernière version de CMake.

2. Ouvrez un navigateur web, puis accédez à la page des versions du kit SDK C Azure IoT.

3. Sélectionnez l’onglet Étiquettes en haut de la page.

4. Copiez le nom d’étiquette de la version la plus récente du SDK C Azure IoT.

5. Ouvrez une invite de commandes ou l’interpréteur de commandes Git Bash. Exécutez les commandes suivantes pour cloner la dernière version du dépôt GitHub de l’appareil Azure IoT SDK pour C. Remplacez <release-tag> par la balise que vous avez copiée à l’étape précédente, par exemple : 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
   

   Cette opération peut prendre plusieurs minutes.

6. Une fois l’opération terminée, exécutez les commandes suivantes à partir du répertoire azure-iot-sdk-c :

   mkdir cmake
   cd cmake
   

7. L’exemple de code utilise une clé symétrique pour fournir l’attestation. Exécutez la commande suivante pour générer une version du SDK spécifique à votre plateforme cliente de développement qui inclut le client de provisionnement des appareils :

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

   Conseil

   Si cmake ne trouve pas votre compilateur C++, vous risquez de rencontrer des erreurs de génération lors de l’exécution de la commande ci-dessus. Si cela se produit, essayez d’exécuter la commande dans l’invite de commandes de Visual Studio.

8. Quand la build se termine correctement, les dernières lignes de la sortie ressemblent à la sortie suivante :

   $ 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.19042.
   -- The C compiler identification is MSVC 19.29.30040.0
   -- The CXX compiler identification is MSVC 19.29.30040.0
   
   ...
   
   -- Configuring done
   -- Generating done
   -- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
   

1. Ouvrez un environnement de ligne de commande Git CMD ou Git Bash.

2. Clonez le dépôt GitHub Azure IoT SDK pour C# avec la commande suivante :

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

1. Ouvrez un environnement de ligne de commande Git CMD ou Git Bash.

2. Clonez le dépôt GitHub du kit SDK Azure IoT pour Node.js à l’aide de la commande suivante :

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

1. Ouvrez un environnement de ligne de commande Git CMD ou Git Bash.

2. Clonez le dépôt GitHub du SDK Azure IoT pour Python à l’aide de la commande suivante :

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

   Notes

   Les exemples utilisés dans ce tutoriel se trouvent dans la branche v2 du référentiel azure-iot-sdk-python. V3 du Kit de développement logiciel (SDK) Python est disponible en version bêta.

1. Ouvrez un environnement de ligne de commande Git CMD ou Git Bash.

2. Clonez le dépôt GitHub du SDK Azure IoT pour Java à l’aide de la commande suivante :

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

3. Accédez au répertoire azure-iot-sdk-java racine et générez le projet pour télécharger tous les packages nécessaires. Cette étape peut prendre plusieurs minutes.

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

Dans cette section, vous allez mettre à jour l’exemple de code d’appareil pour envoyer la séquence de démarrage de l’appareil à votre instance du service de provisionnement des appareils. Grâce à cette séquence de démarrage, l’appareil est reconnu, authentifié et affecté à un hub IoT lié à l’instance du service de provisionnement des appareils.

L’exemple de code de provisionnement effectue les tâches suivantes, dans l’ordre :

1. Authentifie votre appareil avec votre ressource Device Provisioning à l’aide des trois paramètres suivants :

   • L’étendue de l’ID de votre service Device Provisioning
   • L’ID d’inscription pour l’inscription de votre appareil.
   • La clé symétrique principale pour l’inscription de votre appareil.

2. Affecte l’appareil à l’hub IoT qui est déjà lié à votre instance du service Device Provisioning.

Pour mettre à jour et exécuter l’exemple de provisionnement avec les informations de votre appareil :

1. Dans le menu principal de votre service Device Provisioning, sélectionnez Vue d’ensemble.

2. Copiez la valeur Étendue de l’ID.

   

3. Dans Visual Studio, ouvrez le fichier de solution azure_iot_sdks.sln généré en exécutant CMake. Le fichier solution doit être à l’emplacement suivant :

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

   Conseil

   Si le fichier n’a pas été généré dans votre répertoire CMake, vérifiez que vous avez utilisé une version récente du système de génération CMake.

4. Dans la fenêtre Explorateur de solutions de Visual Studio, accédez au dossier Provision_Samples. Développez le projet exemple nommé prov_dev_client_sample. Développez Fichiers sources, puis ouvrez prov_dev_client_sample.c.

5. Recherchez la constante id_scope et remplacez la valeur par la valeur Étendue de l’ID que vous avez copiée à l’étape 2.

   static const char* id_scope = "0ne00002193";
   

6. Recherchez la définition de la fonction main() dans le même fichier. Vérifiez que la variable hsm_type est définie sur SECURE_DEVICE_TYPE_SYMMETRIC_KEY, comme indiqué dans l’exemple suivant :

   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. Recherchez l’appel à prov_dev_set_symmetric_key_info() dans prov_dev_client_sample.c qui est commenté.

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

   Supprimez les marques de commentaire de l’appel de fonction et remplacez les valeurs d’espace réservé (crochets inclus) par votre ID d’inscription de votre appareil et la valeur de clé primaire que vous avez copiée précédemment.

   // Set the symmetric key if using they auth type
   prov_dev_set_symmetric_key_info("symm-key-device-007", "your primary key here");
   

8. Enregistrez le fichier .

9. Cliquez avec le bouton droit sur le projet dps_client_sample et sélectionnez Définir comme projet de démarrage.

10. Dans le menu Visual Studio, sélectionnez Déboguer>Exécuter sans débogage pour exécuter la solution. Dans l’invite de regénération du projet, sélectionnez Yes (Oui) pour regénérer le projet avant de l’exécuter.

    La sortie suivante est un exemple illustrant la connexion réussie de l’appareil à l’instance de service de provisionnement à affecter à un hub IoT :

    Provisioning API Version: 1.2.8
    
    Registering Device
    
    Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    
    Registration Information received from service:
    test-docs-hub.azure-devices.net, deviceId: device-007
    Press enter key to exit:
    

L’exemple de code de provisionnement effectue les tâches suivantes :

1. Authentifie votre appareil avec votre ressource Device Provisioning à l’aide des trois paramètres suivants :

   • L’étendue de l’ID de votre service Device Provisioning
   • L’ID d’inscription pour l’inscription de votre appareil.
   • La clé symétrique principale pour l’inscription de votre appareil.

2. Affecte l’appareil à l’hub IoT qui est déjà lié à votre instance du service Device Provisioning.

3. Envoie un message de télémétrie de test au hub IoT.

Pour mettre à jour et exécuter l’exemple de provisionnement avec les informations de votre appareil :

1. Dans le menu principal de votre service Device Provisioning, sélectionnez Vue d’ensemble.

2. Copiez la valeur Étendue de l’ID.

   

3. Ouvrez une invite de commandes et accédez à SymmetricKeySample dans le dépôt du SDK cloné :

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

4. Dans le dossier SymmetricKeySample, ouvrez Parameters.cs dans un éditeur de texte. Ce fichier montre les paramètres pris en charge par l’exemple. Seuls les trois premiers paramètres requis sont utilisés dans cet article lors de l’exécution de l’exemple. Passez en revue le code dans ce fichier. Aucune modification n’est requise.

   Paramètre	Obligatoire	Description
   --i ou --IdScope	Vrai	Étendue de l’ID de l’instance DPS
   --r ou --RegistrationId	Vrai	L’ID d’inscription est une chaîne insensible à la casse (jusqu’à 128 caractères) de caractères alphanumériques et des caractères spéciaux : '-', '.', '_', ':'. Le dernier caractère doit être alphanumérique ou être un tiret ('-').
   --p ou --PrimaryKey	Vrai	Clé primaire de l’inscription individuelle ou clé d’appareil dérivée de l’inscription de groupe. Pour savoir comment générer la clé dérivée, consultez ComputeDerivedSymmetricKeySample.
   --g ou --GlobalDeviceEndpoint	Faux	Point de terminaison global pour les appareils auxquels se connecter. La valeur par défaut est global.azure-devices-provisioning.net
   --t ou --TransportType	Faux	Transport à utiliser pour communiquer avec l’instance de provisionnement d’appareil. La valeur par défaut est Mqtt. Les valeurs possibles incluent Mqtt, Mqtt_WebSocket_Only, Mqtt_Tcp_Only, Amqp, Amqp_WebSocket_Only, Amqp_Tcp_only et Http1.

5. Dans le dossier SymmetricKeySample, ouvrez ProvisioningDeviceClientSample.cs dans un éditeur de texte. Ce fichier montre comment la classe SecurityProviderSymmetricKey est utilisée avec la classe ProvisioningDeviceClient pour provisionner votre appareil à clé symétrique simulé. Passez en revue le code dans ce fichier. Aucune modification n’est requise.

6. Générez et exécutez l’exemple de code à l’aide de la commande suivante :

   • Remplacez <id-scope> par la valeur Étendue de l’ID que vous avez copiée à l’étape 2.
   • Remplacez <registration-id> par la valeur ID d’inscription que vous avez fournie pour l’inscription de l’appareil.
   • Remplacez <primarykey> par la valeur Clé primaire que vous avez copiée à partir de l’inscription de l’appareil.

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

7. Vous devriez obtenir un résultat semblable à la sortie suivante. Une chaîne « TestMessage » est envoyée au hub en guise de message de test.

   D:\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample>dotnet run --i 0ne00000A0A --r symm-key-csharp-device-01 --p sbDDeEzRuEuGKag+kQKV+T1QGakRtHpsERLP0yPjwR93TrpEgEh/Y07CXstfha6dhIPWvdD1nRxK5T0KGKA+nQ==
   
   Initializing the device provisioning client...
   Initialized for registration Id symm-key-csharp-device-01.
   Registering with the device provisioning service...
   Registration status: Assigned.
   Device csharp-device-01 registered to ExampleIoTHub.azure-devices.net.
   Creating symmetric key authentication for IoT Hub...
   Testing the provisioned device with IoT Hub...
   Sending a telemetry message...
   Finished.
   Enter any key to exit.
   

L’exemple de code de provisionnement effectue les tâches suivantes, dans l’ordre :

1. Authentifie votre appareil avec votre ressource Device Provisioning à l’aide des quatre paramètres suivants :

   • PROVISIONING_HOST
   • PROVISIONING_IDSCOPE
   • PROVISIONING_REGISTRATION_ID
   • PROVISIONING_SYMMETRIC_KEY

2. Affecte l’appareil à l’hub IoT qui est déjà lié à votre instance du service Device Provisioning.

3. Envoie un message de télémétrie de test au hub IoT.

Pour mettre à jour et exécuter l’exemple de provisionnement avec les informations de votre appareil :

1. Dans le menu principal de votre service Device Provisioning, sélectionnez Vue d’ensemble.

2. Copiez les valeurs Étendue de l’ID et Point de terminaison d’appareil global.

   

3. Ouvrez une invite de commandes pour l’exécution de commandes Node.js, puis accédez au répertoire suivant :

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

4. Dans le dossier provisioning/device/samples, ouvrez register_symkey.js et passez en revue le code. Notez que l’exemple de code définit une charge utile personnalisée :

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

   Vous pouvez mettre ce code en commentaire, car il n’est pas nécessaire dans le cadre de ce guide de démarrage rapide. Une charge utile personnalisée est nécessaire si vous souhaitez utiliser une fonction d’allocation personnalisée pour affecter votre appareil à un hub IoT. Pour plus d’informations, consultez Didacticiel : Utiliser des stratégies d’allocation personnalisées.

   La méthode provisioningClient.register() tente d’effectuer l’inscription de votre appareil.

   Aucun autre changement n’est nécessaire.

5. À l’invite de commandes, exécutez les commandes suivantes pour définir les variables d’environnement utilisées par l’exemple :

   • Remplacez <provisioning-global-endpoint> par la valeur Point de terminaison d’appareil global que vous avez copiée à l’étape 2.
   • Remplacez <id-scope> par la valeur Étendue de l’ID que vous avez copiée à l’étape 2.
   • Remplacez <registration-id> par la valeur ID d’inscription que vous avez fournie pour l’inscription de l’appareil.
   • Remplacez <primarykey> par la valeur Clé primaire que vous avez copiée à partir de l’inscription de l’appareil.

   set PROVISIONING_HOST=<provisioning-global-endpoint>
   

   set PROVISIONING_IDSCOPE=<id-scope>
   

   set PROVISIONING_REGISTRATION_ID=<registration-id>
   

   set PROVISIONING_SYMMETRIC_KEY=<primarykey>
   

6. Générez et exécutez l’exemple de code à l’aide des commandes suivantes :

    npm install
   

   node register_symkey.js
   

7. Vous devriez obtenir un résultat semblable à la sortie suivante. Une chaîne « Hello World » est envoyée au hub en guise de message de test.

   D:\azure-iot-samples-csharp\provisioning\device\samples>node register_symkey.js
   registration succeeded
   assigned hub=ExampleIoTHub.azure-devices.net
   deviceId=nodejs-device-01
   payload=undefined
   Client connected
   send status: MessageEnqueued
   

L’exemple de code de provisionnement effectue les tâches suivantes, dans l’ordre :

1. Authentifie votre appareil avec votre ressource Device Provisioning à l’aide des quatre paramètres suivants :

   • PROVISIONING_HOST
   • PROVISIONING_IDSCOPE
   • PROVISIONING_REGISTRATION_ID
   • PROVISIONING_SYMMETRIC_KEY

2. Affecte l’appareil à l’hub IoT qui est déjà lié à votre instance du service Device Provisioning.

3. Envoie un message de télémétrie de test au hub IoT.

Pour mettre à jour et exécuter l’exemple de provisionnement avec les informations de votre appareil :

1. Dans le menu principal de votre service Device Provisioning, sélectionnez Vue d’ensemble.

2. Copiez les valeurs Étendue de l’ID et Point de terminaison d’appareil global.

   

3. Ouvrez une invite de commandes et accédez au répertoire dans lequel se trouve l’exemple de fichier, provision_symmetric_key.py.

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

4. À l’invite de commandes, exécutez les commandes suivantes pour définir les variables d’environnement utilisées par l’exemple :

   • Remplacez <provisioning-global-endpoint> par la valeur Point de terminaison d’appareil global que vous avez copiée à l’étape 2.
   • Remplacez <id-scope> par la valeur Étendue de l’ID que vous avez copiée à l’étape 2.
   • Remplacez <registration-id> par la valeur ID d’inscription que vous avez fournie pour l’inscription de l’appareil.
   • Remplacez <primarykey> par la valeur Clé primaire que vous avez copiée à partir de l’inscription de l’appareil.

   set PROVISIONING_HOST=<provisioning-global-endpoint>
   

   set PROVISIONING_IDSCOPE=<id-scope>
   

   set PROVISIONING_REGISTRATION_ID=<registration-id>
   

   set PROVISIONING_SYMMETRIC_KEY=<primarykey>
   

5. Installez la bibliothèque azure-iot-device en exécutant la commande suivante.

   pip install azure-iot-device
   

6. Exécutez l’exemple de code Python dans provision_symmetric_key.py.

   python provision_symmetric_key.py
   

7. Vous devriez obtenir un résultat semblable à la sortie suivante. Des exemples de messages de télémétrie de la vitesse du vent sont également envoyés au hub en guise de test.

   D:\azure-iot-sdk-python\samples\async-hub-scenarios>python provision_symmetric_key.py
   RegistrationStage(RequestAndResponseOperation): Op will transition into polling after interval 2.  Setting timer.
   The complete registration result is
   python-device-008
   docs-test-iot-hub.azure-devices.net
   initialAssignment
   null
   Will send telemetry from the provisioned device
   sending message #8
   sending message #9
   sending message #3
   sending message #10
   sending message #4
   sending message #2
   sending message #6
   sending message #7
   sending message #1
   sending message #5
   done sending message #8
   done sending message #9
   done sending message #3
   done sending message #10
   done sending message #4
   done sending message #2
   done sending message #6
   done sending message #7
   done sending message #1
   done sending message #5
   

L’exemple de code de provisionnement effectue les tâches suivantes, dans l’ordre :

1. Authentifie votre appareil avec votre ressource Device Provisioning à l’aide des quatre paramètres suivants :

   • GLOBAL_ENDPOINT
   • SCOPE_ID
   • REGISTRATION_ID
   • SYMMETRIC_KEY

2. Affecte l’appareil à l’hub IoT qui est déjà lié à votre instance du service Device Provisioning.

3. Envoie un message de télémétrie de test au hub IoT.

Pour mettre à jour et exécuter l’exemple de provisionnement avec les informations de votre appareil :

1. Dans le menu principal de votre service Device Provisioning, sélectionnez Vue d’ensemble.

2. Copiez les valeurs Étendue de l’ID et Point de terminaison d’appareil global. Ces valeurs sont respectivement vos paramètres SCOPE_ID et GLOBAL_ENDPOINT.

   

3. Ouvrez l’exemple de code d’appareil Java pour le modifier. Le chemin complet de l’exemple de code d’appareil est le suivant :

   azure-iot-sdk-java/provisioning/provisioning-device-client-samples/provisioning-symmetrickey-individual-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningSymmetricKeyIndividualEnrollmentSample.java

4. Définissez la valeur des variables suivantes pour votre DPS et l’inscription de l’appareil :

   • Remplacez <id-scope> par la valeur Étendue de l’ID que vous avez copiée à l’étape 2.
   • Remplacez <provisioning-global-endpoint> par la valeur Point de terminaison d’appareil global que vous avez copiée à l’étape 2.
   • Remplacez <registration-id> par la valeur ID d’inscription que vous avez fournie pour l’inscription de l’appareil.
   • Remplacez <primarykey> par la valeur Clé primaire que vous avez copiée à partir de l’inscription de l’appareil.

   private static final String SCOPE_ID = "<id-scope>";
   private static final String GLOBAL_ENDPOINT = "<provisioning-global-endpoint>";
   private static final String SYMMETRIC_KEY = "<primarykey>";
   private static final String REGISTRATION_ID = "<registration-id>";
   

5. Ouvrez une invite de commandes pour la génération. Accédez à l’exemple de dossier de projet de provisionnement du dépôt SDK Java.

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

6. Générez l’exemple.

   mvn clean install
   

7. Accédez au dossier target et exécutez le fichier .jar créé. Dans la commande java, remplacez l'espace réservé {version} par la version dans le nom de fichier .jar sur votre ordinateur.

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

8. Vous devriez obtenir un résultat semblable à la sortie suivante.

   Starting...
   Beginning setup.
   Initialized a ProvisioningDeviceClient instance using SDK version 1.11.0
   Starting provisioning thread...
   Waiting for Provisioning Service to register
   Opening the connection to device provisioning service...
   Connection to device provisioning service opened successfully, sending initial device registration message
   Authenticating with device provisioning service using symmetric key
   Waiting for device provisioning service to provision this device...
   Current provisioning status: ASSIGNING
   Device provisioning service assigned the device successfully
   IotHUb Uri : <Your IoT hub name>.azure-devices.net
   Device ID : java-device-007
   Sending message from device to IoT Hub...
   Press any key to exit...
   Message received! Response status: OK_EMPTY