Egyéni foglalási szabályzatok megismerése az Azure IoT Hub Device Provisioning Service használatával

Az egyéni foglalási szabályzatokkal jobban szabályozhatja, hogy az eszközök hogyan legyenek hozzárendelve az IoT Hubokhoz. Egyéni foglalási szabályzatok használatával saját foglalási szabályzatokat határozhat meg, ha a Device Provisioning Service (DPS) által biztosított beépített szabályzatok nem felelnek meg a forgatókönyv követelményeinek.

Előfordulhat például, hogy meg szeretné vizsgálni, hogy az eszköz milyen tanúsítványt használ a kiépítés során, és egy tanúsítványtulajdonság alapján rendelje hozzá az eszközt egy IoT Hubhoz. Vagy előfordulhat, hogy rendelkezik az eszközök adatbázisában tárolt információkkal, és le kell kérdeznie az adatbázist annak meghatározásához, hogy melyik IoT Hubhoz kell hozzárendelni az eszközt, vagy hogyan kell beállítani az eszköz kezdeti ikerpéldányát.

Egyéni foglalási szabályzatot implementálhat az Azure Functionsben üzemeltetett webhookban. Ezután konfigurálhatja a webhookot egy vagy több egyéni regisztrációs és regisztrációs csoportban. Amikor egy eszköz egy konfigurált regisztrációs bejegyzésen keresztül regisztrál, a DPS meghívja a webhookot, amely visszaadja az IoT Hubot, hogy regisztrálja az eszközt, és opcionálisan az eszköz kezdeti ikerbeállításait, valamint minden olyan információt, amelyet közvetlenül az eszköznek ad vissza.

Áttekintés

Az alábbi lépések az egyéni foglalási szabályzatok működését írják le:

1. Az egyéni foglalási fejlesztők létrehoznak egy webhookot, amely implementálja a kívánt foglalási szabályzatot, és HTTP-eseményindító függvényként telepíti azt az Azure Functionsben. A webhook adatokat vesz fel a DPS-regisztráció bejegyzéséről és az eszközről, és visszaadja azt az IoT Hubot, amelybe az eszközt regisztrálni kell, és opcionálisan információt ad az eszköz kezdeti állapotáról.

2. Az IoT-operátorok egy vagy több egyéni regisztrációt és/vagy regisztrációs csoportot konfigurálnak egyéni foglaláshoz, és az Azure Functions egyéni foglalási webhookjának hívási adatait biztosítják.

3. Amikor egy eszköz regisztrál egy egyéni foglalási webhookhoz konfigurált regisztrációs bejegyzésen keresztül, a DPS post kérést küld a webhooknak, amelynek a kérelem törzse egy AllocationRequest kérelemobjektumra van beállítva. A AllocationRequest objektum információkat tartalmaz a kiépíteni kívánt eszközről, valamint a kiépítendő egyéni regisztrációs vagy regisztrációs csoportról. Az eszközinformációk tartalmazhatnak az eszközről küldött opcionális egyéni hasznos adatokat a regisztrációs kérelemben. További információ: Egyéni foglalási szabályzat kérése.

4. Az Azure-függvény egy AllocationResponse objektumot hajt végre és ad vissza a sikerhez. A AllocationResponse objektum tartalmazza azt az IoT Hubot, amelybe az eszközt ki kell helyezni, a kezdeti ikerállapotot és egy opcionális egyéni hasznos adatot az eszközre való visszatéréshez. További információ: Egyéni foglalási szabályzat válasza.

5. A DPS hozzárendeli az eszközt a válaszban megjelölt IoT Hubhoz, és ha egy kezdeti ikerpéldányt ad vissza, ennek megfelelően állítja be az eszköz kezdeti ikerpéldányát. Ha a webhook egy egyéni hasznos adatot ad vissza, az át lesz adva az eszköznek a DPS regisztrációs válaszában szereplő hozzárendelt IoT Hubdal és hitelesítési adatokkal együtt.

6. Az eszköz csatlakozik a hozzárendelt IoT Hubhoz, és letölti a kezdeti ikerállapotát. Ha egyéni hasznos adatokat ad vissza a regisztrációs válaszban, az eszköz a saját ügyféloldali logikája szerint használja.

A következő szakaszok részletesebben ismertetik az egyéni foglalási kérelmet és választ, az egyéni hasznos adatokat és a szabályzat implementálását. Az egyéni foglalási szabályzatok teljes körű példáiért lásd : Egyéni foglalási szabályzatok használata.

