Comment transférer des charges utiles entre des appareils et DPS

  • Article

Les appareils qui s’inscrivent auprès de DPS doivent fournir un ID d’inscription et des informations d’identification valides (clés ou certificats X.509) au moment de leur inscription. Toutefois, certaines solutions ou certains scénarios IoT peuvent imposer à l’appareil de fournir des données supplémentaires. Par exemple, un webhook de stratégie d’allocation personnalisée peut utiliser certaines informations (par exemple, un numéro de modèle d’appareil) pour sélectionner un hub IoT sur lequel approvisionner l’appareil. De même, un appareil peut avoir besoin de données supplémentaires dans la réponse d’inscription pour faciliter sa logique côté client. DPS permet aux appareils d’envoyer et de recevoir une charge utile facultative lors de leur inscription.

Quand utiliser cette fonctionnalité ?

Les scénarios courants d’envoi de charges utiles facultatives sont les suivants :

  • Les stratégies d’allocation personnalisées peuvent utiliser la charge utile de l’appareil pour vous aider à sélectionner un hub IoT pour un appareil ou à définir son jumeau initial. Par exemple, lorsque vous souhaitez allouer vos appareils en fonction du modèle d’appareil. Dans ce cas, vous pouvez configurer l’appareil pour qu’il transmette les informations sur son modèle au moment de son inscription. DPS transmet la charge utile de l’appareil au webhook d’allocation personnalisé. Votre webhook peut ensuite décider quel hub IoT sera approvisionné en fonction des informations de modèle de l’appareil. Si nécessaire, le webhook peut également renvoyer des données à l’appareil sous la forme d’un objet JSON dans la réponse du webhook. Pour plus d’informations, consultez Utiliser des charges utiles d’appareil dans une allocation personnalisée.

  • Les appareils IoT Plug-and-Play (PNP)peuvent utiliser la charge utile pour envoyer leur ID de modèle lorsqu’ils s’inscrivent auprès du DPS. Vous trouverez des exemples de cette utilisation dans les exemples PnP dans le Kit de développement logiciel (SDK) ou des exemples de référentiels. Par exemple, le thermostat PnP C# ou le contrôleur de température PnP Node.js.

  • Les appareils IoT Central qui se connectent via DPS doivent suivre les conventions IoT Plug-and-Play et envoyer leur ID de modèle lors de leur inscription. IoT Central utilise l’ID de modèle pour affecter l’appareil au modèle d’appareil qui convient. Pour en savoir plus, consultez Implémentation des appareils et meilleures pratiques pour IoT Central.

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

Lorsque votre appareil appelle Register Device pour s’inscrire auprès de DPS, il peut inclure des données supplémentaires dans la propriété payload. Par exemple, le code JSON suivant montre le corps d’une demande d’inscription à l’aide de l’attestation TPM :

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxx", 
        "storageRootKey": "xxx-device-storage-root-key-xxxx" 
    }, 
    "payload": { A JSON object that contains your additional data } 
}

La propriété payload doit être un objet JSON et peut contenir toutes les données pertinentes pour votre solution ou scénario IoT.

DPS renvoie des données à l’appareil

DPS peut retourner des données à l’appareil dans la réponse d’inscription. Actuellement, cette fonctionnalité est exclusivement utilisée dans les scénarios d’allocation personnalisée. De même, si le webhook de la stratégie d’allocation personnalisée doit renvoyer certaines données à l’appareil, il peut les renvoyer sous forme d’objet JSON dans la réponse du webhook. DPS transmet ensuite ces données dans la propriété registrationState.payload dans la réponse Register Device. Par exemple, le code JSON suivant montre le corps d’une réponse correcte à la demande d’inscription à l’aide de l’attestation TPM.

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "registrationId":"my-tpm-device",
      "createdDateTimeUtc":"2022-08-31T22:02:50.5163352Z",
      "assignedHub":"sample-iot-hub-1.azure-devices.net",
      "deviceId":"my-tpm-device",
      "status":"assigned",
      "substatus":"initialAssignment",
      "lastUpdatedDateTimeUtc":"2022-08-31T22:02:50.7370676Z",
      "etag":"xxxx-etag-value-xxxx",
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"},
      "payload": { A JSON object that contains the data returned by the webhook }
   }
}

La propriété payload doit être un objet JSON et peut contenir toutes les données pertinentes pour votre solution ou scénario IoT.

Prise en charge de SDK

Cette fonctionnalité est aussi disponible dans les Kits de développement logiciel (SDK) clients C, C#, JAVA et Node.js. 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 SDK Microsoft Azure IoT.

Prise en charge d’IoT Edge

À compter de la version 1.4, IoT Edge prend en charge l’envoi d’une charge utile de données contenue dans un fichier JSON. Le fichier de charge utile est lu et envoyé à DPS quand l’appareil est inscrit ou réinscrit, ce qui se produit généralement quand vous exécutez iotedge config apply pour la première fois. Vous pouvez également forcer sa relecture et son inscription en utilisant la commande de reprovisionnement de l’interface CLI : iotedge system reprovision.

Voici un exemple d’extrait de code de /etc/aziot/config.toml où la propriété payload est définie avec le chemin d’un fichier JSON local.

   [provisioning]
   source = "dps"
   global_endpoint = "https://global.azure-devices-provisioning.net"
   id_scope = "0ab1234C5D6"

   # Uncomment to send a custom payload during DPS registration
   payload = { uri = "file:///home/aziot/payload.json" }

Le fichier de charge utile (dans ce cas, /home/aziot/payload.json) peut contenir n’importe quel code JSON valide. Par exemple :

{
    "modelId": "dtmi:com:example:edgedevice;1"
}

Étapes suivantes