Inzicht in aangepast toewijzingsbeleid met Azure IoT Hub Device Provisioning Service

Artikel
03/18/2023

Met aangepast toewijzingsbeleid hebt u meer controle over hoe apparaten worden toegewezen aan uw IoT-hubs. Met behulp van aangepast toewijzingsbeleid kunt u uw eigen toewijzingsbeleid definiëren wanneer de ingebouwde beleidsregels van Device Provisioning Service (DPS) niet voldoen aan de vereisten van uw scenario.

Misschien wilt u bijvoorbeeld het certificaat bekijken dat door een apparaat wordt gebruikt tijdens het inrichten en het apparaat toewijzen aan een IoT-hub op basis van een certificaateigenschap. Of misschien hebt u informatie opgeslagen in een database voor uw apparaten en moet u een query uitvoeren op de database om te bepalen aan welke IoT-hub een apparaat moet worden toegewezen of hoe de eerste dubbel van het apparaat moet worden ingesteld.

U implementeert een aangepast toewijzingsbeleid in een webhook die wordt gehost in Azure Functions. Vervolgens kunt u de webhook configureren in een of meer afzonderlijke inschrijvingen en inschrijvingsgroepen. Wanneer een apparaat wordt geregistreerd via een geconfigureerde inschrijvingsvermelding, roept DPS de webhook aan die de IoT-hub retourneert om het apparaat te registreren en, optioneel, de eerste dubbele instellingen voor het apparaat en eventuele gegevens die rechtstreeks naar het apparaat moeten worden geretourneerd.

Overzicht

In de volgende stappen wordt beschreven hoe aangepast toewijzingsbeleid werkt:

Een ontwikkelaar van aangepaste toewijzing ontwikkelt een webhook die het beoogde toewijzingsbeleid implementeert en implementeert als een HTTP-triggerfunctie in Azure Functions. De webhook neemt informatie over de DPS-inschrijvingsvermelding en het apparaat en retourneert de IoT-hub waarnaar het apparaat moet worden geregistreerd en, optioneel, informatie over de oorspronkelijke status van het apparaat.
Een IoT-operator configureert een of meer afzonderlijke inschrijvings- en/of inschrijvingsgroepen voor aangepaste toewijzing en biedt aanroepende gegevens voor de webhook voor aangepaste toewijzing in Azure Functions.
Wanneer een apparaat wordt geregistreerd via een inschrijvingsvermelding die is geconfigureerd voor de aangepaste toewijzingswebhook, verzendt DPS een POST-aanvraag naar de webhook, waarbij de aanvraagbody is ingesteld op een AllocationRequest-aanvraagobject . Het Object AllocationRequest bevat informatie over het apparaat dat probeert in te richten en de afzonderlijke inschrijvings- of inschrijvingsgroep die het inricht. De apparaatgegevens kunnen een optionele aangepaste nettolading bevatten die is verzonden vanaf het apparaat in de registratieaanvraag. Zie Aanvraag voor aangepast toewijzingsbeleid voor meer informatie.
De Azure-functie voert een AllocationResponse-object uit en retourneert een geslaagd object. Het object AllocationResponse bevat de IoT-hub waaraan het apparaat moet worden ingericht, de eerste dubbele status en een optionele aangepaste nettolading om terug te keren naar het apparaat. Zie Antwoord op aangepast toewijzingsbeleid voor meer informatie.
DPS wijst het apparaat toe aan de IoT-hub die in het antwoord wordt aangegeven. Als er een eerste dubbel wordt geretourneerd, stelt u de eerste dubbel voor het apparaat dienovereenkomstig in. Als een aangepaste nettolading wordt geretourneerd door de webhook, wordt deze doorgegeven aan het apparaat, samen met de toegewezen IoT-hub en verificatiegegevens in het registratieantwoord van DPS.
Het apparaat maakt verbinding met de toegewezen IoT-hub en downloadt de oorspronkelijke dubbele status. Als een aangepaste nettolading wordt geretourneerd in het registratieantwoord, gebruikt het apparaat deze volgens de eigen logica aan de clientzijde.

In de volgende secties vindt u meer informatie over de aangepaste toewijzingsaanvraag en -respons, aangepaste nettoladingen en beleidsuitvoering. Zie Aangepast toewijzingsbeleid gebruiken voor een volledig end-to-end-voorbeeld van een aangepast toewijzingsbeleid.

