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