Egyéni foglalási szabályzat kérése

A DPS post kérést küld a webhooknak a következő végponton: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

A kérelem törzse egy AllocationRequest objektum:

Tulajdonság neve	Leírás
individualEnrollment	Egyéni regisztrációs rekord , amely a foglalási kérelemhez tartozó egyedi regisztrációhoz társított tulajdonságokat tartalmazza. Akkor jelenik meg, ha az eszköz egyéni regisztráción keresztül regisztrál.
enrollmentGroup	Egy regisztrációs csoport rekordja , amely a foglalási kérelemhez tartozó regisztrációs csoporthoz társított tulajdonságokat tartalmazza. Jelenik meg, ha az eszköz regisztrál egy regisztrációs csoporton keresztül.
deviceRuntimeContext	Olyan objektum, amely a regisztráló eszközhöz társított tulajdonságokat tartalmazza. Mindig jelen van.
linkedHubs	Olyan tömb, amely tartalmazza a foglalási kérelem által kapott regisztrációs bejegyzéshez csatolt IoT Hubok állomásneveit. Az eszköz hozzárendelhető ezen IoT Hubok bármelyikéhez. Mindig jelen van.

A DeviceRuntimeContext objektum a következő tulajdonságokkal rendelkezik:

Tulajdonság	Típus	Leírás
registrationId	húr	Az eszköz által futásidőben megadott regisztrációs azonosító. Mindig jelen van.
currentIotHubHostName	húr	Annak az IoT Hubnak a gazdaneve, amelyhez az eszközt korábban hozzárendelték (ha van ilyen). Nem jelenik meg, ha ez egy kezdeti hozzárendelés. Ezzel a tulajdonságtal meghatározhatja, hogy ez az eszköz kezdeti hozzárendelése-e, vagy hogy az eszközt korábban hozzárendelték-e.
currentDeviceId	húr	Az eszköz azonosítója az eszköz előző hozzárendeléséből (ha van ilyen). Nem jelenik meg, ha ez egy kezdeti hozzárendelés.
x509	X509DeviceAttestation	Az X.509-igazolás esetében a tanúsítvány részletei szerepelnek.
symmetricKey	SymmetricKeyAttestation	Szimmetrikus kulcsigazolás esetén az elsődleges és a másodlagos kulcs adatait tartalmazza.
tpm	TpmAttestation	A TPM-igazoláshoz a támogatókulcs és a tároló gyökérkulcsának részletei találhatók.
payload	object	Az eszköz által a regisztráció során megadott tulajdonságokat tartalmazza a hasznos adat tulajdonságban. Akkor jelenik meg, ha az eszköz egyéni hasznos adatokat küld a DPS-regisztrációs kérelemben.

Az alábbi JSON a DPS által egy szimmetrikus kulcsalapú regisztrációs csoporton keresztül regisztráló eszköz számára küldött AllocationRequest objektumot mutatja be.

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

Mivel ez az eszköz kezdeti regisztrációja, az deviceRuntimeContext tulajdonság csak a regisztrációs azonosítót és az eszköz hitelesítési adatait tartalmazza. Az alábbi JSON az eszközRuntimeContext elemét jeleníti meg az ugyanazon eszköz regisztrálására irányuló későbbi híváshoz. Figyelje meg, hogy a kérés tartalmazza az aktuális IoT Hub-állomásnevet és eszközazonosítót.

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

Egyéni foglalási szabályzat válasza

A sikeres kérés egy AllocationResponse objektumot ad vissza.

Tulajdonság	Leírás
initialTwin	Opcionális. A hozzárendelt IoT Hub kezdeti ikerpéldányában beállítani kívánt tulajdonságokat és címkéket tartalmazó objektum. A DPS az initialTwin tulajdonság használatával állítja be a kezdeti ikerpéldányt a hozzárendelt IoT Hubon a kezdeti hozzárendeléskor, vagy ha a regisztrációs bejegyzés áttelepítési szabályzata újrabontásra van állítva, és alaphelyzetbe állítja a kezdeti konfigurációt. Mindkét esetben, ha az initialTwin nem lesz visszaadva, vagy null értékűre van állítva, a DPS a hozzárendelt IoT Hubon lévő ikerpéldányt a regisztrációs bejegyzés kezdeti ikerbeállításaira állítja. A DPS figyelmen kívül hagyja a regisztrációs bejegyzésben szereplő összes többi újraépítési beállítás kezdeti Twin-beállításait. További információ: Implementáció részletei.
iotHubHostName	Szükséges. Az IoT Hub állomásneve az eszköz hozzárendeléséhez. Ennek a kérelem linkedHubs tulajdonságában átadott IoT Hubok egyikének kell lennie.
payload	Opcionális. Olyan objektum, amely a regisztrációs válaszban visszaadandó adatokat tartalmazza az eszköznek. A pontos adatok a fejlesztő által az eszköz és az egyéni foglalási függvény között meghatározott implicit szerződéstől függnek.

Az alábbi JSON az egyéni foglalási függvény által a DPS-nek visszaadott AllocationResponse objektumot mutatja a fenti példaregisztrációhoz.

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

Eszköz hasznos adatainak használata egyéni foglalásban

Az eszközök olyan egyéni hasznos adatokat küldhetnek, amelyeket a DPS továbbít az egyéni foglalási webhooknak, amelyek aztán felhasználhatják ezeket az adatokat a logikájában. A webhook többféleképpen is felhasználhatja ezeket az adatokat, például annak meghatározására, hogy melyik IoT Hubhoz rendelje hozzá az eszközt, vagy hogy olyan külső adatbázisban keressen információkat, amelyek felhasználhatók a kezdeti ikerpéldány tulajdonságainak beállítására. Ezzel szemben a webhook vissza tudja adni az adatokat az eszköznek a DPS használatával, amely az eszköz ügyféloldali logikájában használható.

Előfordulhat például, hogy az eszközmodell alapján szeretne eszközöket lefoglalni. Ebben az esetben úgy konfigurálhatja az eszközt, hogy a DPS-ben való regisztráláskor a kérelem hasznos adataiban jelentse a modelladatait. A DPS átadja ezt a hasznos adatot az egyéni foglalási webhooknak, amely meghatározza, hogy az eszköz melyik IoT Hubra lesz kiépítve az eszközmodell adatai alapján. Szükség esetén a webhook JSON-objektumként vissza tudja adni az adatokat a DPS-nek a webhook válaszában, a DPS pedig ezeket az adatokat a regisztrációs válaszban adja vissza az eszköznek.

Az eszköz adatokat küld a DPS-nek

Egy eszköz meghívja a regisztrációs API-t a DPS-ben való regisztrációhoz. A kérés bővíthető az opcionális hasznos adat tulajdonsággal. Ez a tulajdonság bármilyen érvényes JSON-objektumot tartalmazhat. A pontos tartalom a megoldás követelményeitől függ.

A TPM-lel való igazoláshoz a kérelem törzse a következőhöz hasonlóan néz ki:

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

A DPS adat-hasznos adatokat küld az egyéni foglalási webhooknak

Ha egy eszköz tartalmazza a regisztrációs kérését, a DPS átadja a hasznos adatokat a AllocationRequest.deviceRuntimeContext.payload tulajdonságban, amikor meghívja az egyéni foglalási webhookot.

Az előző szakaszban szereplő TPM-regisztrációs kérelem esetében az eszköz futtatókörnyezete a következőhöz hasonlóan fog kinézni:

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

Ha nem ez az eszköz kezdeti regisztrációja, akkor a futtatókörnyezet tartalmazza a currentIoTHubHostname nevet és a currentDeviceId tulajdonságokat is.

Az egyéni foglalási webhook adatokat ad vissza a DPS-nek

Az egyéni foglalási szabályzat webhook a webhook válaszában a AllocationResponse.payload tulajdonság használatával vissza tudja adni az eszköznek szánt adatokat a DPS-nek egy JSON-objektumban.

Az alábbi JSON egy hasznos adatokat tartalmazó webhook-választ jelenít meg:

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

A DPS adat hasznos adatokat küld az eszköznek

Ha a DPS hasznos adatokat kap a webhook válaszában, az adatokat visszaküldi az eszköznek a RegistrationOperationStatus.registrationState.payload tulajdonságban a válaszban egy sikeres regisztráció során. A registrationState tulajdonság típusa DeviceRegistrationResult.

Az alábbi JSON sikeres regisztrációs választ jelenít meg egy olyan TPM-eszközhöz, amely tartalmazza a hasznos adat tulajdonságot :

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

Megvalósítás részletei

