Förstå anpassade allokeringsprinciper med Azure IoT Hub Device Provisioning Service

Artikel
03/18/2023

Anpassade allokeringsprinciper ger dig mer kontroll över hur enheter tilldelas till dina IoT-hubbar. Genom att använda anpassade allokeringsprinciper kan du definiera dina egna allokeringsprinciper när de inbyggda principerna som tillhandahålls av Device Provisioning Service (DPS) inte uppfyller kraven i ditt scenario.

Du kanske till exempel vill undersöka certifikatet som en enhet använder under etableringen och tilldela enheten till en IoT-hubb baserat på en certifikategenskap. Eller så kanske du har information lagrad i en databas för dina enheter och behöver fråga databasen för att avgöra vilken IoT-hubb en enhet ska tilldelas till eller hur enhetens första tvilling ska anges.

Du implementerar en anpassad allokeringsprincip i en webhook som finns i Azure Functions. Du kan sedan konfigurera webhooken i en eller flera enskilda registreringar och registreringsgrupper. När en enhet registreras via en konfigurerad registreringspost anropar DPS webhooken som returnerar IoT-hubben för att registrera enheten till och, om du vill, de första tvillinginställningarna för enheten och all information som ska returneras direkt till enheten.

Översikt

Följande steg beskriver hur anpassade allokeringsprinciper fungerar:

En anpassad allokeringsutvecklare utvecklar en webhook som implementerar den avsedda allokeringsprincipen och distribuerar den som en HTTP-utlösarfunktion till Azure Functions. Webhooken tar information om DPS-registreringsposten och enheten och returnerar den IoT-hubb som enheten ska registreras till och, om du vill, information om enhetens ursprungliga tillstånd.
En IoT-operator konfigurerar en eller flera enskilda registreringar och/eller registreringsgrupper för anpassad allokering och tillhandahåller samtalsinformation för den anpassade allokeringswebbhooken i Azure Functions.
När en enhet registreras via en registreringspost som konfigurerats för webhooken för anpassad allokering skickar DPS en POST-begäran till webhooken med begärandetexten inställd på ett AllocationRequest-begärandeobjekt . AllocationRequest-objektet innehåller information om enheten som försöker etablera och den enskilda registrerings- eller registreringsgrupp som den etablerar via. Enhetsinformationen kan innehålla en valfri anpassad nyttolast som skickas från enheten i registreringsbegäran. Mer information finns i Begäran om anpassad allokeringsprincip.
Azure-funktionen kör och returnerar ett AllocationResponse-objekt när det lyckas. AllocationResponse-objektet innehåller den IoT-hubb som enheten ska etableras till, det inledande tvillingtillståndet och en valfri anpassad nyttolast för att återgå till enheten. Mer information finns i Svar på anpassad allokeringsprincip.
DPS tilldelar enheten till den IoT-hubb som anges i svaret, och om en första tvilling returneras anger den första tvillingen för enheten därefter. Om en anpassad nyttolast returneras av webhooken skickas den till enheten tillsammans med den tilldelade IoT-hubben och autentiseringsinformationen i registreringssvaret från DPS.
Enheten ansluter till den tilldelade IoT-hubben och laddar ned det ursprungliga tvillingtillståndet. Om en anpassad nyttolast returneras i registreringssvaret använder enheten den enligt sin egen logik på klientsidan.

Följande avsnitt innehåller mer information om anpassad allokeringsbegäran och svar, anpassade nyttolaster och principimplementering. Ett fullständigt exempel från slutpunkt till slutpunkt på en anpassad allokeringsprincip finns i Använda anpassade allokeringsprinciper.

Begäran om anpassad allokeringsprincip

DPS skickar en POST-begäran till din webhook på följande slutpunkt: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Begärandetexten är ett AllocationRequest-objekt :

Egenskapsnamn	Description
individualEnrollment	En enskild registreringspost som innehåller egenskaper som är associerade med den enskilda registreringen som allokeringsbegäran kommer från. Presentera om enheten registreras via en enskild registrering.
enrollmentGroup	En registreringsgrupppost som innehåller de egenskaper som är associerade med registreringsgruppen som allokeringsbegäran kommer från. Presentera om enheten registreras via en registreringsgrupp.
deviceRuntimeContext	Ett objekt som innehåller egenskaper som är associerade med enheten som registreras. Alltid närvarande.
linkedHubs	En matris som innehåller värdnamnen för de IoT-hubbar som är länkade till registreringsposten som allokeringsbegäran kommer från. Enheten kan tilldelas till någon av dessa IoT-hubbar. Alltid närvarande.

DeviceRuntimeContext-objektet har följande egenskaper:

Egenskap	Type	Description
registrationId	sträng	Registrerings-ID:t som tillhandahålls av enheten vid körning. Alltid närvarande.
currentIotHubHostName	sträng	Värdnamnet för den IoT-hubb som enheten tidigare tilldelades (om någon). Finns inte om det här är en första tilldelning. Du kan använda den här egenskapen för att avgöra om det här är en första tilldelning för enheten eller om enheten har tilldelats tidigare.
currentDeviceId	sträng	Enhets-ID:t från enhetens tidigare tilldelning (om det finns några). Finns inte om det här är en första tilldelning.
x509	X509Enhetsstation	För X.509-attestering innehåller certifikatinformation.
symmetricKey	SymmetricKeyAttestation	För symmetrisk nyckelattestering innehåller primär och sekundär nyckelinformation.
tpm	TpmAttestation	För TPM-attestering innehåller information om bekräftelsenyckel och lagringsrotnyckel.
payload	objekt	Innehåller egenskaper som anges av enheten i nyttolastegenskapen under registreringen. Presentera om enheten skickar en anpassad nyttolast i DPS-registreringsbegäran.

Följande JSON visar Det AllocationRequest-objekt som skickas av DPS för en enhet som registrerar sig via en symmetrisk nyckelbaserad registreringsgrupp.

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

Eftersom det här är den första registreringen för enheten innehåller egenskapen deviceRuntimeContext endast registrerings-ID:t och autentiseringsinformationen för enheten. Följande JSON visar deviceRuntimeContext för ett efterföljande anrop för att registrera samma enhet. Observera att det aktuella IoT Hub-värdnamnet och enhets-ID:t ingår i begäran.

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

Svar på anpassad allokeringsprincip

En lyckad begäran returnerar ett AllocationResponse-objekt .

Property	Beskrivning
initialTwin	Valfritt. Ett objekt som innehåller önskade egenskaper och taggar som ska anges i den första tvillingen på den tilldelade IoT-hubben. DPS använder egenskapen initialTwin för att ange den första tvillingen på den tilldelade IoT-hubben vid den första tilldelningen eller vid ometablering om registreringspostens migreringsprincip är inställd på Ometablera och återställa till den första konfigurationen. I båda dessa fall, om initialTwin inte returneras eller är inställt på null, ställer DPS in tvillingen på den tilldelade IoT-hubben till de första tvillinginställningarna i registreringsposten. DPS ignorerar initialTwin för alla andra återetableringsinställningar i registreringsposten. Mer information finns i Implementeringsinformation.
iotHubHostName	Obligatoriska. Värdnamnet för den IoT-hubb som enheten ska tilldelas till. Detta måste vara en av de IoT-hubbar som skickas i egenskapen linkedHubs i begäran.
payload	Valfritt. Ett objekt som innehåller data som ska skickas tillbaka till enheten i registreringssvaret. De exakta data beror på det implicita kontrakt som definierats av utvecklaren mellan enheten och den anpassade allokeringsfunktionen.

Följande JSON visar Det AllocationResponse-objekt som returneras av en anpassad allokeringsfunktion till DPS för exempelregistreringen ovan.

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

Använda enhetsnyttolaster i anpassad allokering

Enheter kan skicka en anpassad nyttolast som skickas av DPS till din anpassade allokeringswebbhook, som sedan kan använda dessa data i sin logik. Webhooken kan använda dessa data på flera olika sätt, kanske för att avgöra vilken IoT-hubb som ska tilldelas enheten till eller för att söka efter information i en extern databas som kan användas för att ange egenskaper för den första tvillingen. Omvänt kan webhooken returnera data tillbaka till enheten via DPS, som kan användas i enhetens logik på klientsidan.

Du kanske till exempel vill allokera enheter baserat på enhetsmodellen. I det här fallet kan du konfigurera enheten att rapportera sin modellinformation i nyttolasten för begäran när den registreras med DPS. DPS skickar den här nyttolasten till webhooken för anpassad allokering, som avgör vilken IoT-hubb som enheten ska etableras till baserat på information om enhetsmodellen. Om det behövs kan webhooken returnera data tillbaka till DPS som ett JSON-objekt i webhook-svaret, och DPS returnerar dessa data till enheten i registreringssvaret.

Enheten skickar datanyttolast till DPS

En enhet anropar register-API:et för att registrera med DPS. Begäran kan utökas med den valfria nyttolastegenskapen . Den här egenskapen kan innehålla valfritt giltigt JSON-objekt. Det exakta innehållet beror på kraven i din lösning.

För attestering med TPM ser begärandetexten ut så här:

{ 
    "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 skickar datanyttolast till anpassad allokeringswebbhook

Om en enhet innehåller en nyttolast för registreringsbegäran skickar DPS nyttolasten i egenskapen AllocationRequest.deviceRuntimeContext.payload när den anropar webhooken för anpassad allokering.

För TPM-registreringsbegäran i föregående avsnitt ser enhetskörningskontexten ut så här:

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

Om detta inte är den första registreringen för enheten innehåller körningskontexten även egenskaperna currentIoTHubHostname och currentDeviceId .

Anpassad allokeringswebbhook returnerar data till DPS

Webhooken för anpassad allokeringsprincip kan returnera data som är avsedda för en enhet till DPS i ett JSON-objekt med egenskapen AllocationResponse.payload i webhook-svaret.

Följande JSON visar ett webhook-svar som innehåller en nyttolast:

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

DPS skickar datanyttolast till enheten

Om DPS tar emot en nyttolast i webhook-svaret skickar den dessa data tillbaka till enheten i egenskapen RegistrationOperationStatus.registrationState.payload i svaret vid en lyckad registrering. Egenskapen registrationState är av typen DeviceRegistrationResult.

Följande JSON visar ett lyckat registreringssvar för en TPM-enhet som innehåller nyttolastegenskapen:

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

Implementeringsdetaljer

Den anpassade allokeringswebbhooken kan anropas för en enhet som inte tidigare har registrerats via DPS (inledande tilldelning) eller för en enhet som tidigare har registrerats via DPS (ometablering). DPS stöder följande principer för ometablering: Återskapa och migrera data, återskapa och återställa till den första konfigurationen och Etablera aldrig om. Dessa principer tillämpas när en tidigare etablerad enhet tilldelas till en ny IoT-hubb. Mer information finns i Ometablering.

Följande punkter beskriver de krav som din anpassade allokeringswebbhook måste observera och beteende som du bör känna till när du utformar din webhook:

Enheten ska tilldelas till en av IoT-hubbarna i egenskapen AllocationRequest.linkedHubs . Den här egenskapen innehåller listan över IoT-hubbar efter värdnamn som enheten kan tilldelas till. Detta består vanligtvis av de IoT-hubbar som valts för registreringsposten. Om inga IoT-hubbar har valts i registreringsposten innehåller den alla IoT-hubbar som är länkade till DPS-instansen. Slutligen, om enheten återskapas och principen Aldrig ometablering har angetts för registreringsposten, innehåller den endast den IoT-hubb som enheten för närvarande är tilldelad till.
Om den initiala egenskapenTwin returneras av webhooken vid den första tilldelningen anger DPS den första tvillingen för enheten på den tilldelade IoT-hubben i enlighet med detta. Om egenskapen initialTwin utelämnas eller är null anger DPS den första tvillingen för enheten till den inledande tvillinginställningen som anges i registreringsposten.
Vid ometablering följer DPS den princip för ometablering som angetts i registreringsposten. DPS använder endast initialTwin-egenskapen i svaret om den aktuella IoT-hubben ändras och ometableringsprincipen som angetts för registreringsposten är Ometablering och återställning till den första konfigurationen. I det här fallet anger DPS den första tvillingen för enheten på den nya IoT-hubben precis som den skulle göra under den första tilldelningen i föregående punkt. I alla andra fall ignorerar DPS den initiala egenskapenTwin .
Om nyttolastegenskapen anges i svaret returnerar DPS alltid den till enheten oavsett om begäran gäller för inledande tilldelning eller ometablering.
Om en enhet tidigare har etablerats till en IoT-hubb innehåller AllocationRequest.deviceRuntimeContext en currentIotHubHostName-egenskap , som anges till värdnamnet för den IoT-hubb där enheten för närvarande är tilldelad.
Du kan avgöra vilken av principerna för ometablering som för närvarande anges för registreringsposten genom att undersöka egenskapen reprovisionPolicy för antingen egenskapen AllocationRequest.individualEnrollment eller egenskapen AllocationRequest.enrollmentGroup i begäran. följande JSON visar inställningarna för principen Ometablera och migrera data :
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

SDK-support

DPS-enhets-SDK:er tillhandahåller API:er i C, C#, Java och Node.js som hjälper dig att registrera enheter med DPS. Både IoT Hub-SDK:erna och DPS-SDK:erna tillhandahåller klasser som representerar enhets- och tjänstartefakter som enhetstvillingar och registreringsposter som kan vara till hjälp när du utvecklar anpassade webhooks för allokering. Mer information om Azure IoT SDK:er som är tillgängliga för IoT Hub- och IoT Hub Device Provisioning-tjänsten finns i Azure IoT Hub SDK:er och Azure DPS SDK:er.

Nästa steg

Ett exempel från slutpunkt till slutpunkt med en anpassad allokeringsprincip finns i Använda anpassade allokeringsprinciper
Mer information om Azure Functions finns i Azure Functions-dokumentationen