Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
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ý určí IoT Hub, do něhož se zařízení zaregistruje, a volitelně i počáteční nastavení dvojčete pro zařízení a veškeré informace, které se vrátí přímo do zařízení.
Přehled
Následující kroky popisují, jak fungují vlastní zásady přidělování:
Vývojář zaměřený na vlastní řešení přidělování vyvíjí webhook, který implementuje zamýšlenou politiku přidělování, a nasadí jej jako HTTP trigger funkci 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ší poskytnout, a o jednotlivé registraci nebo skupině registrací, kterou poskytuje. Informace o zařízení mohou v žádosti o registraci obsahovat volitelnou vlastní datovou část odeslanou ze zařízení. Další informace najdete v tématu Žádost o vlastní zásady přidělování.
Funkce Azure provede a vrátí objekt AllocationResponse v případě úspěchu. Objekt AllocationResponse obsahuje IoT hub, ke kterému by mělo být zařízení připojeno, počáteční stav dvojčete a volitelný vlastní uživatelský datový paket, který se má vrátit do zařízení. Další informace najdete v tématu Odpověď na zásady vlastního 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. Další informace o kompletním příkladu vlastních zásad přidělování najdete v tématu Kurz: Použití vlastních zásad přidělování se službou Device Provisioning Service (DPS).
Správa klíčů funkcí
Vlastní zásady přidělování používají klíče funkcí k ověřování volání ve službě Azure Functions, kde je úroveň autorizace nastavená na Function. Chování správy klíčů se liší podle toho, jestli konfigurujete vlastní zásady přidělování prostřednictvím webu Azure Portal nebo programově.
Funkční klíče na portálu
Když vytvoříte registraci na webu Azure Portal a zadáte vlastní zásady přidělování, portál automaticky zpracuje načítání a vkládání funkčního klíče.
Po výběru funkce pro vlastní zásady přidělování portál načte klíč funkce. Tento krok není viditelný pro uživatele prostřednictvím rozhraní portálu. Pak se klíč funkce uloží jako součást šifrované adresy URL webhooku používané službou DPS k volání funkce. Klíč se na portálu nezobrazuje.
Spuštěním příkazu GET můžete ověřit, že je klíč vložený do adresy URL webhooku a načíst podrobnosti o registraci. V konfiguraci registrace je klíč funkce součástí pole webhookUrl .
Funkční klávesy s rozhraními API
Při programovém vytváření registrace pomocí rozhraní DPS API musíte klíč zadat ručně během vytváření registrace. Pokud klíč není zadaný, autentizace volání Azure Functions selže.
Před vytvořením jednotlivé nebo skupinové registrace načtěte klíč funkce z vaší funkce. Další informace najdete v tématu Získání přístupových klíčů funkce. Potom zahrněte funkční klíč do pole webhookUrl v CustomAllocationDefinition.
Další informace najdete v tématu Autorizace přístupového klíče.
Žá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 |
|---|---|
| individuální zápis | Jednotlivý záznam registrace, který obsahuje vlastnosti přidružené k jednotlivé registraci, ze které pochází žádost o přidělení. Je přítomen, pokud se zařízení registruje prostřednictvím individuální registrace. |
| zápisová skupina | Záznam skupiny registrací, který obsahuje vlastnosti přidružené ke skupině registrací, ze které pochází žádost o přidělení. Je přítomno, pokud se zařízení registruje prostřednictvím skupiny pro registraci. |
| Kontext zařízení během běhu | Objekt, který obsahuje vlastnosti přidružené k zařízení, které se registruje. Vždy přítomný. |
| propojené uzly | 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řazené k některému z těchto center IoT. Vždy přítomný. |
Objekt DeviceRuntimeContext má následující vlastnosti:
| Vlastnost | Typ | Popis |
|---|---|---|
| identifikační číslo registrace | řetězec | ID registrace poskytnuté zařízením za běhu. Vždy přítomný. |
| currentIotHubHostName | řetězec | 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 | řetězec | 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í. |
| Rozšíření x509 | X509DeviceAttestation | Pro atestaci X.509 obsahuje podrobnosti o certifikátu. |
| symetrický klíč | Ověření symetrického klíče | Pro ověření symetrického klíče obsahuje podrobnosti o primárním a sekundárním klíči. |
| čip tpm | TpmAtestace | Pro ověření identity TPM obsahuje podrobnosti ověřovacího klíče a kořenového klíče úložiště. |
| datová část | 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 centra IoT a ID zařízení 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í politiku přidělování
Úspěšný požadavek vrátí objekt AllocationResponse .
| Vlastnost | Popis |
|---|---|
| počáteční dvojče | 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. |
| datová část | Nepovinné. Objekt, který obsahuje data, která se mají předat zpět do zařízení v odpovědi registrace. Přesná data závisí 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 registraci v předchozím příkladu.
{
"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í mohou odesílat uživatelsky definovanou datovou zátěž, která je službou DPS předána vašemu webhooku pro vlastní přidělení, a ten pak může tato data použít ve své logice. Webhook může tato data používat mnoha způsoby, třeba 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žívat 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 předá tento payload do webhooku vlastního přidělení, který určuje, ve kterém centru IoT je zařízení zřizováno, 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 vrátí tato data do vašeho zařízení v odpovědi registrace.
Zařízení odesílá datovou část do DPS.
Zařízení volá API pro registraci do DPS, aby se zaregistrovalo ve službě DPS. Požadavek lze rozšířit o volitelnou datovou část. Tato vlastnost může obsahovat libovolný platný objekt JSON. Přesný obsah závisí na požadavcích vašeho řešení.
Pro ověření identity pomocí čipu TPM vypadá text požadavku jako v následujícím příkladu:
{
"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 ve své žádosti o registraci, služba DPS předá datovou část ve vlastnosti AllocationRequest.deviceRuntimeContext.payload při vyvolání webhooku pro vlastní přidělení.
V případě žádosti o registraci TPM v předchozí části vypadá kontext modulu runtime zařízení jako v následujícím příkladu:
{
"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 zahrnuje 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
Vlastní přidělovací webhook lze volat pro zařízení, které nebylo dříve zaregistrováno prostřednictvím DPS (počáteční přiřazení), nebo pro zařízení, které bylo dříve zaregistrová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ší informace najdete v tématu Koncepty opětovného zřízení zařízení služby IoT Hub.
Následující body popisují požadavky, které webhook pro vlastní rozdělení prostředků musí dodržovat, a chování, o kterém 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ána žádná centra IoT, tato položka registrace obsahuje všechna centra IoT propojená s instancí DPS. Nakonec, pokud se zařízení znovu nakonfiguruje a na položce registrace je nastavena zásada nikdy znovu nekonfigurovat, obsahuje 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í, DPS nastaví počáteční dvojče pro zařízení v přiřazeném IoT Hubu 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 DPS řídí zásadami opětovného zřízení nastavenými v záznamu 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 payload nastavena v odpovědi, DPS ji vždy odesílá zpět do zařízení, bez ohledu na to, zda je žádost o počáteční přiřazení nebo opětovné zřízení.
Pokud bylo zařízení dříve zřízeno pro centrum IoT, AllocationRequest.deviceRuntimeContext obsahuje vlastnost currentIotHubHostName , která je nastavena na název hostitele centra IoT, kde je zařízení aktuálně přiřazeno.
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 duplikáty zařízení a položky registrace, které mohou být užitečné při vývoji vlastních webhooků pro alokaci. 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 MICROSOFT SDK pro službu IoT Hub Device Provisioning.
Další kroky
Kompletní příklad použití vlastních zásad přidělování najdete v tématu Kurz: Použití vlastních zásad přidělování se službou Device Provisioning Service (DPS)
Další informace o službě Azure Functions najdete v dokumentaci ke službě Azure Functions.