Tutoriel : Utiliser des stratégies d’allocation personnalisées avec le service DPS (Device Provisioning Service)

  • Article

Les stratégies d’allocation personnalisées vous permettent de mieux contrôler le processus d’assignation des appareils à vos hubs IoT. Avec les stratégies d’allocation personnalisées, vous pouvez définir vos propres stratégies d’allocation quand les stratégies fournies par le service DPS (Device Provisioning Service) Azure IoT Hub ne sont pas adaptées aux besoins de votre scénario. Une stratégie d’allocation personnalisée est implémentée dans un webhook hébergé dans Azure Functions et configuré sur une ou plusieurs inscriptions individuelles et/ou groupes d’inscriptions. Quand un appareil s’inscrit auprès de DPS en utilisant une entrée d’inscription configurée, DPS appelle le webhook pour déterminer le hub IoT auquel l’appareil doit être inscrit et, éventuellement, son état initial. Pour plus d’informations, consultez Comprendre les stratégies d’allocation personnalisées.

Ce tutoriel présente une stratégie d’allocation personnalisée qui utilise une fonction Azure écrite en C#. Les appareils sont affectés à l’un des deux hubs IoT représentant une division Contoso Toasters Division et une division Contoso Heat Pumps Division. Les appareils à provisionner doivent avoir un ID d’inscription contenant l’un des suffixes suivants pour être éligibles au provisionnement :

  • -contoso-tstrsd-007 pour la division Contoso Toasters Division
  • -contoso-hpsd-088 pour la division Contoso Heat Pumps Division

Les appareils seront simulés en utilisant un exemple de provisionnement inclus dans le Kit de développement logiciel (SDK) C d’Azure IoT.

Dans ce tutoriel, vous allez apprendre à effectuer les tâches suivantes :

  • Utiliser Azure CLI pour créer une instance DPS, pour créer deux hubs IoT destinés aux divisions Contoso Toasters Division et Contoso Heat Pumps Division, et pour lier ces hubs à cette instance.
  • Créer une fonction Azure qui implémente la stratégie d’allocation personnalisée.
  • Créer un groupe d’inscriptions qui utilise la fonction Azure pour la stratégie d’allocation personnalisée.
  • Créer des clés symétriques d’appareil pour deux appareils simulés.
  • Configurer l’environnement de développement pour le Kit de développement logiciel (SDK) C d’Azure IoT.
  • Simuler les appareils et vérifier qu’ils sont provisionnés conformément à l’exemple de code dans la stratégie d’allocation personnalisée.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Prérequis

Les prérequis suivants s’appliquent à un environnement de développement Windows. 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).

Créer le service de provisionnement et deux hubs IoT

Dans cette section, vous utilisez Azure Cloud Shell pour créer un service d’approvisionnement et deux hubs IoT représentant les divisions Contoso Toasters Division et Contoso Heat Pumps Division.

  1. Tout d’abord, définissez des variables d’environnement dans votre espace de travail pour simplifier les commandes de ce tutoriel.

    Les noms du DPS et du hub IoT doivent être globalement unique dans Azure. Remplacez l’espace réservé SUFFIX par votre propre valeur.

    En outre, le code de la fonction Azure que vous créez plus loin dans ce tutoriel recherche les hubs IoT dont le nom contient -toasters- ou -heatpumps-. Si vous modifiez les valeurs suggérées, veillez à utiliser des noms qui contiennent les sous-chaînes requises.

    #!/bin/bash
export RESOURCE_GROUP="contoso-us-resource-group"
export LOCATION="westus"
export DPS="contoso-provisioning-service-SUFFIX"
export TOASTER_HUB="contoso-toasters-hub-SUFFIX"
export HEATPUMP_HUB="contoso-heatpumps-hub-SUFFIX"

    # PowerShell
