Vysvětlení vlastních zásad přidělování pomocí služby Azure IoT Hub Device Provisioning
Vlastní zásady přidělování poskytují větší kontrolu nad tím, jak se zařízení přiřazují k vašim ioT Hubům. Pomocí vlastních zásad přidělování můžete definovat vlastní zásady přidělování, pokud předdefinované zásady poskytované službou Device Provisioning Service (DPS) nesplňují požadavky vašeho scénáře.
Možná například chcete prozkoumat certifikát, který zařízení používá při zřizování, a přiřadit ho k centru IoT na základě vlastnosti certifikátu. Nebo možná máte informace uložené v databázi pro vaše zařízení a potřebujete zadat dotaz na databázi, abyste zjistili, ke které službě IoT Hub se má zařízení přiřadit nebo jak by se mělo nastavit počáteční dvojče zařízení.
Implementujete vlastní zásady přidělování ve webhooku hostované ve službě Azure Functions. Pak můžete webhook nakonfigurovat v jedné nebo více jednotlivých registracích a skupinách registrací. Když se zařízení zaregistruje prostřednictvím nakonfigurované položky registrace, služba DPS zavolá webhook, který vrátí centrum IoT, aby zařízení zaregistrovalo, a volitelně i počáteční nastavení dvojčete zařízení a všechny informace, které se mají vrátit přímo do zařízení.
Přehled
Následující kroky popisují, jak fungují vlastní zásady přidělování:
Vývojář vlastního přidělení vyvíjí webhook, který implementuje zamýšlenou zásadu přidělování a nasadí ji jako funkci triggeru HTTP do Azure Functions. Webhook přebírá informace o položce registrace DPS a zařízení a vrátí centrum IoT, do kterého se má zařízení zaregistrovat, a volitelně informace o počátečním stavu zařízení.
Operátor IoT nakonfiguruje jednu nebo více jednotlivých registrací nebo skupin registrací pro vlastní přidělení a poskytne podrobnosti volání pro vlastní webhook přidělování ve službě Azure Functions.
Když se zařízení zaregistruje prostřednictvím položky registrace nakonfigurované pro webhook vlastního přidělení, služba DPS odešle požadavek POST do webhooku s textem požadavku nastaveným na objekt požadavku AllocationRequest . Objekt AllocationRequest obsahuje informace o zařízení, které se pokouší zřídit, a o jednotlivé registraci nebo skupině registrací, které zřizuje. Informace o zařízení můžou v žádosti o registraci obsahovat volitelnou vlastní datovou část odeslanou ze zařízení. Další informace najdete v tématu Vlastní žádost o zásady přidělování.
Funkce Azure Functions provede a vrátí objekt AllocationResponse při úspěchu. Objekt AllocationResponse obsahuje Centrum IoT, pro které by se zařízení mělo zřídit, počáteční stav dvojčete a volitelnou vlastní datovou část, která se má vrátit do zařízení. Další informace najdete v tématu Odpověď na vlastní zásady přidělování.
Služba DPS přiřadí zařízení do centra IoT, které je uvedené v odpovědi, a pokud se vrátí počáteční dvojče, nastaví počáteční dvojče pro zařízení odpovídajícím způsobem. Pokud webhook vrátí vlastní datovou část, předá se do zařízení spolu s přiřazeným centrem IoT a podrobnostmi o ověřování v odpovědi na registraci z DPS.
Zařízení se připojí k přiřazené službě IoT Hub a stáhne počáteční stav dvojčete. Pokud se vlastní datová část vrátí v odpovědi registrace, zařízení ji použije podle vlastní logiky na straně klienta.
Následující části obsahují podrobnější informace o vlastní žádosti o přidělení a odpovědi, vlastních datových částech a implementaci zásad. Úplný kompletní příklad vlastních zásad přidělování najdete v tématu Použití vlastních zásad přidělování.
Žádost o vlastní zásady přidělování
Služba DPS odešle požadavek POST do vašeho webhooku na následujícím koncovém bodu: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}
Text požadavku je objekt AllocationRequest :
| Název vlastnosti | Popis |
|---|---|
| individualEnrollment | Jednotlivý záznam registrace, který obsahuje vlastnosti přidružené k jednotlivé registraci, ze které pochází žádost o přidělení. Prezentovat, pokud se zařízení registruje prostřednictvím jednotlivé registrace. |
| enrollmentGroup | Záznam skupiny registrací, který obsahuje vlastnosti přidružené ke skupině registrací, ze které pochází žádost o přidělení. Zobrazí se, pokud se zařízení registruje prostřednictvím skupiny registrací. |
| deviceRuntimeContext | Objekt, který obsahuje vlastnosti přidružené k zařízení, které se registruje. Vždy prezentovat. |
| propojenéhuby | Pole obsahující názvy hostitelů center IoT, které jsou propojené s položkou registrace, ze které pochází požadavek na přidělení. Zařízení může být přiřazeno k některému z těchto center IoT. Vždy prezentovat. |
Objekt DeviceRuntimeContext má následující vlastnosti:
| Vlastnost | Type | Popis |
|---|---|---|
| registrationId | string | ID registrace poskytnuté zařízením za běhu. Vždy prezentovat. |
| currentIotHubHostName | string | Název hostitele ioT Hubu, ke kterému bylo zařízení dříve přiřazeno (pokud existuje). Není k dispozici, pokud se jedná o počáteční přiřazení. Tuto vlastnost můžete použít k určení, jestli se jedná o počáteční přiřazení zařízení nebo jestli bylo zařízení dříve přiřazeno. |
| currentDeviceId | string | ID zařízení z předchozího přiřazení zařízení (pokud existuje). Není k dispozici, pokud se jedná o počáteční přiřazení. |
| x509 | X509DeviceAttestation | Pro ověření identity X.509 obsahuje podrobnosti o certifikátu. |
| symetrický klíč | SymmetricKeyAttestation | Pro ověření symetrického klíče obsahuje podrobnosti o primárním a sekundárním klíči. |
| tpm | TpmAttestation | Pro ověření identity TPM obsahuje podrobnosti ověřovacího klíče a kořenového klíče úložiště. |
| payload | objekt | Obsahuje vlastnosti zadané zařízením ve vlastnosti datové části během registrace. Zobrazí se, pokud zařízení odešle vlastní datovou část v žádosti o registraci DPS. |
Následující JSON ukazuje objekt AllocationRequest odeslaný službou DPS pro zařízení, které se registruje prostřednictvím skupiny registrací založené na symetrických klíčích.
{
"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"
]
}
Vzhledem k tomu, že se jedná o počáteční registraci zařízení, vlastnost deviceRuntimeContext obsahuje pouze ID registrace a podrobnosti ověřování zařízení. Následující KÓD JSON ukazuje deviceRuntimeContext pro následné volání pro registraci stejného zařízení. Všimněte si, že aktuální název hostitele a ID zařízení služby IoT Hub jsou součástí požadavku.
{
"deviceRuntimeContext":{
"registrationId":"breakroom499-contoso-tstrsd-007",
"currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
"currentDeviceId":"breakroom499-contoso-tstrsd-007",
"symmetricKey":{
}
},
}
Odpověď na vlastní zásady přidělování
Úspěšný požadavek vrátí objekt AllocationResponse .
| Vlastnost | Popis |
|---|---|
| initialTwin | Nepovinné. Objekt obsahující požadované vlastnosti a značky, které se mají nastavit v počátečním dvojčeti v přiřazené službě IoT Hub. Služba DPS používá vlastnost initialTwin k nastavení počátečního dvojčete v přiřazené službě IoT Hub při počátečním přiřazení nebo při opětovném zřízení, pokud je zásada migrace položky registrace nastavená na opětovné zřízení a resetování na počáteční konfiguraci. V obou těchto případech, pokud initialTwin není vrácen nebo je nastaven na hodnotu null, DPS nastaví dvojče v přiřazené službě IoT Hub na počáteční nastavení dvojčete v položce registrace. DPS ignoruje initialTwin pro všechna ostatní nastavení opětovného zřízení v položce registrace. Další informace najdete v tématu Podrobnosti o implementaci. |
| iotHubHostName | Povinný: Název hostitele centra IoT, ke kterému se má zařízení přiřadit. Musí se jednat o jedno z ioT hubů předávaných ve vlastnosti linkedHubs v požadavku. |
| payload | Nepovinné. Objekt, který obsahuje data, která se mají předat zpět do zařízení v odpovědi registrace. Přesná data budou záviset na implicitním kontraktu definovaném vývojářem mezi zařízením a vlastní funkcí přidělování. |
Následující kód JSON ukazuje objekt AllocationResponse vrácený vlastní funkcí přidělení do DPS pro výše uvedenou ukázkovou registraci.
{
"iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
"initialTwin":{
"properties":{
"desired":{
"state":"ready",
"darknessSetting":"medium"
}
},
"tags":{
"deviceType":"toaster"
}
}
}
Použití datových částí zařízení ve vlastním přidělení
Zařízení můžou odesílat vlastní datovou část předanou službou DPS do vašeho webhooku vlastního přidělení, který pak může tato data použít v logice. Webhook může tato data používat mnoha způsoby, například určit, ke kterému centru IoT se má zařízení přiřadit, nebo vyhledat informace v externí databázi, která by mohla být použita k nastavení vlastností počátečního dvojčete. Webhook může naopak vracet data zpět do zařízení prostřednictvím DPS, která se můžou použít v logice na straně klienta zařízení.
Můžete například chtít přidělit zařízení na základě modelu zařízení. V takovém případě můžete zařízení nakonfigurovat tak, aby hlásilo informace o modelu v datové části požadavku, když se zaregistruje v DPS. DPS tuto datovou část předá do webhooku vlastního přidělení, který určí, pro které centrum IoT bude zařízení zřízeno, na základě informací o modelu zařízení. V případě potřeby může webhook vracet data zpět do DPS jako objekt JSON v odpovědi webhooku a služba DPS tato data vrátí do vašeho zařízení v odpovědi registrace.
Zařízení odesílá datovou část do DPS.
Zařízení volá rozhraní API pro registraci , aby se zaregistrovalo ve službě DPS. Požadavek lze rozšířit o volitelnou vlastnost datové části . Tato vlastnost může obsahovat libovolný platný objekt JSON. Přesný obsah bude záviset na požadavcích vašeho řešení.
Pro ověření identity pomocí čipu TPM vypadá text požadavku takto:
{
"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 odesílá datovou část do webhooku vlastního přidělení.
Pokud zařízení obsahuje datovou část, kterou má žádost o registraci, služba DPS předá datovou část ve vlastnosti AllocationRequest.deviceRuntimeContext.payload , když volá webhook vlastního přidělení.
V případě žádosti o registraci TPM v předchozí části bude kontext modulu runtime zařízení vypadat takto:
{
"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}, .. }
}
Pokud se nejedná o počáteční registraci zařízení, kontext modulu runtime bude obsahovat také currentIoTHubHostname a currentDeviceId vlastnosti.
Webhook vlastního přidělení vrací data do DPS.
Webhook zásad vlastního přidělení může v objektu JSON vracet data určená pro zařízení do DPS pomocí vlastnosti AllocationResponse.payload v odpovědi webhooku.
Následující json ukazuje odpověď webhooku, která obsahuje datovou část:
{
"iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
"initialTwin":{
"properties":{
"desired":{
"state":"ready",
"darknessSetting":"medium"
}
},
"tags":{
"deviceType":"toaster"
}
},
"payload": { "property1": "value1" }
}
DPS odesílá datovou část do zařízení.
Pokud SLUŽBA DPS obdrží datovou část v odpovědi webhooku, předá tato data zpět do zařízení ve vlastnosti RegistrationOperationStatus.registrationState.payload v odpovědi na úspěšnou registraci. Vlastnost registrationState je typu DeviceRegistrationResult.
Následující JSON ukazuje úspěšnou odpověď na registraci pro zařízení TPM, které obsahuje vlastnost datové části :
{
"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"}
}
}
Podrobnosti implementace
Webhook vlastního přidělení lze volat pro zařízení, které nebylo dříve registrováno prostřednictvím DPS (počáteční přiřazení) nebo pro zařízení, které bylo dříve registrováno prostřednictvím DPS (opětovné zřízení). SLUŽBA DPS podporuje následující zásady opětovného zřízení: Opětovné zřízení a migraci dat, opětovné zřízení a obnovení do počáteční konfigurace a nikdy znovu zřízení. Tyto zásady se použijí při každém přiřazení dříve zřízeného zařízení k novému centru IoT. Další podrobnosti najdete v tématu Opětovné zřízení.
Následující body popisují požadavky, které webhook vlastního přidělení musí sledovat a chování, o které byste měli vědět při návrhu webhooku:
Zařízení by mělo být přiřazeno k jednomu z center IoT ve vlastnosti AllocationRequest.linkedHubs . Tato vlastnost obsahuje seznam ioT Hubů podle názvu hostitele, ke kterému je možné zařízení přiřadit. Obvykle se skládají z ioT Hubů vybraných pro položku registrace. Pokud v položce registrace nejsou vybrány žádné služby IoT Hub, budou obsahovat všechna centra IoT propojená s instancí DPS. A konečně, pokud se zařízení znovu zřídí a zásada nikdy znovu zřízení není nastavená u položky registrace, bude obsahovat pouze centrum IoT, ke kterému je zařízení aktuálně přiřazené.
Pokud webhook vrátí vlastnost initialTwin při počátečním přiřazení, služba DPS nastaví počáteční dvojče pro zařízení v přiřazené službě IoT Hub odpovídajícím způsobem. Pokud je vlastnost initialTwin vynechána nebo má hodnotu null, DPS nastaví počáteční dvojče zařízení na počáteční nastavení dvojčete zadané v položce registrace.
Při opětovném zřízení se SLUŽBA DPS řídí zásadami opětovného zřízení nastavené v položce registrace. DPS v odpovědi používá vlastnost initialTwin pouze v případě, že se změní aktuální centrum IoT a zásada opětovného zřízení nastavená u položky registrace je Opětovné zřízení a resetování počáteční konfigurace. V tomto případě DPS nastaví počáteční dvojče pro zařízení v novém centru IoT přesně tak, jak by to bylo při počátečním přiřazení v předchozí odrážkě. Ve všech ostatních případech DPS ignoruje vlastnost initialTwin .
Pokud je vlastnost datové části nastavena v odpovědi, SLUŽBA DPS ji vždy vrátí do zařízení bez ohledu na to, zda je požadavek na počáteční přiřazení nebo opětovné zřízení.
Pokud se zařízení dříve zřídilo pro centrum IoT, nástroj AllocationRequest.deviceRuntimeContext bude obsahovat vlastnost currentIotHubHostName , která se nastaví na název hostitele centra IoT, ve kterém je zařízení aktuálně přiřazené.
Můžete určit, které zásady opětovného zřízení jsou aktuálně nastaveny pro položku registrace, prozkoumáním vlastnosti reprovisionPolicy AllocationRequest.individualEnrollment nebo AllocationRequest.enrollmentGroup v požadavku. Následující JSON ukazuje nastavení pro zásady opětovného zřízení a migrace dat :
"reprovisionPolicy":{ "updateHubAssignment":true, "migrateDeviceData":true }
Podpora SDK
Sady SDK pro zařízení DPS poskytují rozhraní API v jazyce C, C#, Javě a Node.js, které vám pomůžou registrovat zařízení v DPS. Sady SDK služby IoT Hub i sady DPS SDK poskytují třídy, které představují artefakty zařízení a služeb, jako jsou dvojčata zařízení a položky registrace, které můžou být užitečné při vývoji vlastních webhooků přidělování. Další informace o sadách SDK Azure IoT, které jsou k dispozici pro službu IoT Hub a IoT Hub Device Provisioning, najdete v tématu Sady SDK služby Azure IoT Hub a sady SDK Azure DPS.
Další kroky
Kompletní příklad použití vlastních zásad přidělování najdete v tématu Použití vlastních zásad přidělování.
Další informace o službě Azure Functions najdete v dokumentaci ke službě Azure Functions.
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro