Comprendre les stratégies d’allocation personnalisée avec le service IoT Hub Device Provisioning (DPS) Azure

Article
10/26/2023

Les stratégies d’allocation personnalisées vous permettent de mieux contrôler le processus d’assignation des appareils à vos hubs IoT. Des stratégies d’allocation personnalisée vous permettent de définir vos propres stratégies d’allocation quand les stratégies intégrées fournies par le service IoT Hub Device Provisioning (DPS) ne sont pas adaptées aux besoins de votre scénario.

Par exemple, vous souhaitez peut-être examiner le certificat utilisé par un appareil pendant le provisionnement et assigner l’appareil à un hub IoT en fonction d’une propriété du certificat. Ou bien, vous avez peut-être une base de données contenant des informations sur vos appareils, que vous souhaitez interroger pour déterminer à quel hub IoT un appareil doit être assigné ou comment le jumeau initial de l’appareil doit être défini.

Vous implémentez une stratégie d’allocation personnalisée dans un webhook hébergé dans Azure Functions. Vous pouvez ensuite configurer le webhook dans une ou plusieurs inscriptions individuelles et dans des groupes d’inscriptions. Quand un appareil s’inscrit via une entrée d’inscription configurée, le DPS appelle le webhook qui retourne le hub IoT auquel inscrire l’appareil et, éventuellement, les paramètres de jumeau initial de l’appareil, ainsi que toutes les informations à retourner directement à l’appareil.

Vue d’ensemble

Les étapes suivantes décrivent le fonctionnement des stratégies d’allocation personnalisée :

Un développeur d’allocation personnalisée développe un webhook qui implémente la stratégie d’allocation voulue et la déploie en tant que fonction de déclencheur HTTP pour Azure Functions. Le webhook prend des informations sur l’entrée d’inscription du DPS et l’appareil, et retourne le hub IoT auquel l’appareil doit être inscrit, ainsi éventuellement que des informations sur l’état initial de l’appareil.
Un opérateur IoT configure une ou plusieurs inscriptions individuelles et/ou des groupes d’inscriptions pour l’allocation personnalisée, et fournit des détails d’appel pour le webhook d’allocation personnalisée dans Azure Functions.
Quand un appareil s’inscrit via une entrée d’inscription configurée pour le webhook d’allocation personnalisée, le DPS envoie au webhook une requête POST dont le corps est défini sur un objet de requête AllocationRequest. L’objet AllocationRequest contient des informations sur l’appareil qui tente d’approvisionner, ainsi que sur l’instruction individuelle ou le groupe d’inscriptions via lesquels il est approvisionné. Les informations de l’appareil peuvent inclure une charge utile personnalisée facultative envoyée à partir de l’appareil dans sa demande d’inscription. Pour plus d’informations, consultez Demande de stratégie d’allocation personnalisée.
La fonction Azure s’exécute et retourne un objet AllocationResponse sur la réussite. L’objet AllocationResponse contient le hub IoT auquel l’appareil doit être approvisionné, l’état du jumeau initial et une charge utile personnalisée facultative à retourner à l’appareil. Pour plus d’informations, consultez Réponse de stratégie d’allocation personnalisée.
Le DPS affecte l’appareil au hub IoT indiqué dans la réponse et, si un jumeau initial est retourné, définit le jumeau initial pour l’appareil en conséquence. Si une charge utile personnalisée est retournée par le webhook, elle est transmise à l’appareil avec les détails sur le hub IoT affecté et l’authentification dans la réponse d’inscription du DPS.
L’appareil se connecte au hub IoT affecté et télécharge son état de jumeau initial. Si une charge utile personnalisée est retournée dans la réponse d’inscription, l’appareil l’utilise conformément à sa propre logique côté client.

Les sections suivantes fournissent plus de détails sur la demande et la réponse d’allocation personnalisée, les charges utiles personnalisées et l’implémentation de la stratégie. Pour obtenir un exemple complet de bout en bout de stratégie d’allocation personnalisée, consultez Utiliser des stratégies d’allocation personnalisée.

Demande de stratégie d’allocation personnalisée

Le DPS envoie une requête POST à votre webhook sur le point de terminaison suivant : https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Le corps de la requête est un objet AllocationRequest :

Nom de la propriété	Description
individualEnrollment	Enregistrement d’inscription individuelle contenant les propriétés associées à l’inscription individuelle dont provient la demande d’allocation. Présent si l’appareil s’inscrit via une inscription individuelle.
enrollmentGroup	Enregistrement de groupe d’inscriptions contenant les propriétés associées au groupe d’inscriptions dont provient la demande d’allocation. Présent si l’appareil s’inscrit via un groupe d’inscriptions.
deviceRuntimeContext	Objet contenant des propriétés associées à l’appareil qui s’inscrit. Toujours présent.
linkedHubs	Tableau contenant les noms d’hôte des hubs IoT liés à l’entrée d’inscription dont provient la demande d’allocation. L’appareil peut être affecté à n’importe lequel de ces hubs IoT. Toujours présent.

L’objet DeviceRuntimeContext a les propriétés suivantes :

Propriété	Type	Description
registrationId	string	ID d’inscription fourni par l’appareil lors de l’exécution. Toujours présent.
currentIotHubHostName	string	Nom d’hôte du hub IoT auquel l’appareil était précédemment affecté (le cas échéant). Non présent s’il s’agit d’une affectation initiale. Vous pouvez utiliser cette propriété pour déterminer s’il s’agit d’une affectation initiale pour l’appareil ou si l’appareil a été affecté auparavant.
currentDeviceId	string	ID d’appareil de l’affectation précédente de l’appareil (le cas échéant). Non présent s’il s’agit d’une affectation initiale.
x509	X509DeviceAttestation	Pour l’attestation X.509, contient les détails du certificat.
symmetricKey	SymmetricKeyAttestation	Pour l’attestation de clé symétrique, contient les détails de clé primaire et secondaire.
tpm	TpmAttestation	Pour l’attestation TPM, contient des détails de paire de clés de type EK (Endorsement Key) et de clé racine de stockage.
payload	object	Contient les propriétés spécifiées par l’appareil dans la propriété de charge utile pendant l’inscription. Présent si l’appareil envoie une charge utile personnalisée dans la demande d’inscription auprès du DPS.

Le code JSON suivant montre l’objet AllocationRequest envoyé par le DPS pour un appareil s’inscrivant via un groupe d’inscriptions basé sur une clé symétrique.

{
   "enrollmentGroup":{
      "enrollmentGroupId":"contoso-custom-allocated-devices",
      "attestation":{
         "type":"symmetricKey"
      },
      "capabilities":{
         "iotEdge":false
      },
      "etag":"\"13003fea-0000-0300-0000-62d1d5e50000\"",
      "provisioningStatus":"enabled",
      "reprovisionPolicy":{
         "updateHubAssignment":true,
         "migrateDeviceData":true
      },
      "createdDateTimeUtc":"2022-07-05T21:27:16.8123235Z",
      "lastUpdatedDateTimeUtc":"2022-07-15T21:02:29.5922255Z",
      "allocationPolicy":"custom",
      "iotHubs":[
         "custom-allocation-toasters-hub.azure-devices.net",
         "custom-allocation-heatpumps-hub.azure-devices.net"
      ],
      "customAllocationDefinition":{
         "webhookUrl":"https://custom-allocation-function-app-3.azurewebsites.net/api/HttpTrigger1?****",
         "apiVersion":"2021-10-01"
      }
   },
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
   "linkedHubs":[
      "custom-allocation-toasters-hub.azure-devices.net",
      "custom-allocation-heatpumps-hub.azure-devices.net"
   ]
}

Étant donné qu’il s’agit de l’inscription initiale de l’appareil, la propriété deviceRuntimeContext contient uniquement l’ID d’inscription et les détails d’authentification de l’appareil. Le code JSON suivant montre la propriété deviceRuntimeContext d’un appel subséquent pour inscrire le même appareil. Notez que le nom d’hôte et l’ID d’appareil IoT Hub actuels sont inclus dans la demande.

{
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
      "currentDeviceId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
}

Réponse de stratégie d’allocation personnalisée

Une requête réussie retourne un objet AllocationResponse.

Propriété	Description
initialTwin	facultatif. Objet contenant les propriétés et balises souhaitées à définir dans le jumeau initial sur le hub IoT affecté. DPS utilise la propriété initialTwin pour définir le jumeau initial sur le hub IoT affecté lors de l’affectation initiale ou lors de la reprovisionnement si la stratégie de migration de l’entrée d’inscription est définie sur Reprovisionner et réinitialiser la configuration initiale. Dans ces deux cas, si l’initialTwin n’est pas retourné ou est défini sur Null, DPS définit le jumeau sur le hub IoT affecté sur les paramètres de jumeau initial dans l’entrée d’inscription. DPS ignore l’initialTwin pour tous les autres paramètres de reprovisionnement dans l’entrée d’inscription. Pour plus d’informations, consultez Détails de l’implémentation.
iotHubHostName	Obligatoire. Nom d’hôte du hub IoT auquel affecter l’appareil. Il doit s’agir de l’un des hubs IoT transmis dans la propriété linkedHubs dans la requête.
payload	facultatif. Objet contenant des données à retourner à l’appareil dans la réponse d’inscription. Les données exactes dépendent du contrat implicite défini par le développeur entre l’appareil et la fonction d’allocation personnalisée.

Le code JSON suivant montre l’objet AllocationResponse retourné par une fonction d’allocation personnalisée au DPS pour l’exemple d’inscription ci-dessus.

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   }
}

Utiliser des charges utiles d’appareil dans une allocation personnalisée

Des appareils peuvent envoyer une charge utile personnalisée transmise par le DPS à votre webhook d’allocation personnalisée, qui peut ensuite utiliser ces données dans sa logique. Le webhook peut utiliser ces données de plusieurs façons, par exemple, pour déterminer le hub IoT auquel affecter l’appareil, ou pour rechercher dans une base de données externe des informations qui pourraient être utilisées pour définir des propriétés sur le jumeau initial. À l’inverse, votre webhook peut retourner à l’appareil via le DPS des données qui peuvent être utilisées dans la logique côté client de l’appareil.

Par exemple, vous pouvez allouer des appareils en fonction de leur modèle. Dans ce cas, vous pouvez configurer l’appareil pour qu’il transmette les informations sur son modèle dans la charge utile de la demande au moment de son inscription auprès du DPS. Le DPS transmet cette charge utile au webhook d’allocation personnalisée, qui détermine le hub IoT auquel l’appareil sera approvisionné en fonction des informations sur son modèle. Si nécessaire, le webhook peut retourner des données au DPS en tant qu’objet JSON dans la réponse du webhook, et le DPS retourne ces données à votre appareil dans la réponse d’inscription.

L’appareil envoie la charge utile de données à DPS

Un appareil appelle l’API d’inscription pour s’inscrire auprès du DPS. La requête peut être améliorée avec la propriété payload facultative. Cette propriété peut contenir n’importe quel objet JSON valide. Le contenu exact dépend des exigences de votre solution.

Pour l’attestation avec TPM, le corps de la demande ressemble à ce qui suit :

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

Le DPS envoie la charge utile de données au webhook d’allocation personnalisée

Si un appareil inclut une charge utile dans sa demande d’inscription, le DPS transmet la charge utile dans la propriété AllocationRequest.deviceRuntimeContext.payload quand il appelle le webhook d’allocation personnalisée.

Pour la demande d’inscription TPM dans la section précédente, le contexte du runtime de l’appareil se présente comme suit :

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

S’il ne s’agit pas de l’inscription initiale de l’appareil, le contexte du runtime inclut également le currentIoTHubHostname et les propriétés currentDeviceId.

Le webhook d’allocation personnalisée retourne des données au DPS

Le webhook de stratégie d’allocation personnalisée peut retourner au DPS des données destinées à un appareil dans un objet JSON en utilisant la propriété AllocationResponse.payload dans la réponse du webhook.

Le code JSON suivant montre une réponse de webhook qui inclut une charge utile :

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   },
   "payload": { "property1": "value1" } 
}

Le DPS envoie la charge utile de données à l’appareil

Si le DPS reçoit une charge utile dans la réponse du webhook, il transmet ces données à l’appareil dans la propriété RegistrationOperationStatus.registrationState.payload dans la réponse en cas d’inscription réussie. La propriété registrationState est de type DeviceRegistrationResult.

Le code JSON suivant montre une réponse d’inscription réussie pour un appareil TPM, qui inclut la propriété payload :

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "assignedHub":"myIotHub",
      "createdDateTimeUtc" : "2022-08-01T22:57:47Z",
      "deviceId" : "myDeviceId",
      "etag" : "xxxx-etag-value-xxxxx",
      "lastUpdatedDateTimeUtc" : "2022-08-01T22:57:47Z",
      "payload": { "property1": "value1" },
      "registrationId": "mydevice", 
      "status": assigned,
      "substatus": initialAssignment,
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"}
   }
}