$env:RESOURCE_GROUP = "contoso-us-resource-group"
$env:LOCATION = "westus"
$env:DPS = "contoso-provisioning-service-SUFFIX"
$env:TOASTER_HUB = "contoso-toasters-hub-SUFFIX"
$env:HEATPUMP_HUB = "contoso-heatpumps-hub-SUFFIX"

    Conseil

    Les commandes utilisées dans ce tutoriel créent par défaut les ressources dans la région USA Ouest. Nous vous recommandons de créer vos ressources dans la région la plus proche de celle qui prend en charge le service Device Provisioning. Vous pouvez voir une liste des emplacements disponibles en accédant à la page État d’Azure et en recherchant « Device Provisioning Service ». Dans les commandes, les emplacements peuvent être spécifiés dans un format d’un mot ou de plusieurs mots. Par exemple : westus, West US, WEST US, etc. La valeur ne respecte pas la casse.

  2. Utilisez la commande az group create pour créer un groupe de ressources Azure. Un groupe de ressources Azure est un conteneur logique dans lequel les ressources Azure sont déployées et gérées.

    L’exemple suivant crée un groupe de ressources. Nous vous recommandons d’utiliser un même groupe pour toutes les ressources créées dans ce tutoriel. Cela facilitera la suppression des ressources quand vous aurez terminé.

    az group create --name $RESOURCE_GROUP --location $LOCATION

  3. Utilisez la commande az iot dps create pour créer une instance du service Device Provisioning (DPS). Le service de provisionnement est ajouté au groupe contoso-us-resource-group.

    az iot dps create --name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION

    L’exécution de cette commande peut prendre quelques minutes.

  4. Utilisez la commande az iot hub create pour créer le hub IoT Contoso Toasters Division. Le hub IoT est ajouté au groupe contoso-us-resource-group.

    az iot hub create --name $TOASTER_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    L’exécution de cette commande peut prendre quelques minutes.

  5. Utilisez la commande az iot hub create pour créer le hub IoT Contoso Heat Pumps Division. Le hub IoT est également ajouté au groupe contoso-us-resource-group.

    az iot hub create --name $HEATPUMP_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    L’exécution de cette commande peut prendre quelques minutes.

  6. Exécutez les deux commandes suivantes pour obtenir les chaînes de connexion des hubs que vous avez créés.

    az iot hub connection-string show --hub-name $TOASTER_HUB --key primary --query connectionString -o tsv
az iot hub connection-string show --hub-name $HEATPUMP_HUB --key primary --query connectionString -o tsv

  7. Exécutez les commandes suivantes pour lier les hubs à la ressource DPS. Remplacez les espaces réservés par les chaînes de connexion des hubs de l’étape précédente.

    az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <toaster_hub_connection_string>
az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <heatpump_hub_connection_string>

Créer la fonction d’allocation personnalisée

