Grundlegendes zu benutzerdefinierten Zuordnungsrichtlinien mit Azure IoT Hub Device Provisioning Service

Artikel
03/18/2023

Mithilfe benutzerdefinierter Zuweisungsrichtlinien können Sie genauer steuern, wie Geräte Ihren IoT-Hubs zugewiesen werden. Durch die Verwendung von benutzerdefinierten Zuordnungsrichtlinien können Sie eigene Zuordnungsrichtlinien definieren, wenn die von Device Provisioning Service (DPS) bereitgestellten Richtlinien nicht den Anforderungen Ihres Szenarios entsprechen.

Beispielsweise möchten Sie eventuell das Zertifikat überprüfen, das während der Bereitstellung von einem Gerät verwendet wird, und das Gerät basierend auf einer Zertifikateigenschaft einem IoT-Hub zuweisen. Oder möglicherweise sind in einer Datenbank Informationen für Ihre Geräte gespeichert, und Sie müssen die Datenbank abfragen, um zu bestimmen, welchem IoT-Hub ein Gerät zugewiesen oder wie der anfängliche Gerätezwilling festgelegt werden soll.

Benutzerdefinierte Zuordnungsrichtlinien werden in einem in Azure Functions gehosteten Webhook implementiert. Anschließend können Sie den Webhook in einer oder mehreren einzelnen Registrierungen und Registrierungsgruppen konfigurieren. Wenn ein Gerät über einen konfigurierten Registrierungseintrag registriert wird, ruft DPS den Webhook auf, der den IoT-Hub für die Geräteregistrierung zurückgibt. Optional werden zudem die Einstellungen für den anfänglichen Gerätezwilling und alle Informationen zurückgegeben, die direkt an das Gerät zurückgegeben werden sollen.

Überblick

Mit den folgenden Schritten wird die Funktionsweise von benutzerdefinierten Zuordnungsrichtlinien beschrieben:

Entwickler*innen von benutzerdefinierten Zuordnungen entwickeln einen Webhook, der die gewünschte Zuordnungsrichtlinie implementiert und als HTTP-Triggerfunktion für Azure Functions bereitstellt. Der Webhook verwendet Informationen über den DPS-Registrierungseintrag und das Gerät und gibt den IoT-Hub zurück, für den das Gerät registriert werden soll. Optional werden zudem Informationen zum anfänglichen Status des Geräts zurückgegeben.
Ein*e IoT-Operator*in konfiguriert eine oder mehrere einzelne Registrierungen und/oder Registrierungsgruppen für benutzerdefinierte Zuordnungen und stellt Aufrufdetails für den Webhook der benutzerdefinierten Zuordnung in Azure Functions bereit.
Wenn ein Gerät über einen Registrierungseintrag registriert wird, der für den Webhook der benutzerdefinierten Zuordnung konfiguriert ist, sendet DPS eine POST-Anforderung an den Webhook. Der Anforderungstext ist dabei auf ein AllocationRequest-Anforderungsobjekt festgelegt. Das AllocationRequest-Objekt enthält Informationen zum Gerät, das versucht, eine Bereitstellung durchzuführen, sowie die einzelne Registrierung oder Registrierungsgruppe, über die die Bereitstellung erfolgt. Die Geräteinformationen können eine optionale benutzerdefinierte Payload enthalten, die vom Gerät in der zugehörigen Registrierungsanforderung gesendet wurde. Weitere Informationen finden Sie unter Anforderung der benutzerdefinierten Zuordnungsrichtlinie.
Die Azure-Funktion wird ausgeführt und gibt bei erfolgreicher Ausführung ein AllocationResponse-Objekt zurück. Das AllocationResponse-Objekt enthält den IoT-Hub, für den das Gerät bereitgestellt werden soll, den anfänglichen Zwillingsstatus und eine optionale benutzerdefinierte Payload, die an das Gerät zurückgegeben werden soll. Weitere Informationen finden Sie unter Antwort der benutzerdefinierten Zuordnungsrichtlinie.
DPS weist das Gerät dem IoT-Hub zu, der in der Antwort angegeben ist, und legt den anfänglichen Gerätezwilling fest (sofern ein anfänglicher Zwilling zurückgegeben wurde). Wenn eine benutzerdefinierte Payload vom Webhook zurückgegeben wird, wird sie gemeinsam mit dem zugewiesenen IoT-Hub und den Authentifizierungsdetails in der Registrierungsantwort von DPS an das Gerät übergeben.
Das Gerät stellt eine Verbindung mit dem zugewiesenen IoT-Hub her und lädt den anfänglichen Zwillingsstatus herunter. Wenn eine benutzerdefinierte Payload in der Registrierungsantwort zurückgegeben wird, verwendet das Gerät diese Informationen entsprechend seiner eigenen clientseitigen Logik.

In den folgenden Abschnitten finden Sie weitere Details zur Anforderung und Antwort der benutzerdefinierten Zuordnung, zu benutzerdefinierten Payloads sowie zur Richtlinienimplementierung. Ein vollständiges Beispiel einer benutzerdefinierten Zuordnungsrichtlinie finden Sie unter Verwenden von benutzerdefinierten Zuordnungsrichtlinien.

Anforderung der benutzerdefinierten Zuordnungsrichtlinie

DPS sendet eine POST-Anforderung an Ihren Webhook auf dem folgenden Endpunkt: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Der Anforderungstext ist ein AllocationRequest-Objekt:

Name der Eigenschaft	Beschreibung
individualEnrollment	Ein einzelner Registrierungsdatensatz mit Eigenschaften, die der einzelnen Registrierung zugeordnet sind, von der die Zuordnungsanforderung stammt. Dieser Datensatz ist vorhanden, wenn das Gerät über eine einzelne Registrierung registriert wird.
enrollmentGroup	Ein Registrierungsgruppendatensatz mit den Eigenschaften, die der Registrierungsgruppe zugeordnet sind, von der die Zuordnungsanforderung stammt. Dieser Datensatz ist vorhanden, wenn das Gerät über eine Registrierungsgruppe registriert wird.
deviceRuntimeContext	Ein Objekt mit Eigenschaften, die dem Gerät zugeordnet sind, für das die Registrierung durchgeführt wird. Immer vorhanden.
linkedHubs	Ein Array mit den Hostnamen der IoT-Hubs, die mit dem Registrierungseintrag verknüpft sind, von dem die Zuordnungsanforderung stammt. Das Gerät kann einem dieser IoT-Hubs zugewiesen werden. Immer vorhanden.

Das DeviceRuntimeContext-Objekt weist die folgenden Eigenschaften auf:

Eigenschaft	Type	Beschreibung
registrationId	Zeichenfolge	Die Registrierungs-ID, die vom Gerät zur Laufzeit bereitgestellt wird. Immer vorhanden.
currentIotHubHostName	Zeichenfolge	Der Hostname des IoT-Hubs, dem das Gerät zuvor zugewiesen war (sofern zutreffend). Dieser Eintrag ist nicht vorhanden, wenn es sich um eine anfängliche Zuordnung handelt. Sie können diese Eigenschaft verwenden, um festzustellen, ob es sich um eine anfängliche Zuordnung für das Gerät handelt oder ob das Gerät zuvor bereits zugewiesen wurde.
currentDeviceId	Zeichenfolge	Die Geräte-ID aus der vorherigen Zuordnung des Geräts (sofern vorhanden). Dieser Eintrag ist nicht vorhanden, wenn es sich um eine anfängliche Zuordnung handelt.
x509	X509DeviceAttestation	Dieser Eintrag enthält Zertifikatdetails für den X.509-Nachweis.
symmetricKey	SymmetricKeyAttestation	Dieser Eintrag enthält Details zum Primär- und Sekundärschlüssel für den Nachweis mit symmetrischen Schlüsseln.
tpm	TpmAttestation	Dieser Eintrag enthält Details zum Endorsement Key und Storage Root Key für den TPM-Nachweis.
payload	Objekt	Er enthält Eigenschaften, die vom Gerät während der Registrierung in der Payloadeigenschaft angegeben werden. Dieser Eintrag ist vorhanden, wenn das Gerät eine benutzerdefinierte Payload in der DPS-Registrierungsanforderung sendet.

Im folgenden JSON-Beispiel ist das AllocationRequest-Objekt gezeigt, das von DPS für eine Geräteregistrierung über eine auf symmetrischen Schlüsseln basierenden Registrierungsgruppe gesendet wird.

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

Da es sich um die anfängliche Registrierung für das Gerät handelt, enthält die deviceRuntimeContext-Eigenschaft lediglich die Registrierungs-ID und die Authentifizierungsdetails für das Gerät. Das folgende JSON-Beispiel zeigt deviceRuntimeContext für einen nachfolgenden Aufruf zur Registrierung desselben Geräts. Beachten Sie, dass der aktuelle IoT-Hub-Hostname und die Geräte-ID in der Anforderung enthalten sind.

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

Antwort der benutzerdefinierten Zuordnungsrichtlinie

Bei einer erfolgreichen Anforderung wird ein AllocationResponse-Objekt zurückgegeben.

Eigenschaft	Beschreibung
initialTwin	Optional. Ein Objekt mit den gewünschten Eigenschaften und Tags, die im anfänglichen Zwilling auf dem zugewiesenen IoT-Hub festgelegt werden sollen. DPS verwendet die initialTwin-Eigenschaft, um den anfänglichen Zwilling auf dem zugewiesenen IoT-Hub bei der anfänglichen Zuordnung oder beim Erneuten Bereitstellen festzulegen, wenn die Migrationsrichtlinie des Registrierungseintrags auf "Neu bereitstellen" festgelegt und auf die anfängliche Konfiguration zurückgesetzt wird. Wenn der initialTwin in beiden Fällen nicht zurückgegeben oder auf NULL festgelegt ist, legt DPS den Zwilling auf dem zugewiesenen IoT-Hub auf die anfänglichen Zwillingseinstellungen im Registrierungseintrag fest. DPS ignoriert den initialTwin für alle anderen Neueinstellungen im Registrierungseintrag. Weitere Informationen finden Sie unter Implementierungsdetails.
iotHubHostName	Erforderlich. Der Hostname des IoT-Hubs, dem das Gerät zugewiesen werden soll. Dies muss einer der IoT-Hubs sein, die in der linkedHubs-Eigenschaft in der Anforderung übergeben wurden.
payload	Optional. Ein Objekt mit Daten, die in der Registrierungsantwort wieder an das Gerät übergeben werden sollen. Die genauen Daten hängen vom impliziten Vertrag ab, der von Entwickler*innen zwischen Gerät und benutzerdefinierter Zuordnungsfunktion definiert wird.

Das folgende JSON-Beispiel zeigt das AllocationResponse-Objekt, das von einer benutzerdefinierten Zuordnungsfunktion für die obige Beispielregistrierung an DPS zurückgegeben wird.

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

Verwenden von Gerätepayloads in einer benutzerdefinierten Zuordnung

Geräte können eine benutzerdefinierte Payload senden, die von DPS an Ihren Webhook für die benutzerdefinierte Zuordnung übergeben wird, der die Daten dann in seiner Logik verwenden kann. Der Webhook kann diese Daten auf verschiedene Weise verwenden. Beispielsweise kann er damit bestimmen, welchem IoT-Hub das Gerät zugewiesen werden soll. Oder er sucht mit diesen Daten nach Informationen in einer externen Datenbank, die zum Festlegen von Eigenschaften für den anfänglichen Zwilling verwendet werden können. Umgekehrt kann Ihr Webhook Daten über DPS an das Gerät zurückgeben. Diese können dann in der clientseitigen Logik des Geräts verwendet werden.

