Übertragen von Nutzlasten zwischen Geräten und DPS

Artikel
03/15/2023

Geräte, die sich bei DPS registrieren, müssen beim Registrieren eine Registrierungs-ID und gültige Anmeldeinformationen (Schlüssel oder X.509-Zertifikate) bereitstellen. Es kann jedoch IoT-Lösungen oder -Szenarien geben, in denen zusätzliche Daten aus dem Gerät benötigt werden. Beispielsweise verwendet ein benutzerdefinierter Zuordnungsrichtlinien-Webhook vielleicht Informationen wie eine Gerätemodellnummer zum Auswählen eines IoT-Hubs, für den das Gerät bereitgestellt werden soll. Ebenso benötigt ein Gerät vielleicht zusätzliche Daten in der Registrierungsantwort zur Vereinfachung seiner clientseitigen Logik. DPS bietet die Möglichkeit für Geräte, bei ihrer Registrierung optionale Nutzdaten sowohl zu senden als auch zu empfangen.

Einsatzgebiete

Allgemeine Szenarien zum Senden von optionalen Nutzdaten sind folgende:

Benutzerdefinierte Zuordnungsrichtlinien können mithilfe der Gerätenutzdaten einen IoT-Hub für ein Gerät auswählen oder dessen ursprünglichen Zwilling festlegen. So möchten Sie beispielsweise Ihre Geräte anhand des Gerätemodells zuordnen. In diesem Fall können Sie das Gerät so konfigurieren, dass es die zugehörigen Modellinformationen bei seiner Registrierung meldet. DPS übergibt die Nutzlast des Geräts an den benutzerdefinierten Zuweisungswebhook. Anschließend kann Ihr Webhook basierend auf den Gerätemodellinformationen entscheiden, für welchen IoT-Hub das Gerät bereitgestellt wird. Bei Bedarf kann der Webhook in seiner Antwort Daten auch als JSON-Objekt an das Gerät zurückgeben. Weitere Informationen finden Sie unter Verwenden von Gerätenutzdaten in benutzerdefinierter Zuordnung.
IoT Plug & Play (PnP)-Geräte verwenden die Nutzdaten möglicherweise zum Senden ihrer Modell-ID, wenn sie sich bei DPS registrieren. Beispiele für diese Verwendung finden Sie in den PnP-Beispielen im SDK oder in Beispielrepositorys. Beispiel: C#-PnP-Thermostat oder Node.js-PnP-Temperaturcontroller.
IoT Central-Geräte, die sich über DPS verbinden, sollten bei ihrer Registrierung IoT Plug & Play-Konventionen folgen und ihre Modell-ID senden. IoT Central verwendet die Modell-ID, um das Gerät der richtigen Gerätevorlage zuzuweisen. Weitere Informationen finden Sie unter Geräteimplementierung und bewährte Methoden für IoT Central.

Gerät sendet Datennutzlast an DPS

Wenn Ihr Gerät Gerät registrieren aufruft, um sich bei DPS zu registrieren, kann es in die Eigenschaft Nutzdaten zusätzliche Daten einbeziehen. Das folgende JSON beispielsweise zeigt den Textkörper für eine Anforderung zum Registrieren mithilfe eines TPM-Nachweises:

{ 
    "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 } 
}

Die Eigenschaft Nutzdaten muss ein JSON-Objekt sein und kann beliebige Daten enthalten, die für Ihre IoT-Lösung oder Ihr IoT-Szenario relevant sind.

DPS gibt Daten an das Gerät zurück

DPS kann in der Registrierungsantwort Daten an das Gerät zurückgeben. Dieses Feature wird zurzeit ausschließlich in benutzerdefinierten Zuordnungsszenarien verwendet. Wenn der Webhook für die benutzerdefinierte Zuordnungsrichtlinie Daten an das Gerät zurückgeben muss, kann er sie in seiner Antwort als JSON-Objekt übergeben. DPS gibt dann diese Daten in der Eigenschaft registrationState.payload der Antwort „Gerät registrieren“ zurück. Das folgende JSON beispielsweise zeigt den Textkörper einer erfolgreichen Antwort zum Registrieren mithilfe eines TPM-Nachweises.

{
   "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 }
   }
}

Die Eigenschaft Nutzdaten muss ein JSON-Objekt sein und kann beliebige Daten enthalten, die für Ihre IoT-Lösung oder Ihr IoT-Szenario relevant sind.

SDK-Support

Diese Funktion ist in den Client-SDKs für C, C#, Java und Node.js verfügbar. Weitere Informationen zu den Azure IoT SDKs, die für IoT Hub und den IoT Hub Device Provisioning-Dienst verfügbar sind, finden Sie unter Microsoft Azure IoT SDKs.

IoT Edge-Unterstützung

Ab Version 1.4 unterstützt IoT Edge das Senden einer Datennutzlast, die in einer JSON-Datei enthalten ist. Die Nutzlastdatei wird gelesen und an DPS gesendet, wenn das Gerät (erneut)registriert wird. Dies geschieht normalerweise, wenn Sie iotedge config applyzum ersten Mal ausführen. Mithilfe des CLI-Befehls zur erneuten Bereitstellung (iotedge system reprovision) können Sie auch ein erneutes Lesen und die Registrierung erzwingen.

Nachfolgend finden Sie einen Beispielausschnitt aus /etc/aziot/config.toml, bei dem die Eigenschaft payload auf den Pfad einer lokalen JSON-Datei festgelegt wurde.

   [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" }

Die Nutzlastdatei (in diesem Fall /home/aziot/payload.json) kann beliebiges gültiges JSON enthalten wie z. B.:

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

Nächste Schritte

Eine Übersicht über benutzerdefinierte Zuordnungsrichtlinien finden Sie unter Grundlegendes zu benutzerdefinierten Zuordnungsrichtlinien.
Informationen zum Bereitstellen von Geräten mithilfe einer benutzerdefinierten Zuordnungsrichtlinie finden Sie unter Verwenden benutzerdefinierter Zuordnungsrichtlinien.

Freigeben über