Dans cette section, vous allez créer une fonction Azure qui implémente votre stratégie d’allocation personnalisée. Cette fonction détermine le hub IoT des divisions sur lequel un appareil doit être inscrit, selon que son ID d’inscription contient la chaîne -contoso-tstrsd-007 ou -contoso-hpsd-088. Elle définit également l’état initial du jumeau d’appareil selon que l’appareil est un toaster ou une pompe à chaleur.

  1. Connectez-vous au portail Azure.

  2. Dans la zone de recherche, recherchez et sélectionnez Application de fonction.

  3. Sélectionnez Créer ou Créer une application de fonction.

  4. Dans la page de création Application de fonction, sous l’onglet Options de base, entrez les paramètres suivants pour votre nouvelle application de fonction et sélectionnez Vérifier + créer :

    Paramètre Valeur
    Abonnement Vérifiez que l’abonnement où vous avez créé les ressources pour ce tutoriel est sélectionné.
    Groupe de ressources Sélectionnez le groupe de ressources que vous avez créé dans la section précédente. La valeur par défaut fournie dans la section précédente est contoso-us-resource-group.
    Nom de l’application de fonction Nommez votre application de fonction.
    Voulez-vous déployer du code ou une image conteneur ? Code
    Pile d’exécution .NET
    Version Sélectionnez n’importe quelle version du modèle in-process.
    Région Sélectionnez une région proche de chez vous.

    Remarque

    Par défaut, Application Insights est activé. Application Insights n’est pas nécessaire pour ce tutoriel, mais il peut vous aider à comprendre et à examiner les problèmes que vous rencontrez avec l’allocation personnalisée. Si vous préférez, vous pouvez désactiver les Application Insights en sélectionnant l’onglet Surveillance, puis en sélectionnant Non pour Activer Application Insights.

    Capture d’écran montrant le formulaire Créer une application de fonction dans le portail Azure.

  5. Sous l’onglet Vérifier + créer, sélectionnez Créer pour créer l’application de fonction.

  6. Le déploiement peut prendre plusieurs minutes. Une fois l’opération terminée, sélectionnez Accéder à la ressource.

  7. Dans le volet gauche de la page Vue d’ensemble de l’application de fonction, sélectionnez Créer une fonction..

    Capture d’écran montrant la sélection de l’option permettant pour créer une fonction dans le portail Azure.

  8. Dans la page Créer une fonction, sélectionnez le modèle Déclencheur HTTP, puis sélectionnez Suivant.

  9. Sous l’onglet Détails du modèle, sélectionnez Anonyme pour Niveau d’autorisation, puis sélectionnez Créer.

    Capture d’écran montrant la définition du niveau d’autorisation comme Anonyme.

    Conseil

    Si vous conservez le niveau d’autorisation comme Fonction, vous allez devoir configurer vos inscriptions DPS avec la clé API de la fonction. Pour plus d’informations, consultez Déclencheur HTTP Azure Functions.

  10. Quand la fonction HttpTrigger1 s’ouvre, sélectionnez Code + test dans le volet gauche. Cela vous permet de modifier le code de la fonction. Le fichier de code run.csx doit être ouvert pour modification.

  11. Référencez les packages NuGet requis. Pour créer le jumeau d’appareil initial, la fonction d’allocation personnalisée utilise des classes qui sont définies dans deux packages NuGet qui doivent être chargés dans l’environnement d’hébergement. Avec Azure Functions, les packages NuGet sont référencés à l’aide d’un fichier function.proj. Dans cette étape, vous enregistrez et chargez un fichier function.proj pour les assemblys requis. Pour plus d’informations, consultez Utiliser des packages NuGet avec Azure Functions.

    1. Copiez les lignes suivantes dans votre éditeur favori et enregistrez le fichier sur votre ordinateur sous le nom fonction.proj.

      <Project Sdk="Microsoft.NET.Sdk">  
    <PropertyGroup>  
        <TargetFramework>netstandard2.0</TargetFramework>  
    </PropertyGroup>  
    <ItemGroup>  
        <PackageReference Include="Microsoft.Azure.Devices.Provisioning.Service" Version="1.18.1" />
        <PackageReference Include="Microsoft.Azure.Devices.Shared" Version="1.30.1" />
    </ItemGroup>  
</Project>

    2. Sélectionnez le bouton Charger situé au-dessus de l’éditeur de code pour charger votre fichier function.proj. Après le chargement, sélectionnez le fichier dans l’éditeur de code avec la zone de liste déroulante pour vérifier le contenu.

    3. Sélectionnez le fichier function.proj dans l’éditeur de code et vérifiez son contenu. Si le fichier function.proj est vide, copiez les lignes ci-dessus dans le fichier et enregistrez-le. (Le chargement crée parfois le fichier sans charger le contenu.)

  12. Vérifiez que run.csx pour HttpTrigger1 est sélectionné dans l’éditeur de code. Remplacez le code de la fonction HttpTrigger1 par le code suivant, puis sélectionnez Enregistrer :

    #r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

