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. Ez visszatéríti az IoT Hub információit, amelyhez az eszközt regisztrálni kell, valamint szükség esetén az eszköz kezdeti ikerbeállításait és minden olyan információt, amelyet közvetlenül az eszköznek kell visszaadni.

Á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 próbáló eszközről, valamint az egyéni regisztráció vagy regisztrációs csoport révén történő kiépítésről. Az eszközinformációk tartalmazhatják az eszköz által a regisztrációs kérelemben küldött opcionális egyéni hasznos adatot. További információ: Egyéni foglalási szabályzat kérése.

  4. Az Azure-függvény siker esetén visszaad egy AllocationResponse objektumot. 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 kiosztási irányelv 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 egy webhook egy egyéni adatcsomagot ad vissza, az a készüléknek lesz továbbítva a DPS regisztrációs válaszában található hozzárendelt IoT Hubbal é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 allokációs kérelmet és választ, az egyéni adatterhelést és a szabályzat végrehajtását. Az egyéni foglalási szabályzatok teljes körű példájáról további információt a következő oktatóanyagban talál: Egyéni foglalási szabályzatok használata a Device Provisioning Service (DPS) szolgáltatással.

Függvénykulcsok kezelése

Az egyéni foglalási szabályzatok függvénykulcsokkal hitelesítik az Azure Functionsbe irányuló hívásokat, ahol az engedélyezési szint be van állítva Function. A kulcskezelés viselkedése attól függ, hogy az egyéni foglalási szabályzatot az Azure Portalon vagy programozott módon konfigurálja.

Függvénykulcsok a portálon

Amikor létrehoz egy regisztrációt az Azure Portalon, és egyéni foglalási szabályzatot ad meg, a portál automatikusan kezeli a függvénykulcs lekérését és beágyazását.

Az egyéni kiosztási házirend függvényének kiválasztása után a portál lekéri a függvény kulcsot. Ez a lépés nem látható a felhasználók számára a portál felületén keresztül. Ezután a függvénykulcs a DPS által a függvény meghívásához használt titkosított webhook URL-cím részeként lesz tárolva. A kulcs nem jelenik meg a portálon.

A regisztráció részleteinek lekéréséhez egy GET parancs futtatásával ellenőrizheti, hogy a kulcs beágyazva van-e a webhook URL-címébe. A regisztrációs konfigurációban a függvénykulcs szerepel a webhookUrl mezőben.

Függvénykulcsok API-kkal

Amikor programozott módon hoz létre regisztrációt a DPS API használatával, manuálisan kell megadnia a kulcsot a regisztráció létrehozásakor. Ha a kulcs nincs megadva, az Azure Functions-hívás sikertelen hitelesítést fog végrehajtani.

Az egyéni vagy csoportos regisztráció létrehozása előtt szerezze be a függvénykulcsot a függvényből. További információ: A függvény hozzáférési kulcsainak lekérése. Ezután adja meg a függvénykulcsot a CustomAllocationDefinition webhookUrl mezőjében.

További információ: Access-kulcs engedélyezése.

Egyéni elosztá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 megnevezése Leírás
egyéni beiratkozás 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.
beiratkozási csoport 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.
eszköz-futási környezet Olyan objektum, amely a regisztráló eszközhöz társított tulajdonságokat tartalmazza. Mindig jelen van.
linkedHubs Egy tömb, amely tartalmazza azon IoT-hubok állomásneveit, amelyek kapcsolatban állnak azzal a regisztrációs bejegyzéssel, ahonnan a kiosztási kérelem származik. Előfordulhat, hogy az eszköz ezen IoT Hubok bármelyikéhez hozzárendelhető. Mindig jelen van.

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

Tulajdonság Típus Leírás
regisztrációs azonosító karakterlánc Az eszköz által futásidőben megadott regisztrációs azonosító. Mindig jelen van.
currentIotHubHostName karakterlánc 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.
jelenlegiEszközAzonosító karakterlánc 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 X509-eszköz-hitelesítés Az X.509-igazolás esetében a tanúsítvány részletei szerepelnek.
szimmetrikus kulcs SzimmetrikusKulcsBizonyítás Szimmetrikus kulcsigazolás esetén az elsődleges és a másodlagos kulcs adatait tartalmazza.
Tpm TPM-igazolás A TPM-igazoláshoz tartoznak a támogatókulcs és a tároló gyökérkulcs részletei.
hasznos adat objektum A regisztráció során az eszköz által megadott tulajdonságok találhatók a hasznos adat tulajdonságában. Akkor jelenik meg, ha az eszköz egyedi hasznos terhet 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 IoT Hub jelenlegi állomásnevét és eszközazonosítóját.

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

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

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

