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.

Sie implementieren eine benutzerdefinierte Zuordnungsrichtlinie in einem in Azure Functions gehosteten Webhook. 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 benutzerdefinierten Zuordnungswebhook konfiguriert ist, sendet DPS eine POST-Anforderung an den Webhook, wobei der Anforderungstext auf ein AllocationRequest-Anforderungsobjekt festgelegt ist. Das AllocationRequest -Objekt enthält Informationen über das Gerät, das bereitgestellt werden soll, und die einzelne Registrierung oder Registrierungsgruppe, über die es bereitgestellt wird. 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 einer benutzerdefinierten Zuordnungsrichtlinie.

4. Die Azure-Funktion wird ausgeführt und gibt ein AllocationResponse-Objekt bei Erfolg zurück. Das AllocationResponse -Objekt enthält den IoT-Hub, an dem das Gerät bereitgestellt werden soll, den anfänglichen Twin-Zustand und eine optionale benutzerdefinierte Nutzlast, um zum Gerät zurückzukehren. Weitere Informationen finden Sie in der Antwort auf benutzerdefinierte Zuordnungsrichtlinien.

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 Nutzlast vom Webhook zurückgegeben wird, wird sie zusammen mit den zugewiesenen IoT-Hub- und 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. Weitere Informationen zu einem vollständigen End-to-End-Beispiel einer benutzerdefinierten Zuordnungsrichtlinie finden Sie im Lernprogramm: Verwenden von benutzerdefinierten Zuordnungsrichtlinien mit Device Provisioning Service (DPS).For more information about a complete end-to-end example of a custom allocation policy, see Tutorial: Use custom allocation policies with Device Provisioning Service (DPS).

Verwalten von Funktionsschlüsseln

Benutzerdefinierte Zuordnungsrichtlinien verwenden Funktionsschlüssel, um Aufrufe von Azure Functions zu authentifizieren, auf die die Autorisierungsstufe Function festgelegt ist. Das Verhalten der Schlüsselverwaltung unterscheidet sich je nachdem, ob Sie die benutzerdefinierte Zuordnungsrichtlinie über das Azure-Portal oder programmgesteuert konfigurieren.

Funktionsschlüssel im Portal

Wenn Sie eine Registrierung im Azure-Portal erstellen und eine benutzerdefinierte Zuordnungsrichtlinie angeben, verarbeitet das Portal automatisch das Abrufen und Einbetten des Funktionsschlüssels.

Nachdem Sie die Funktion für die benutzerdefinierte Zuordnungsrichtlinie ausgewählt haben, ruft das Portal den Funktionsschlüssel ab. Dieser Schritt ist für Benutzer über die Portalschnittstelle nicht sichtbar. Anschließend wird der Funktionsschlüssel als Teil der verschlüsselten Webhook-URL gespeichert, die von DPS zum Aufrufen der Funktion verwendet wird. Der Schlüssel wird nicht im Portal angezeigt.

Sie können überprüfen, ob der Schlüssel in die Webhook-URL eingebettet ist, indem Sie einen GET-Befehl ausführen, um die Registrierungsdetails abzurufen. In der Registrierungskonfiguration ist der Funktionsschlüssel im WebhookUrl-Feld enthalten.

Funktionsschlüssel mit APIs

Wenn Sie eine Registrierung programmgesteuert mithilfe der DPS-API erstellen, müssen Sie den Schlüssel während der Erstellung der Registrierung manuell bereitstellen. Wenn der Schlüssel nicht bereitgestellt wird, schlägt der Azure Functions-Aufruf die Authentifizierung fehl.

Rufen Sie vor dem Erstellen der Einzel- oder Gruppenregistrierung den Funktionsschlüssel aus Ihrer Funktion ab. Weitere Informationen finden Sie unter Abrufen ihrer Funktionszugriffsschlüssel. Schließen Sie dann den Funktionsschlüssel in das WebhookUrl-Feld der CustomAllocationDefinition ein.

Weitere Informationen zur Zugriffsschlüsselautorisierung finden Sie hier.

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 verfügt über die folgenden Eigenschaften:

Der folgende JSON-Code zeigt das AllocationRequest-Objekt , das von DPS für ein Gerät gesendet wird, das über eine symmetrische schlüsselbasierte Registrierungsgruppe registriert 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 dies die anfängliche Registrierung für das Gerät ist, enthält die deviceRuntimeContext-Eigenschaft nur die Registrierungs-ID und die Authentifizierungsdetails für das Gerät. Der folgende JSON-Code zeigt den deviceRuntimeContext für einen nachfolgenden Aufruf zum Registrieren 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