using Microsoft.Azure.Devices.Shared;               // For TwinCollection
using Microsoft.Azure.Devices.Provisioning.Service; // For TwinState

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    // Get request body
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    log.LogInformation("Request.Body:...");
    log.LogInformation(requestBody);

    // Get registration ID of the device
    string regId = data?.deviceRuntimeContext?.registrationId;

    string message = "Uncaught error";
    bool fail = false;
    ResponseObj obj = new ResponseObj();

    if (regId == null)
    {
        message = "Registration ID not provided for the device.";
        log.LogInformation("Registration ID : NULL");
        fail = true;
    }
    else
    {
        string[] hubs = data?.linkedHubs?.ToObject<string[]>();

        // Must have hubs selected on the enrollment
        if (hubs == null)
        {
            message = "No hub group defined for the enrollment.";
            log.LogInformation("linkedHubs : NULL");
            fail = true;
        }
        else
        {
            // This is a Contoso Toaster Model 007
            if (regId.Contains("-contoso-tstrsd-007"))
            {
                //Find the "-toasters-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-toasters-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No toasters hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "toaster";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "ready";
                    properties["darknessSetting"] = "medium";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // This is a Contoso Heat pump Model 008
            else if (regId.Contains("-contoso-hpsd-088"))
            {
                //Find the "-heatpumps-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-heatpumps-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No heat pumps hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "heatpump";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "on";
                    properties["temperatureSetting"] = "65";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // Unrecognized device.
            else
            {
                fail = true;
                message = "Unrecognized device registration.";
                log.LogInformation("Unknown device registration");
            }
        }
    }

    log.LogInformation("\nResponse");
    log.LogInformation((obj.iotHubHostName != null) ? JsonConvert.SerializeObject(obj) : message);

    return (fail)
        ? new BadRequestObjectResult(message) 
        : (ActionResult)new OkObjectResult(obj);
}

public class ResponseObj
{
    public string iotHubHostName {get; set;}
    public TwinState initialTwin {get; set;}
}

Créer l’inscription

Dans cette section, vous créez un groupe d’inscriptions qui utilise la stratégie d’allocation personnalisée. Par souci de simplicité, ce tutoriel utilise l’attestation de clé symétrique avec l’inscription. Pour sécuriser votre solution, utilisez plutôt l’attestation de certificat X.509 avec une chaîne d’approbation.

  1. Connectez-vous au portail Azure et accédez à votre instance du service Device Provisioning.

  2. Sélectionnez Gérer les inscriptions dans la section Paramètres du menu de navigation.

  3. Sélectionnez Ajouter un groupe d’inscriptions.

  4. Sous l’onglet Inscription + approvisionnement de la page Ajouter un groupe d’inscriptions, fournissez les informations suivantes pour configurer les détails du groupe d’inscription :

    Champ Description
    Attestation Sélectionnez Clé symétrique comme Mécanisme d’attestation.
    Paramètres de clé symétrique Cochez la case Générer automatiquement des clés symétriques.
    Nom du groupe Entrez contoso-custom-allocation-devices comme nom de groupe.
    État d’approvisionnement Cochez la case Activer cette inscription .

  5. Sélectionnez Suivant : IoT Hubs.

  6. Sous l’onglet Hubs IoT de la page Ajouter un groupe d’inscription, fournissez les informations suivantes pour déterminer les hubs IoT pour lesquels le groupe d’inscription peut approvisionner des appareils :

    Champ Description
    Hubs IoT cibles Sélectionnez un ou plusieurs de vos hubs IoT liés, ou ajoutez un nouveau lien à un hub IoT.
    Stratégie d’allocation Sélectionnez Personnalisé (utiliser la fonction Azure). Sélectionnez Sélectionner une fonction Azure, puis suivez les invites pour sélectionner la fonction que vous avez créée pour ce tutoriel.

  7. Sélectionnez Revoir + créer.

  8. Dans l’onglet Vérifier + créer, vérifiez toutes vos valeurs, puis sélectionnez Créer.

Après avoir enregistré l’inscription, rouvrez-la et notez la valeur de la Clé primaire. Vous devez d’abord enregistrer l’inscription pour permettre la génération des clés. Cette clé est utilisée pour générer des clés d’appareil uniques pour les appareils simulés dans la section suivante.

Dériver les clés d’appareil uniques

Les appareils n’utilisent pas directement la clé symétrique primaire du groupe d’inscriptions. Au lieu de cela, vous utilisez la clé primaire pour dériver une clé d’appareil pour chaque appareil. Dans cette section, vous créez deux clés d’appareil uniques. Une de clés sera utilisée pour l’appareil Toaster simulé. L’autre clé est utilisée pour l’appareil Heat pump simulé.

Pour dériver la clé d’appareil, vous utilisez la clé principale du groupe d’inscriptions, que vous avez notée précédemment pour calculer le HMAC-SHA256 de l’ID d’inscription d’appareil pour chaque appareil et convertir le résultat au format Base 64. Pour plus d’informations sur la création de clés d’appareil dérivées avec des groupes d’inscription, consultez la section sur les inscriptions de groupes dans Attestation de clé symétrique.

Pour l’exemple de ce tutoriel, utilisez les ID d’inscription des deux appareils suivants et calculez une clé d’appareil pour chaque appareil. Les deux ID d’inscription ont un suffixe qui peut être utilisé dans l’exemple de code pour la stratégie d’allocation personnalisée :

  • breakroom499-contoso-tstrsd-007
  • mainbuilding167-contoso-hpsd-088

L’extension IoT pour Azure CLI fournit la commande iot dps enrollment-group compute-device-key permettant de générer des clés d’appareil dérivées. Cette commande peut être utilisée sur des systèmes Windows ou Linux, dans PowerShell ou un interpréteur de commandes Bash.

Remplacez la valeur de l’argument --key par la clé primaire de votre groupe d’inscription.

az iot dps enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id breakroom499-contoso-tstrsd-007

az iot dps compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id mainbuilding167-contoso-hpsd-088

Notes

Vous pouvez également fournir l’ID de groupe d’inscriptions plutôt que la clé symétrique à la commande iot dps enrollment-group compute-device-key. Par exemple :

az iot dps enrollment-group compute-device-key -g contoso-us-resource-group --dps-name contoso-provisioning-service-1098 --enrollment-id contoso-custom-allocated-devices --registration-id breakroom499-contoso-tstrsd-007

Les appareils simulés utiliseront les clés d’appareil dérivées avec chaque ID d’inscription pour effectuer l’attestation de clé symétrique.

Préparer un environnement de développement pour le SDK Azure IoT pour C

Dans cette section, vous préparez l’environnement de développement utilisé pour générer le SDK Azure IoT pour C. Le SDK inclut l’exemple de code pour l’appareil simulé. Cet appareil simulé tente le provisionnement durant la séquence de démarrage de l’appareil.

Cette section s’applique à une station de travail Windows. Pour obtenir un exemple sur Linux, consultez la section sur la configuration des machines virtuelles dans Tutoriel : Provisionner pour la géolatence.

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

    Important : les composants requis pour Visual Studio (Visual Studio et la charge de travail « Développement Desktop en C++ ») doivent être 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.

  2. Recherchez le nom de balise de la version la plus récente du kit de développement logiciel (SDK).

  3. 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. Utilisez l’étiquette obtenue à l’étape précédente comme valeur pour le paramètre -b, 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

    Attendez-vous à ce que cette opération prenne plusieurs minutes.

  4. Créez un sous-répertoire cmake dans le répertoire racine du référentiel Git et accédez à ce dossier. Exécutez les commandes suivantes à partir du répertoire azure-iot-sdk-c :

    mkdir cmake
cd cmake

  5. Exécutez la commande suivante qui génère une version du SDK propre à votre plateforme cliente de développement. Une solution Visual Studio pour l’appareil simulé est générée dans le répertoire cmake.

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

    Si cmake ne trouve pas votre compilateur C++, vous risquez de constater des erreurs de build lors de l’exécution de la commande. Si cela se produit, essayez d’exécuter la commande dans l’invite de commandes de Visual Studio.

    Une fois la génération terminée, les dernières lignes de la sortie doivent ressembler à ceci :

    $ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

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

Simuler les appareils

Dans cette section, vous mettez à jour un exemple d’approvisionnement nommé prov_dev_client_sample provenant du Kit de développement logiciel (SDK) Azure IoT pour C que vous avez configuré précédemment.

Cet exemple de code simule une séquence de démarrage d’un appareil qui envoie la demande de provisionnement à votre instance du service Device Provisioning. La séquence de démarrage entraîne la reconnaissance de l’appareil Toaster et son affectation au hub IoT avec la stratégie d’allocation personnalisée.

  1. Dans le portail Azure, sélectionnez l’onglet Vue d’ensemble de votre service Device Provisioning et notez la valeur Étendue de l’ID.

    Extraction des informations de point de terminaison du service Device Provisioning à partir du panneau du Portail

  2. Dans Visual Studio, ouvrez le fichier solution azure_iot_sdks.sln généré précédemment en exécutant CMake. Le fichier solution doit être à l’emplacement suivant : azure-iot-sdk-c\cmake\azure_iot_sdks.sln.

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

  4. Recherchez la constante id_scope et remplacez la valeur par la valeur Étendue de l’ID que vous avez copiée précédemment.

    static const char* id_scope = "0ne00002193";

  5. Recherchez la définition de la fonction main() dans le même fichier. Vérifiez que la variable hsm_type a la valeur SECURE_DEVICE_TYPE_SYMMETRIC_KEY, comme indiqué ci-dessous :

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

  6. Dans la fonction main(), recherchez l’appel à Prov_Device_Register_Device(). Juste avant cet appel, ajoutez les lignes de code suivantes qui utilisent Prov_Device_Set_Provisioning_Payload() pour passer une charge utile JSON personnalisée pendant le provisionnement. Cela permet de fournir plus d’informations à vos fonctions d’allocation personnalisées. Cela peut également être utilisé pour passer le type d’appareil au lieu d’examiner l’ID d’inscription. Pour plus d’informations sur l’envoi et la réception de charges utiles de données personnalisées avec DPS, consultez Guide pratique pour transférer des charges utiles entre des appareils et un service DPS.

    // An example custom payload
const char* custom_json_payload = "{\"MyDeviceFirmwareVersion\":\"12.0.2.5\",\"MyDeviceProvisioningVersion\":\"1.0.0.0\"}";

prov_device_result = Prov_Device_Set_Provisioning_Payload(prov_device_handle, custom_json_payload);
if (prov_device_result != PROV_DEVICE_RESULT_OK)
{
    (void)printf("\r\nFailure setting provisioning payload: %s\r\n", MU_ENUM_TO_STRING(PROV_DEVICE_RESULT, prov_device_result));
}

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

Simuler l’appareil Toaster de Contoso

  1. Pour simuler l’appareil Toaster, recherchez l’appel à prov_dev_set_symmetric_key_info() dans prov_dev_client_sample.c, qui est placé en commentaire.

    // 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 pour l’appel de fonction et remplacez les valeurs des espaces réservés (y compris les crochets) par l’ID d’inscription du Toaster et la clé d’appareil dérivée que vous avez générée précédemment. La valeur JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= est donnée seulement à titre d’exemple.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("breakroom499-contoso-tstrsd-007", "JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs=");

    Enregistrez le fichier .

  2. Dans le menu Visual Studio, sélectionnez Déboguer>Exécuter sans débogage pour exécuter la solution. Dans l’invite pour régénérer le projet, sélectionnez Oui pour régénérer le projet avant de l’exécuter.

    La sortie suivante est un exemple illustrant le démarrage réussi de l’appareil Toaster simulé et sa connexion à l’instance du service Device Provisioning à assigner au hub IoT Toasters à l’aide de la stratégie d’allocation personnalisée :

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-toasters-hub-1098.azure-devices.net, deviceId: breakroom499-contoso-tstrsd-007

Press enter key to exit:

    La sortie suivante est un exemple de journalisation de la sortie générée par le code de la fonction d’allocation personnalisée en cours d’exécution pour l’appareil Toaster. Notez qu’un hub est correctement sélectionné pour un appareil Toaster. Notez également la propriété payload qui contient le contenu JSON personnalisé que vous avez ajouté au code. Il peut s’utiliser pour votre code dans deviceRuntimeContext.

    Cette journalisation est disponible en cliquant sur Journaux sous le code de fonction dans le portail :

    2022-08-03T20:34:41.178 [Information] Executing 'Functions.HttpTrigger1' (Reason='This function was programmatically called via the host APIs.', Id=12950752-6d75-4f41-844b-c253a6653d4f)
2022-08-03T20:34:41.340 [Information] C# HTTP trigger function processed a request.
2022-08-03T20:34:41.341 [Information] Request.Body:...
2022-08-03T20:34:41.341 [Information] {"enrollmentGroup":{"enrollmentGroupId":"contoso-custom-allocated-devices","attestation":{"type":"symmetricKey"},"capabilities":{"iotEdge":false},"etag":"\"0000f176-0000-0700-0000-62eaad1e0000\"","provisioningStatus":"enabled","reprovisionPolicy":{"updateHubAssignment":true,"migrateDeviceData":true},"createdDateTimeUtc":"2022-08-03T17:15:10.8464255Z","lastUpdatedDateTimeUtc":"2022-08-03T17:15:10.8464255Z","allocationPolicy":"custom","iotHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"],"customAllocationDefinition":{"webhookUrl":"https://contoso-function-app-1098.azurewebsites.net/api/HttpTrigger1?****","apiVersion":"2021-10-01"}},"deviceRuntimeContext":{"registrationId":"breakroom499-contoso-tstrsd-007","currentIotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","currentDeviceId":"breakroom499-contoso-tstrsd-007","symmetricKey":{},"payload":{"MyDeviceFirmwareVersion":"12.0.2.5","MyDeviceProvisioningVersion":"1.0.0.0"}},"linkedHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"]}
2022-08-03T20:34:41.382 [Information] Response
2022-08-03T20:34:41.398 [Information] {"iotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","initialTwin":{"properties":{"desired":{"state":"ready","darknessSetting":"medium"}},"tags":{"deviceType":"toaster"}}}
2022-08-03T20:34:41.399 [Information] Executed 'Functions.HttpTrigger1' (Succeeded, Id=12950752-6d75-4f41-844b-c253a6653d4f, Duration=227ms)