Aanvraag voor aangepast toewijzingsbeleid

DPS verzendt een POST-aanvraag naar uw webhook op het volgende eindpunt: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

De aanvraagbody is een AllocationRequest-object :

Eigenschapsnaam	Beschrijving
individualEnrollment	Een afzonderlijke inschrijvingsrecord die eigenschappen bevat die zijn gekoppeld aan de afzonderlijke inschrijving waaruit de toewijzingsaanvraag afkomstig is. Aanwezig als het apparaat wordt geregistreerd via een afzonderlijke inschrijving.
enrollmentGroup	Een registratiegroeprecord die de eigenschappen bevat die zijn gekoppeld aan de inschrijvingsgroep waaruit de toewijzingsaanvraag afkomstig is. Aanwezig als het apparaat wordt geregistreerd via een inschrijvingsgroep.
deviceRuntimeContext	Een object dat eigenschappen bevat die zijn gekoppeld aan het apparaat dat wordt geregistreerd. Altijd aanwezig.
linkedHubs	Een matrix met de hostnamen van de IoT-hubs die zijn gekoppeld aan de inschrijvingsvermelding waaruit de toewijzingsaanvraag afkomstig is. Het apparaat kan worden toegewezen aan een van deze IoT-hubs. Altijd aanwezig.

Het object DeviceRuntimeContext heeft de volgende eigenschappen:

Eigenschap	Type	Description
registrationId	tekenreeks	De registratie-id die tijdens runtime door het apparaat is opgegeven. Altijd aanwezig.
currentIotHubHostName	tekenreeks	De hostnaam van de IoT-hub waaraan het apparaat eerder is toegewezen (indien van toepassing). Niet aanwezig als dit een eerste opdracht is. U kunt deze eigenschap gebruiken om te bepalen of dit een initiële toewijzing voor het apparaat is of of het apparaat eerder is toegewezen.
currentDeviceId	tekenreeks	De apparaat-id van de vorige toewijzing van het apparaat (indien van toepassing). Niet aanwezig als dit een eerste opdracht is.
x509	X509DeviceAttestation	Voor X.509-attestation bevat u certificaatgegevens.
symmetricKey	SymmetricKeyAttestation	Voor attestation van symmetrische sleutels bevat u primaire en secundaire sleuteldetails.
tpm	TpmAttestation	Voor TPM-attestation bevat goedkeuringssleutel- en opslaghoofdsleutelgegevens.
nettolading	object	Bevat eigenschappen die zijn opgegeven door het apparaat in de eigenschap nettolading tijdens de registratie. Aanwezig als het apparaat een aangepaste nettolading verzendt in de DPS-registratieaanvraag.

De volgende JSON toont het AllocationRequest-object dat door DPS is verzonden voor een apparaat dat wordt geregistreerd via een registratiegroep op basis van een symmetrische sleutel.

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

Omdat dit de eerste registratie voor het apparaat is, bevat de eigenschap deviceRuntimeContext alleen de registratie-id en de verificatiegegevens voor het apparaat. In de volgende JSON wordt de deviceRuntimeContext weergegeven voor een volgende aanroep om hetzelfde apparaat te registreren. U ziet dat de huidige Hostnaam en apparaat-id van IoT Hub zijn opgenomen in de aanvraag.

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

Antwoord op aangepast toewijzingsbeleid

Een geslaagde aanvraag retourneert een AllocationResponse-object .

Eigenschappen	Beschrijving
initialTwin	Optioneel. Een object dat de gewenste eigenschappen en tags bevat die moeten worden ingesteld in de eerste dubbel op de toegewezen IoT-hub. DPS gebruikt de eigenschap initialTwin om de eerste dubbel in te stellen op de toegewezen IoT-hub bij de eerste toewijzing of bij het opnieuw inrichten als het migratiebeleid van de inschrijvingsvermelding is ingesteld op Opnieuw inrichten en opnieuw instellen op de eerste configuratie. Als in beide gevallen de initialTwin niet wordt geretourneerd of als deze is ingesteld op null, stelt DPS de dubbel in op de toegewezen IoT-hub op de oorspronkelijke tweelinginstellingen in de inschrijvingsvermelding. DPS negeert de initialTwin voor alle andere herinrichtingsinstellingen in de inschrijvingsvermelding. Zie Implementatiedetails voor meer informatie.
iotHubHostName	Vereist. De hostnaam van de IoT-hub waaraan het apparaat moet worden toegewezen. Dit moet een van de IoT-hubs zijn die zijn doorgegeven in de eigenschap linkedHubs in de aanvraag.
nettolading	Optioneel. Een object dat gegevens bevat die moeten worden doorgestuurd naar het apparaat in het antwoord registratie. De exacte gegevens zijn afhankelijk van het impliciete contract dat is gedefinieerd door de ontwikkelaar tussen het apparaat en de aangepaste toewijzingsfunctie.

