Grundlegendes zu benutzerdefinierten Zuordnungsrichtlinien mit Azure IoT Hub Device Provisioning Service

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.

Übersicht

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

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

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

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

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

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

6. 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:

Das DeviceRuntimeContext-Objekt weist die folgenden Eigenschaften auf:

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.

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 Richtlinien für die erneute Bereitstellung: Erneut bereitstellen und Daten migrieren, Erneut bereitstellen und auf ursprüngliche Konfiguration zurücksetzen und Nie erneut bereitstellen. 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 für das Gerät eine erneute Bereitstellung durchgeführt wird und die Richtlinie Nie erneut bereitstellen für den Registrierungseintrag festgelegt ist, ist in der Liste nur der IoT-Hub enthalten, dem das Gerät aktuell 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 Richtlinie für die erneute Bereitstellung auf Erneut bereitstellen und auf ursprüngliche Konfiguration zurücksetzen eingestellt ist. In diesem Fall legt DPS den ursprünglichen Zwilling für das Gerät auf dem neuen IoT-Hub genau so fest, wie es bei der ursprünglichen Zuordnung im vorherigen Aufzählungspunkt 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. Das folgende JSON-Beispiel zeigt die Einstellungen für die Richtlinie Erneut bereitstellen und Daten migrieren:

         "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