Simuler l’appareil Heat pump de Contoso

  1. Pour simuler l’appareil Pompe à chaleur, mettez à jour l’appel à prov_dev_set_symmetric_key_info() dans prov_dev_client_sample.c à nouveau avec l’ID d’inscription et la clé d’appareil dérivée de la pompe à chaleur générée précédemment. La valeur 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= est donnée seulement à titre d’exemple.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("mainbuilding167-contoso-hpsd-088", "6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg=");

    Enregistrez le fichier .

  2. Dans le menu Visual Studio, sélectionnez Déboguer>Exécuter sans débogage pour exécuter la solution. Dans l’invite pour régénérer le projet, sélectionnez Oui pour régénérer le projet avant de l’exécuter.

    La sortie suivante est un exemple illustrant le démarrage réussi de l’appareil Heat pump simulé et sa connexion à l’instance du service Device Provisioning à assigner au hub IoT Heat pumps de Contoso à l’aide de la stratégie d’allocation personnalisée :

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-heatpumps-hub-1098.azure-devices.net, deviceId: mainbuilding167-contoso-hpsd-088

Press enter key to exit:

Résoudre les problèmes liés aux stratégies d’allocation personnalisées

Le tableau suivant présente les scénarios attendus et les codes d’erreur de résultats que vous pouvez recevoir. Aidez-vous de ce tableau pour résoudre les problèmes de stratégie d’allocation personnalisée avec Azure Functions.