Eine erfolgreiche Anforderung gibt ein AllocationResponse-Objekt zurück.

Der folgende JSON-Code zeigt das AllocationResponse-Objekt , das von einer benutzerdefinierten Zuordnungsfunktion an DPS für die Registrierung im vorherigen Beispiel 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 vielfältige Weise verwenden, z. B. um zu bestimmen, welchem IoT-Hub das Gerät zugewiesen werden soll, oder um Informationen in einer externen Datenbank nachzuschlagen, die verwendet werden kann, um Eigenschaften für den ersten Zwilling festzulegen. Umgekehrt kann Ihr Webhook Daten über DPS zurück an das Gerät zurückgeben, die möglicherweise in der clientseitigen Logik des Geräts verwendet werden.

Sie können z. B. 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 Nutzlast an den benutzerdefinierten Zuordnungswebhook, der bestimmt, auf welcher IoT-Hub das Gerät basierend auf den Gerätemodellinformationen bereitgestellt wird. Bei Bedarf kann der Webhook Daten als JSON-Objekt in der Webhook-Antwort zurück an das DPS zurückgeben, und DPS gibt diese Daten in der Registrierungsantwort an Ihr Gerät zurück.

Gerät sendet Datennutzlast an DPS

Ein Gerät ruft die DPS-Registrierungs-API auf, um sich bei DPS zu registrieren. Die Anforderung kann mit der optionalen Nutzlast-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 folgendes Beispiel 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

Wenn ein Gerät eine Nutzlast in ihrer Registrierungsanforderung enthält, übergibt DPS die Nutzlast in der AllocationRequest.deviceRuntimeContext.payload-Eigenschaft, wenn er den benutzerdefinierten Zuordnungs-Webhook aufruft.

Für die TPM-Registrierungsanforderung im vorherigen Abschnitt sieht der Gerätelaufzeitkontext wie im folgenden Beispiel 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 anfängliche Registrierung für das Gerät ist, enthält der Laufzeitkontext auch den currentIoTHubHostname und die currentDeviceId-Eigenschaften .

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

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

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 Nutzdaten 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 ist vom Typ DeviceRegistrationResult.

Der folgende JSON-Code zeigt eine erfolgreiche Registrierungsantwort, die die Payload-Eigenschaft für ein TPM-Gerät enthält.

{
   "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 benutzerdefinierte Zuordnungswebhook kann für ein Gerät aufgerufen werden, das zuvor nicht über DPS (anfängliche Zuordnung) oder für ein Gerät aufgerufen wurde, 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 den Reprovisioning-Konzepten für IoT Hub Geräte.

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 zugewiesen 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 im Registrierungseintrag keine IoT-Hubs ausgewählt sind, enthält sie 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 null ist, legt DPS den ersten Zwilling für das Gerät auf die anfängliche Zwillingseinstellung fest, die im Registrierungseintrag angegeben ist.

• 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 der AllocationRequest.deviceRuntimeContext eine currentIotHubHostName-Eigenschaft , die auf den Hostnamen des IoT-Hubs festgelegt ist, dem das Gerät derzeit zugewiesen ist.

• Sie können bestimmen, welche der Reprovisioning-Richtlinien derzeit für den Registrierungseintrag festgelegt ist, indem Sie die reprovisionPolicy-Eigenschaft entweder der AllocationRequest.individualEnrollment- oder der AllocationRequest.enrollmentGroup-Eigenschaft in der Anfrage untersuchen. Der folgende JSON-Code zeigt die Einstellungen für die Richtlinie "Neu bereitstellen" und "Migrieren von Daten ":

         "reprovisionPolicy":{
            "updateHubAssignment":true,
            "migrateDeviceData":true
         }
  

SDK-Unterstützung

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 den Bereitstellungsdienst für IoT-Hub- und IoT Hub-Geräte verfügbar sind, finden Sie unter Azure IoT Hub SDKs und Microsoft SDKs für den Bereitstellungsdienst für IoT-Hub-Geräte.

Nächste Schritte

• Ein End-to-End-Beispiel mit einer benutzerdefinierten Zuordnungsrichtlinie finden Sie im Lernprogramm: Verwenden von benutzerdefinierten Zuordnungsrichtlinien mit Device Provisioning Service (DPS)

• Weitere Informationen zu Azure Functions finden Sie in der Dokumentation zu Azure Functions