In de volgende JSON ziet u het object AllocationResponse dat wordt geretourneerd door een aangepaste toewijzingsfunctie voor DPS voor de bovenstaande voorbeeldregistratie.

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

Nettoladingen van apparaten gebruiken in aangepaste toewijzing

Apparaten kunnen een aangepaste nettolading verzenden die door DPS wordt doorgegeven aan uw webhook voor aangepaste toewijzing, die die gegevens vervolgens in de logica kan gebruiken. De webhook kan deze gegevens op verschillende manieren gebruiken, misschien om te bepalen aan welke IoT-hub het apparaat moet worden toegewezen of om informatie op te zoeken in een externe database die kan worden gebruikt om eigenschappen in te stellen op de eerste dubbel. Omgekeerd kan uw webhook gegevens terugsturen naar het apparaat via DPS, die kunnen worden gebruikt in de logica aan de clientzijde van het apparaat.

U kunt bijvoorbeeld apparaten toewijzen op basis van het apparaatmodel. In dit geval kunt u het apparaat configureren om de modelgegevens in de nettolading van de aanvraag te rapporteren wanneer het wordt geregistreerd bij DPS. DPS geeft deze nettolading door aan de webhook voor aangepaste toewijzing, waarmee wordt bepaald aan welke IoT-hub het apparaat wordt ingericht op basis van de gegevens van het apparaatmodel. Indien nodig kan de webhook gegevens als een JSON-object in het antwoord van de webhook retourneren naar de DPS. DPS retourneert deze gegevens naar uw apparaat in het registratieantwoord.

Apparaat verzendt nettolading van gegevens naar DPS

Een apparaat roept de register-API aan om zich te registreren bij DPS. De aanvraag kan worden uitgebreid met de optionele nettoladingeigenschap . Deze eigenschap kan elk geldig JSON-object bevatten. De exacte inhoud is afhankelijk van de vereisten van uw oplossing.

Voor attestation met TPM ziet de aanvraagbody er als volgt uit:

{ 
    "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 verzendt de nettolading van gegevens naar een aangepaste toewijzingswebhook

Als een apparaat een nettolading bevat, geeft DPS de nettolading door in de eigenschap AllocationRequest.deviceRuntimeContext.payload wanneer deze de aangepaste toewijzingswebhook aanroept.

Voor de TPM-registratieaanvraag in de vorige sectie ziet de context van de apparaatruntime er als volgt uit:

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

Als dit niet de eerste registratie voor het apparaat is, bevat de runtimecontext ook de currentIoTHubHostname en de eigenschappen currentDeviceId .

Aangepaste toewijzingswebhook retourneert gegevens naar DPS

De webhook voor aangepast toewijzingsbeleid kan gegevens retourneren die zijn bedoeld voor een apparaat naar DPS in een JSON-object met behulp van de eigenschap AllocationResponse.payload in het antwoord van de webhook.

In de volgende JSON ziet u een webhookantwoord dat een nettolading bevat:

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

DPS verzendt de nettolading van gegevens naar het apparaat

Als DPS een nettolading ontvangt in het antwoord van de webhook, worden deze gegevens teruggegeven aan het apparaat in de eigenschap RegistrationOperationStatus.registrationState.payload in het antwoord op een geslaagde registratie. De eigenschap registrationState is van het type DeviceRegistrationResult.

In de volgende JSON ziet u een geslaagd registratieantwoord voor een TPM-apparaat dat de eigenschap nettolading bevat:

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

Implementatiedetails

De webhook voor aangepaste toewijzing kan worden aangeroepen voor een apparaat dat niet eerder is geregistreerd via DPS (initiële toewijzing) of voor een apparaat dat eerder is geregistreerd via DPS (opnieuw inrichten). DPS ondersteunt het volgende beleid voor opnieuw inrichten: gegevens opnieuw inrichten en migreren, opnieuw inrichten en opnieuw instellen op de eerste configuratie en nooit opnieuw inrichten. Deze beleidsregels worden toegepast wanneer een eerder ingericht apparaat wordt toegewezen aan een nieuwe IoT-hub. Zie Opnieuw inrichten voor meer informatie.

In de volgende punten worden de vereisten beschreven die uw webhook voor aangepaste toewijzing moet observeren en gedrag moet hebben waarmee u rekening moet houden bij het ontwerpen van uw webhook:

Het apparaat moet worden toegewezen aan een van de IoT-hubs in de eigenschap AllocationRequest.linkedHubs . Deze eigenschap bevat de lijst met IoT-hubs op hostnaam waaraan het apparaat kan worden toegewezen. Dit bestaat doorgaans uit de IoT-hubs die zijn geselecteerd voor de inschrijvingsvermelding. Als er geen IoT-hubs zijn geselecteerd in de inschrijvingsvermelding, bevatten deze alle IoT-hubs die zijn gekoppeld aan het DPS-exemplaar. Als het apparaat opnieuw wordt ingericht en het beleid voor nooit opnieuw inrichten is ingesteld op de inschrijvingsvermelding, bevat het alleen de IoT-hub waaraan het apparaat momenteel is toegewezen.
Als bij de eerste toewijzing de initialTwin-eigenschap wordt geretourneerd door de webhook, stelt DPS de eerste dubbel in voor het apparaat op de toegewezen IoT-hub. Als de eigenschap initialTwin wordt weggelaten of null is, stelt DPS de eerste dubbel voor het apparaat in op de initiële tweelinginstelling die is opgegeven in de inschrijvingsvermelding.
Bij het opnieuw inrichten volgt DPS het beleid voor opnieuw inrichten dat is ingesteld in de inschrijvingsvermelding. DPS maakt alleen gebruik van initialTwin-eigenschap in het antwoord als de huidige IoT-hub wordt gewijzigd en het beleid voor opnieuw inrichten dat is ingesteld op de inschrijvingsvermelding, opnieuw wordt ingericht en opnieuw wordt ingesteld op de eerste configuratie. In dit geval stelt DPS de eerste dubbel voor het apparaat in op de nieuwe IoT-hub, precies zoals tijdens de eerste toewijzing in het vorige opsommingsteken. In alle andere gevallen negeert DPS de eigenschap initialTwin .
Als de eigenschap nettolading is ingesteld in het antwoord, retourneert DPS deze altijd naar het apparaat, ongeacht of de aanvraag voor de eerste toewijzing of het opnieuw inrichten is.
Als een apparaat eerder is ingericht voor een IoT-hub, bevat de AllocationRequest.deviceRuntimeContext een currentIotHubHostName-eigenschap , die wordt ingesteld op de hostnaam van de IoT-hub waaraan het apparaat momenteel is toegewezen.
U kunt bepalen welke beleidsregels voor opnieuw inrichten momenteel zijn ingesteld voor de inschrijvingsvermelding door de eigenschap reprovisionPolicy van de eigenschap AllocationRequest.individualEnrollment of de eigenschap AllocationRequest.enrollmentGroup in de aanvraag te bekijken. de volgende JSON toont de instellingen voor het beleid voor opnieuw inrichten en migreren van gegevens :
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

SDK-ondersteuning

De SDK's voor DPS-apparaten bieden API's in C, C#, Java en Node.js waarmee u apparaten kunt registreren bij DPS. Zowel de IoT Hub SDK's als de DPS-SDK's bieden klassen die apparaat- en serviceartefacten vertegenwoordigen, zoals apparaatdubbels en inschrijvingsvermeldingen die nuttig kunnen zijn bij het ontwikkelen van webhooks voor aangepaste toewijzing. Zie Azure IoT Hub SDK's en Azure DPS SDK's voor meer informatie over de Azure IoT SDK's die beschikbaar zijn voor IoT Hub en IoT Hub Device Provisioning Service.

Volgende stappen

Zie Aangepast toewijzingsbeleid gebruiken voor een end-to-end-voorbeeld met een aangepast toewijzingsbeleid
Raadpleeg de Documentatie voor Azure Functions voor meer informatie over Azure Functions

Delen via