Scénario Résultat de l’inscription retourné par le service Provisioning Résultat du provisionnement retourné par le SDK
Le webhook retourne 200 OK avec 'iotHubHostName' défini sur un nom d’hôte IoT Hub valide État du résultat : Attribué Le SDK retourne PROV_DEVICE_RESULT_OK et des informations sur le hub
Le webhook retourne 200 OK avec 'iotHubHostName' présent dans la réponse, mais défini sur une chaîne vide ou null État du résultat : Échec

Code d’erreur : CustomAllocationIotHubNotSpecified (400208)		 Le SDK retourne PROV_DEVICE_RESULT_HUB_NOT_SPECIFIED
Le webhook retourne 401 Unauthorized État du résultat : Échec

Code d’erreur : CustomAllocationUnauthorizedAccess (400209)		 Le SDK retourne PROV_DEVICE_RESULT_UNAUTHORIZED
Une inscription individuelle a été créée pour désactiver l’appareil État du résultat : Désactivé Le SDK retourne PROV_DEVICE_RESULT_DISABLED
Le webhook retourne le code d’erreur >= 429 L’orchestration de DPS va effectuer plusieurs nouvelles tentatives. La stratégie de nouvelles tentatives est actuellement la suivante :

  - Nombre de nouvelles tentatives : 10
  - Intervalle initial : 1 s
  - Incrément : 9 s		 Le SDK ignore l’erreur et envoie un autre message d’état get dans le délai spécifié