Az egyéni foglalási webhook olyan eszközökhöz hívható meg, amelyek korábban még nem voltak regisztrálva a DPS-ben (kezdeti hozzárendelés), vagy olyan eszköz esetében, amelyet korábban a DPS-n keresztül regisztráltak (újraépítés). A DPS a következő újraépítési szabályzatokat támogatja: adatok újrabontása és migrálása, újrabontás és visszaállítás a kezdeti konfigurációra, és a Never reprovision. Ezek a szabályzatok akkor lesznek alkalmazva, ha egy korábban kiépített eszköz egy új IoT Hubhoz van rendelve. További részletekért lásd : Újraépítés.

Az alábbi pontok ismertetik azokat a követelményeket, amelyeket az egyéni foglalási webhooknak figyelembe kell vennie, és amelyekről tisztában kell lennie a webhook tervezésekor:

• Az eszközt a AllocationRequest.linkedHubs tulajdonság egyik IoT Hubhoz kell hozzárendelni. Ez a tulajdonság tartalmazza az IoT Hubok gazdagépnév szerinti listáját, amelyhez az eszköz hozzárendelhető. Ez általában a regisztrációs bejegyzéshez kiválasztott IoT Hubokból áll. Ha nincs kiválasztva IoT Hub a regisztrációs bejegyzésben, az tartalmazza a DPS-példányhoz társított összes IoT Hubot. Végül, ha az eszköz újraépítésre kerül, és a Never reprovision szabályzat be van állítva a regisztrációs bejegyzésben, csak azt az IoT Hubot fogja tartalmazni, amelyhez az eszköz jelenleg hozzá van rendelve.

• A kezdeti hozzárendeléskor, ha a webhook visszaadja az initialTwin tulajdonságot, a DPS ennek megfelelően állítja be az eszköz kezdeti ikerpéldányát a hozzárendelt IoT Hubon. Ha a initialTwin tulajdonság hiányzik vagy null, a DPS az eszköz kezdeti ikerpéldányát a regisztrációs bejegyzésben megadott kezdeti ikerbeállításra állítja.

• Az újraépítéskor a DPS a regisztrációs bejegyzésben beállított újraépítési szabályzatot követi. A DPS csak akkor használja az initialTwin tulajdonságot a válaszban, ha az aktuális IoT Hub módosul, és a regisztrációs bejegyzésen beállított újraépítési szabályzat újraépítésre kerül, és visszaállítja a kezdeti konfigurációt. Ebben az esetben a DPS pontosan úgy állítja be az eszköz kezdeti ikerpéldányát az új IoT Hubon, mint az előző listajel kezdeti hozzárendelése során. Minden más esetben a DPS figyelmen kívül hagyja az initialTwin tulajdonságot.

• Ha a hasznos adat tulajdonság be van állítva a válaszban, a DPS mindig visszaadja azt az eszköznek, függetlenül attól, hogy a kérés kezdeti hozzárendelésre vagy újraépítésre van-e szükség.

• Ha egy eszközt korábban kiépítettek egy IoT Hubon, a AllocationRequest.deviceRuntimeContext egy currentIotHubHostName tulajdonságot fog tartalmazni, amely annak az IoT Hubnak a gazdagépneve lesz, amelyhez az eszköz jelenleg hozzá van rendelve.

• Az újraépítési szabályzatok közül jelenleg melyik van beállítva a regisztrációs bejegyzésben, ha megvizsgálja a kérelemben szereplő AllocationRequest.individualEnrollment vagy a AllocationRequest.enrollmentGroup tulajdonság újraprovisionPolicy tulajdonságát. az alábbi JSON az újraépítési és migrálási adatszabályzat beállításait mutatja be:

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

SDK-támogatás

A DPS eszközoldali SDK-k API-kat biztosítanak c, C#, Java és Node.js az eszközök DPS-ben való regisztrálásához. Az IoT Hub SDK-k és a DPS SDK-k egyaránt olyan osztályokat biztosítanak, amelyek az eszköz- és szolgáltatásösszetevőket, például az ikereszközöket és a regisztrációs bejegyzéseket jelölik, amelyek hasznosak lehetnek az egyéni foglalási webhookok fejlesztésekor. Az IoT Hubhoz és az IoT Hub Eszközkiépítési szolgáltatáshoz elérhető Azure IoT SDK-kkal kapcsolatos további információkért lásd az Azure IoT Hub SDK-jait és az Azure DPS SDK-kat.

Következő lépések

• Az egyéni foglalási szabályzatot használó végpontok közötti példáért lásd: Egyéni foglalási szabályzatok használata

• Az Azure Functionsről további információt az Azure Functions dokumentációjában talál.