Tulajdonság Leírás
kezdetiIkertestvér Opcionális. Az az objektum, amely a hozzárendelt IoT Hub kezdeti ikerpéldányában beállítandó kívánt tulajdonságokat és címkéket tartalmazza. DPS az initialTwin attribútum használatával állítja be a kezdeti ikerpéldányt a hozzárendelt IoT Hubon a kezdeti hozzárendelés során vagy amikor újraprovíziózás történik, és visszaállítja az eredeti konfigurációt, ha a bejegyzés áttelepítési szabályzata Reprovision and reset to initial config van állítva. Mindkét esetben, ha az initialTwin nincs visszaadva, vagy null értékre van állítva, a DPS a hozzárendelt IoT Hubon az ikerpéldányt a bejegyzés kezdeti ikerbeállításaira állítja. A DPS figyelmen kívül hagyja az initialTwin beállításokat a regisztrációs bejegyzésben szereplő összes többi újraépítési beállítás esetén. További információ: Implementáció részletei.
iotHubHostName Szükséges. Az az IoT hub állomásneve, amelyhez az eszközt hozzárendeljük. Ennek a kérelem linkedHubs tulajdonságában átadott IoT Hubok egyikének kell lennie.
hasznos adat 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 be az előző példában való regisztrációhoz.

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

Eszközadatok használata egyéni allokáció során

Az eszközök egyéni payloadot küldhetnek, amelyet a DPS továbbít az egyéni kiosztási webhooknak, amely aztán felhasználhatja ezeket az adatokat a logikájában. A webhook számos módon haszná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-ben, amelyet 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 allokációs webhooknak, amely meghatározza, hogy az eszköz melyik IoT Hubhoz van rendelve 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 adja vissza az eszköznek a regisztrációs válaszban.

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

Egy eszköz meghívja a DPS regisztrációs API-t , hogy regisztráljon a DPS-ben. 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-sel való igazoláshoz a kérelem törzse a következő példához 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 adatcsomagot küld az egyéni kiosztási webhooknak

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

Az előző szakaszban szereplő TPM-regisztrációs kérelem esetében az eszköz futtatókörnyezete a következő példához 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}, .. } 
}

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

Az egyéni kiosztási webhook visszaküld adatokat a DPS-nek

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

Az alábbi JSON egy payloadot tartalmazó webhook-választ mutat.

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

A DPS adatcsomagot küld az eszköznek.

Ha a DPS a webhook válaszában hasznos adatokat kap, az adatokat sikeres regisztráció esetén a válaszban a RegistrationOperationStatus.registrationState.payload tulajdonságban küldi vissza az eszköznek. 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, amelyeket korábban nem regisztráltak a DPS-ben (kezdeti hozzárendelés), vagy olyan eszközhöz, amelyet korábban a DPS-ben regisztráltak (újraépítés). A DPS a következő újrabeállítási irányelveket támogatja: újraprovisionálás és adatmigráció, újraprovisionálás és visszaállítás a kezdeti konfigurációra, és soha ne újraprovisionáljon. Ezek a szabályzatok akkor lesznek alkalmazva, ha egy korábban kiépített eszköz egy új IoT Hubhoz van rendelve. További információ: IoT Hub Eszköz újraépítési fogalmak.

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 az összes, a DPS-példányhoz társított IoT-hubot tartalmazza. Végül, ha az eszköz újrakonfigurálás alatt áll, és a Never reprovision szabályzat be van állítva a beiratkozási bejegyzésben, csak azt az IoT hubot tartalmazza, 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.

  • Újratelepítéskor a DPS a regisztrációs bejegyzésben beállított újratelepí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 megváltozik, és a regisztrációs bejegyzésen beállított újraprovisionálási szabályzat "Újraépítés és visszaállítás a kezdeti konfigurációra" van beállítva. Ebben az esetben a DPS pontosan úgy állítja be az eszköz kezdeti iker tulajdonságát az új IoT Hubon, mint az előző felsorolási pont kezdeti hozzárendelése során. Minden más esetben a DPS figyelmen kívül hagyja az initialTwin tulajdonságot.

  • Ha a válaszban be van állítva a payload tulajdonság, a DPS mindig visszajuttatja azt az eszköznek, függetlenül attól, hogy a kérés kezdeti hozzárendelésre vagy újrahozzárendelésre vonatkozik-e.

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

  • Megállapíthatja, hogy az újraépítési szabályzatok közül melyik van jelenleg beállítva a regisztrációs bejegyzéshez, ha megvizsgálja a AllocationRequest.individualEnrollment vagy a AllocationRequest.enrollmentGroup tulajdonság reprovisionPolicy tulajdonságát a kérelemben. az alábbi JSON az újratelepítési és adatmigrálási szabá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 nyelven, hogy segítsenek az eszközök regisztrálásában a DPS-ben. 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 Device Provisioning Service-hez elérhető Azure IoT Hub SDK-król további információt az Azure IoT Hub SDK-kkal és az IoT Hub Device Provisioning Service-hez készült Microsoft SDK-kkal kapcsolatban talál.

Következő lépések

  • Last updated on