Le webhook retourne un autre code d’état État du résultat : Échec

Code d’erreur : CustomAllocationFailed (400207)		 Le SDK retourne PROV_DEVICE_RESULT_DEV_AUTH_ERROR

Nettoyer les ressources

Si vous envisagez de continuer à utiliser les ressources créées dans ce tutoriel, vous pouvez les conserver. Sinon, effectuez les étapes suivantes pour supprimer toutes les ressources qui ont été créées dans le cadre de ce tutoriel, et ainsi éviter des frais inutiles.

Les étapes décrites partent du principe que vous avez créé toutes les ressources utilisées dans ce tutoriel dans le même groupe de ressources nommé contoso-us-resource-group, comme nous vous l’avions demandé.

Important

La suppression d’un groupe de ressources est irréversible. Le groupe de ressources et toutes les ressources qu’il contient sont supprimés définitivement. Veillez à ne pas supprimer accidentellement les mauvaises ressources ou le mauvais groupe de ressources. Si vous avez créé l’IoT Hub à l’intérieur d’un groupe de ressources existant qui concerne des ressources que vous souhaitez conserver, supprimer uniquement la ressource de l’ IoT Hub au lieu de supprimer le groupe de ressources.

Pour supprimer le groupe de ressources par nom :

  1. Connectez-vous au portail Azure, puis sélectionnez Groupes de ressources.

  2. Dans la zone de texte Filtrer par nom..., tapez le nom du groupe de ressources contenant vos ressources (ici, contoso-us-resource-group).

  3. À droite de votre groupe de ressources dans la liste des résultats, sélectionnez ... , puis Supprimer le groupe de ressources.

  4. Il vous sera demandé de confirmer la suppression du groupe de ressources. Saisissez à nouveau le nom de votre groupe de ressources pour confirmer, puis sélectionnez Supprimer. Après quelques instants, le groupe de ressources et toutes les ressources qu’il contient sont supprimés.

Étapes suivantes

Pour plus d’informations sur les stratégies d’allocation personnalisées, consultez :

Comprendre les stratégies d’allocation personnalisées