Informations d’implémentation

Le webhook d’allocation personnalisée peut être appelé pour un appareil qui n’a pas été précédemment inscrit via le DPS (affectation initiale) ou pour un appareil qui a été précédemment inscrit via le DPS (réapprovisionnement). DPS prend en charge les stratégies de reprovisionnement suivantes : reprovisionner et migrer des données, reprovisionner et réinitialiser la configuration initiale et ne jamais reprovisionner. Ces stratégies sont appliquées chaque fois qu’un appareil précédemment approvisionné est affecté à un nouveau hub IoT. Pour plus d’informations, consultez Réapprovisionnement.

Les points suivants décrivent les exigences que votre webhook d’allocation personnalisée doit respecter, et le comportement dont vous devez être conscient lors de la conception de votre webhook :

L’appareil devrait être affecté à l’un des hubs IoT dans la propriété AllocationRequest.linkedHubs. Cette propriété contient la liste des hubs IoT par nom d’hôte, auxquels l’appareil peut être affecté. Elle comprend généralement les hubs IoT sélectionnés pour l’entrée d’inscription. Si aucun hub IoT n’est sélectionné dans l’entrée d’inscription, elle contient tous les hubs IoT liés à l’instance du DPS. Enfin, si l’appareil est reprovisionnement et que la stratégie de réapprovisionnement Never est définie sur l’entrée d’inscription, elle contient uniquement le hub IoT auquel l’appareil est actuellement affecté.
Lors de l’affectation initiale, si la propriété initialTwin est retournée par le webhook, le DPS définit le jumeau initial pour l’appareil sur le hub IoT affecté en conséquence. Si la propriété initialTwin est omise ou a la valeur null, le DPS définit le jumeau initial pour l’appareil sur le paramètre de jumeau initial spécifié dans l’entrée d’inscription.
Lors du réapprovisionnement, le DPS suit la stratégie de réapprovisionnement définie dans l’entrée d’inscription. DPS utilise uniquement la propriété initialTwin dans la réponse si le hub IoT actuel est modifié et que la stratégie de reprovisionnement définie sur l’entrée d’inscription est Reprovisionner et réinitialiser la configuration initiale. Dans ce cas, DPS définit le jumeau initial de l’appareil sur le nouveau hub IoT exactement comme lors de l’affectation initiale dans la puce précédente. Dans tous les autres cas, le DPS ignore la propriété initialTwin.
Si la propriété payload est définie dans la réponse, le DPS la retourne toujours à l’appareil, que la demande ait trait à l’affectation initiale ou à un réapprovisionnement.
Si un appareil a été précédemment approvisionné à un hub IoT, la propriété allocationRequest.deviceRuntimeContext contient une propriété currentIotHubHostName, qui sera définie sur le nom d’hôte du hub IoT où l’appareil est actuellement affecté.
Vous pouvez déterminer la stratégie de réapprovisionnement actuellement définie sur l’entrée d’inscription en examinant la propriété reprovisionPolicy de la propriété AllocationRequest.individualEnrollment ou allocationRequest.enrollmentGroup dans la demande. le code JSON suivant montre les paramètres de la stratégie de reprovisionnement et de migration des données :
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

Prise en charge de SDK

Les kits de développement logiciel (SDK) d’appareil de DPS fournissent des API en C, C#, Java et Node.js pour vous aider à inscrire des appareils auprès du DPS. Les kits de développement logiciel (SDK) IoT Hub et DPS fournissent des classes qui représentent des artefacts d’appareil et de service tels que des jumeaux d’appareil et des entrées d’inscription qui peuvent être utiles lors du développement de webhooks d’allocation personnalisée. Pour en savoir plus sur les kits de développement logiciel (SDK) Azure IoT disponibles pour IoT Hub et le service IoT Hub Device Provisioning, consultez Kits de développement logiciel (SDK) Azure IoT Hub et Kits de développement logiciel (SDK) Azure DPS.

Étapes suivantes

Pour obtenir un exemple de bout en bout d’utilisation d’une stratégie d’allocation personnalisée, consultez Utiliser des stratégies d’allocation personnalisée.
Pour en savoir plus sur Azure Functions, consultez la documentation Azure Functions.