Beispiel: Sie möchten Geräte basierend auf dem Gerätemodell zuordnen. In diesem Fall können Sie das Gerät so konfigurieren, dass es die zugehörigen Modellinformationen bei seiner Registrierung bei DPS in der Anforderungspayload meldet. DPS übergibt diese Payload an den Webhook für die benutzerdefinierte Zuordnung, der anhand der Gerätemodellinformationen bestimmt, für welchen IoT-Hub das Gerät bereitgestellt wird. Bei Bedarf kann der Webhook Daten als JSON-Objekt in der Webhookantwort an DPS zurückgeben. DPS gibt diese Daten in der Registrierungsantwort an Ihr Gerät zurück.

Gerät sendet Datennutzlast an DPS

Ein Gerät ruft die Registrierungs-API auf, um sich bei DPS zu registrieren. Die Anforderung kann um die optionale payload-Eigenschaft erweitert werden. Diese Eigenschaft kann ein beliebiges gültiges JSON-Objekt enthalten. Der genaue Inhalt hängt von den Anforderungen Ihrer Lösung ab.

Für TPM-Nachweise sieht der Anforderungstext wie folgt aus:

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

DPS sendet die Datenpayload an den Webhook für die benutzerdefinierte Zuordnung

Falls die Registrierungsanforderung eines Geräts eine Payload enthält, übergibt DPS die Payload in der AllocationRequest.deviceRuntimeContext.payload-Eigenschaft, wenn der Webhook für die benutzerdefinierte Zuordnung aufgerufen wird.

Für die TPM-Registrierungsanforderung im vorherigen Abschnitt sieht der Gerätelaufzeitkontext wie folgt aus:

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

Wenn dies nicht die erste Registrierung für das Gerät ist, enthält der Laufzeitkontext zudem die Eigenschaften currentIoTHubHostname und currentDeviceId.

Webhook für benutzerdefinierte Zuordnung gibt Daten an DPS zurück

Der Webhook für die benutzerdefinierte Zuordnungsrichtlinie kann Daten für ein Gerät in einem JSON-Objekt an DPS zurückgeben. Dazu wird in der Webhookantwort die AllocationResponse.payload-Eigenschaft verwendet.

Das folgende JSON-Beispiel zeigt eine Webhookantwort, die eine Payload enthält:

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

DPS sendet eine Datenpayload an das Gerät

Wenn DPS in der Webhookantwort eine Payload empfängt, werden diese Daten bei einer erfolgreichen Registrierung in der RegistrationOperationStatus.registrationState.payload-Eigenschaft der Antwort an das Gerät zurückgegeben. Die registrationState-Eigenschaft weist den Typ DeviceRegistrationResult auf.

Das folgende JSON-Beispiel zeigt die Antwort bei erfolgreicher Registrierung für ein TPM-Gerät mit der payload-Eigenschaft:

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

Details zur Implementierung

Der Webhook für die benutzerdefinierte Zuordnung kann sowohl für ein Gerät aufgerufen werden, das zuvor nicht über DPS registriert wurde (anfängliche Zuordnung), als auch für ein Gerät, das zuvor über DPS registriert wurde (erneute Bereitstellung). DPS unterstützt die folgenden Neuanstellungsrichtlinien: Erneute Bereitstellung und Migrieren von Daten, Erneute Bereitstellung und Zurücksetzen auf die anfängliche Konfiguration und Nie erneute Bereitstellung. Diese Richtlinien werden angewendet, wenn ein zuvor bereitgestelltes Gerät einem neuen IoT-Hub zugewiesen wird. Weitere Informationen finden Sie unter Erneute Bereitstellung.

In den folgenden Punkten werden die Anforderungen beschrieben, die Ihr Webhook für die benutzerdefinierte Zuordnung beachten muss. Außerdem wird das Verhalten beschrieben, das Sie beim Entwerfen Ihres Webhooks beachten sollten:

Das Gerät sollte einem der IoT-Hubs in der AllocationRequest.linkedHubs-Eigenschaft zugeordnet werden. Diese Eigenschaft enthält die Liste der IoT-Hubs nach Hostname, denen das Gerät zugewiesen werden kann. Üblicherweise besteht diese Liste aus den IoT-Hubs, die für den Registrierungseintrag ausgewählt wurden. Wenn keine IoT-Hubs im Registrierungseintrag ausgewählt sind, enthält die Liste alle IoT-Hubs, die mit der DPS-Instanz verknüpft sind. Wenn das Gerät neu bereitgestellt wird und die Richtlinie "Nie erneut bereitstellen " für den Registrierungseintrag festgelegt ist, enthält es nur den IoT-Hub, dem das Gerät derzeit zugewiesen ist.
Wenn bei der anfänglichen Zuweisung die initialTwin-Eigenschaft vom Webhook zurückgegeben wird, legt DPS den anfänglichen Zwilling für das Gerät entsprechend auf dem zugewiesenen IoT-Hub fest. Wenn die initialTwin-Eigenschaft ausgelassen wird oder der Wert dieser Eigenschaft null lautet, legt DPS den anfänglichen Zwilling für das Gerät auf die entsprechende Einstellung im Registrierungseintrag fest.
Bei der erneuten Bereitstellung befolgt DPS die Richtlinie für die erneute Bereitstellung, die im Registrierungseintrag festgelegt ist. DPS verwendet nur die initialTwin-Eigenschaft in der Antwort, wenn der aktuelle IoT-Hub geändert wird und die für den Registrierungseintrag festgelegte neu bereitgestellte Richtlinie erneut bereitgestellt und auf die ursprüngliche Konfiguration zurückgesetzt wird. In diesem Fall legt DPS den ersten Zwilling für das Gerät auf dem neuen IoT-Hub genau so fest, wie es bei der anfänglichen Zuordnung im vorherigen Aufzählungszeichen der Fall wäre. In allen anderen Fällen ignoriert DPS die initialTwin-Eigenschaft.
Wenn die payload-Eigenschaft in der Antwort festgelegt ist, gibt DPS die Payload immer an das Gerät zurück, und zwar unabhängig davon, ob die Anforderung für die anfängliche Zuordnung oder für die erneute Bereitstellung gilt.
Wenn ein Gerät zuvor für einen IoT-Hub bereitgestellt wurde, enthält AllocationRequest.deviceRuntimeContext eine currentIotHubHostName-Eigenschaft, die auf den Hostnamen des IoT-Hubs festgelegt ist, dem das Gerät aktuell zugewiesen ist.
Anhand der reprovisionPolicy-Eigenschaft der Eigenschaft AllocationRequest.individualEnrollment oder AllocationRequest.enrollmentGroup in der Anforderung können Sie ermitteln, welche Richtlinie für die erneute Bereitstellung aktuell festgelegt ist. Der folgende JSON-Code zeigt die Einstellungen für die Richtlinie "Neu bereitstellen" und "Migrieren von Daten ":
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

SDK-Support

Die DPS-Geräte-SDKs bieten APIs in C, C#, Java und Node.js, um Sie bei der Registrierung von Geräten in DPS zu unterstützen. Sowohl die IoT-Hub-SDKs als auch die DPS-SDKs bieten Klassen zur Darstellung von Geräte- und Dienstartefakten wie Gerätezwillingen sowie Registrierungseinträge, die bei der Entwicklung von Webhooks für die benutzerdefinierte Zuordnung hilfreich sein können. Weitere Informationen zu den Azure IoT-SDKs, die für IoT Hub und IoT Hub Device Provisioning Service verfügbar sind, finden Sie unter Azure IoT Hub-SDKs und Azure DPS-SDKs.

Nächste Schritte

Ein vollständiges Beispiel einer benutzerdefinierten Zuordnungsrichtlinie finden Sie unter Verwenden von benutzerdefinierten Zuordnungsrichtlinien.
Weitere Informationen zu Azure Functions finden Sie in der Dokumentation zu Azure Functions