Memahami kebijakan alokasi kustom dengan Azure IoT Hub Device Provisioning Service

Artikel
03/18/2023

Kebijakan alokasi kustom memberi Anda kontrol lebih atas bagaimana perangkat ditetapkan ke hub IoT Anda. Dengan menggunakan kebijakan alokasi kustom, Anda dapat menentukan kebijakan alokasi Anda sendiri saat kebijakan bawaan yang disediakan oleh Device Provisioning Service (DPS) tidak memenuhi persyaratan skenario Anda.

Misalnya, mungkin Anda ingin memeriksa sertifikat yang digunakan perangkat selama penyediaan dan menetapkan perangkat ke hub IoT berdasarkan properti sertifikat. Atau, mungkin Anda memiliki informasi yang disimpan dalam database untuk perangkat Anda dan perlu mengkueri database untuk menentukan hub IoT mana yang harus ditetapkan perangkat atau bagaimana kembar awal perangkat harus diatur.

Anda menerapkan kebijakan alokasi kustom di webhook yang dihosting di Azure Functions. Anda kemudian dapat mengonfigurasi webhook dalam satu atau beberapa pendaftaran individu dan grup pendaftaran. Ketika perangkat mendaftar melalui entri pendaftaran yang dikonfigurasi, DPS memanggil webhook yang mengembalikan hub IoT untuk mendaftarkan perangkat ke dan, secara opsional, pengaturan kembar awal untuk perangkat dan informasi apa pun yang akan dikembalikan langsung ke perangkat.

Gambaran Umum

Langkah-langkah berikut menjelaskan cara kerja polisi alokasi kustom:

Pengembang alokasi kustom mengembangkan webhook yang menerapkan kebijakan alokasi yang dimaksudkan dan menyebarkannya sebagai fungsi Pemicu HTTP ke Azure Functions. Webhook mengambil informasi tentang entri pendaftaran DPS dan perangkat dan mengembalikan hub IoT tempat perangkat harus didaftarkan ke dan, secara opsional, informasi tentang status awal perangkat.
Operator IoT mengonfigurasi satu atau beberapa pendaftaran individu dan/atau grup pendaftaran untuk alokasi kustom dan memberikan detail panggilan untuk webhook alokasi kustom di Azure Functions.
Ketika perangkat mendaftar melalui entri pendaftaran yang dikonfigurasi untuk webhook alokasi kustom, DPS mengirim permintaan POST ke webhook dengan isi permintaan yang diatur ke objek permintaan AllocationRequest . Objek AllocationRequest berisi informasi tentang perangkat yang mencoba menyediakan dan pendaftaran individu atau grup pendaftaran yang disediakannya. Informasi perangkat dapat mencakup payload kustom opsional yang dikirim dari perangkat dalam permintaan pendaftarannya. Untuk informasi selengkapnya, lihat Permintaan kebijakan alokasi kustom.
Fungsi Azure menjalankan dan mengembalikan objek AllocationResponse pada keberhasilan. Objek AllocationResponse berisi hub IoT yang harus disediakan perangkat, status kembar awal, dan payload kustom opsional untuk kembali ke perangkat. Untuk informasi selengkapnya, lihat Respons kebijakan alokasi kustom.
DPS menetapkan perangkat ke hub IoT yang ditunjukkan dalam respons, dan, jika kembar awal dikembalikan, mengatur kembar awal untuk perangkat yang sesuai. Jika payload kustom dikembalikan oleh webhook, payload tersebut diteruskan ke perangkat bersama dengan hub IoT dan detail autentikasi yang ditetapkan dalam respons pendaftaran dari DPS.
Perangkat terhubung ke hub IoT yang ditetapkan dan mengunduh status kembar awalnya. Jika payload kustom dikembalikan dalam respons pendaftaran, perangkat menggunakannya sesuai dengan logika sisi kliennya sendiri.

Bagian berikut memberikan detail selengkapnya tentang permintaan dan respons alokasi kustom, payload kustom, dan implementasi kebijakan. Untuk contoh lengkap kebijakan alokasi kustom, lihat Menggunakan kebijakan alokasi kustom.

Permintaan kebijakan alokasi kustom

DPS mengirimkan permintaan POST ke webhook Anda di titik akhir berikut: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Isi permintaan adalah objek AllocationRequest :

Nama properti	Deskripsi
individualEnrollment	Catatan pendaftaran individu yang berisi properti yang terkait dengan pendaftaran individu tempat permintaan alokasi berasal. Ada jika perangkat mendaftar melalui pendaftaran individu.
enrollmentGroup	Rekaman grup pendaftaran yang berisi properti yang terkait dengan grup pendaftaran tempat permintaan alokasi berasal. Ada jika perangkat mendaftar melalui grup pendaftaran.
deviceRuntimeContext	Objek yang berisi properti yang terkait dengan perangkat yang mendaftar. Selalu ada.
linkedHubs	Array yang berisi nama host hub IoT yang ditautkan ke entri pendaftaran tempat permintaan alokasi berasal. Perangkat dapat ditetapkan ke salah satu hub IoT ini. Selalu ada.

Objek DeviceRuntimeContext memiliki properti berikut:

Properti	Tipe	Deskripsi
registrationId	string	ID pendaftaran yang disediakan oleh perangkat saat runtime. Selalu ada.
currentIotHubHostName	string	Nama host hub IoT yang sebelumnya ditetapkan perangkat (jika ada). Tidak ada jika ini adalah penugasan awal. Anda dapat menggunakan properti ini untuk menentukan apakah ini adalah penugasan awal untuk perangkat atau apakah perangkat telah ditetapkan sebelumnya.
currentDeviceId	string	ID perangkat dari penugasan perangkat sebelumnya (jika ada). Tidak ada jika ini adalah penugasan awal.
x509	X509DeviceAttestation	Untuk pengesahan X.509, berisi detail sertifikat.
symmetricKey	SymmetricKeyAttestation	Untuk pengesahan kunci konten, berisi detail kunci primer dan sekunder.
Tpm	TpmAttestation	Untuk pengesahan TPM, berisi kunci dukungan dan detail kunci akar penyimpanan.
payload	object	Berisi properti yang ditentukan oleh perangkat di properti payload selama pendaftaran. Ada jika perangkat mengirim payload kustom dalam permintaan pendaftaran DPS.

JSON berikut menunjukkan objek AllocationRequest yang dikirim oleh DPS untuk perangkat yang mendaftar melalui grup pendaftaran berbasis kunci konten.

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

Karena ini adalah pendaftaran awal untuk perangkat, properti deviceRuntimeContext hanya berisi ID pendaftaran dan detail autentikasi untuk perangkat. JSON berikut menunjukkan deviceRuntimeContext untuk panggilan berikutnya untuk mendaftarkan perangkat yang sama. Perhatikan bahwa nama host dan ID perangkat IoT Hub saat ini disertakan dalam permintaan.

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

Respons kebijakan alokasi kustom

Permintaan yang berhasil mengembalikan objek AllocationResponse .

Properti	Deskripsi
initialTwin	Opsional. Objek yang berisi properti dan tag yang diinginkan untuk diatur dalam kembar awal pada hub IoT yang ditetapkan. DPS menggunakan properti initialTwin untuk mengatur kembar awal pada hub IoT yang ditetapkan pada penugasan awal atau saat memprovisi ulang jika kebijakan migrasi entri pendaftaran diatur ke Provisi ulang dan atur ulang ke konfigurasi awal. Dalam kedua kasus ini, jika initialTwin tidak dikembalikan atau diatur ke null, DPS mengatur kembar pada hub IoT yang ditetapkan ke pengaturan kembar awal dalam entri pendaftaran. DPS mengabaikan initialTwin untuk semua pengaturan provisi ulang lainnya dalam entri pendaftaran. Untuk mempelajari selengkapnya, lihat Detail implementasi.
iotHubHostName	Harus diisi. Nama host hub IoT untuk menetapkan perangkat. Ini harus menjadi salah satu hub IoT yang diteruskan di properti linkedHubs dalam permintaan.
payload	Opsional. Objek yang berisi data yang akan diteruskan kembali ke perangkat dalam respons Pendaftaran. Data yang tepat akan bergantung pada kontrak implisit yang ditentukan oleh pengembang antara perangkat dan fungsi alokasi kustom.

JSON berikut menunjukkan objek AllocationResponse yang dikembalikan oleh fungsi alokasi kustom ke DPS untuk contoh pendaftaran di atas.

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

Menggunakan payload perangkat dalam alokasi kustom

Perangkat dapat mengirim payload kustom yang diteruskan oleh DPS ke webhook alokasi kustom Anda, yang kemudian dapat menggunakan data tersebut dalam logikanya. Webhook dapat menggunakan data ini dengan sejumlah cara, mungkin untuk menentukan hub IoT mana yang akan ditetapkan perangkat, atau untuk mencari informasi dalam database eksternal yang mungkin digunakan untuk mengatur properti pada kembar awal. Sebaliknya, webhook Anda dapat mengembalikan data kembali ke perangkat melalui DPS, yang dapat digunakan dalam logika sisi klien perangkat.

Misalnya, Anda mungkin ingin mengalokasikan perangkat berdasarkan model perangkat. Dalam hal ini, Anda dapat mengonfigurasi perangkat untuk melaporkan informasi modelnya dalam payload permintaan saat mendaftar dengan DPS. DPS akan meneruskan payload ini ke webhook alokasi kustom, yang akan menentukan hub IoT mana yang akan disediakan perangkat berdasarkan informasi model perangkat. Jika diperlukan, webhook dapat mengembalikan data kembali ke DPS sebagai objek JSON dalam respons webhook, dan DPS akan mengembalikan data ini ke perangkat Anda dalam respons pendaftaran.

Perangkat mengirim payload data ke DPS

Perangkat memanggil API register untuk mendaftar dengan DPS. Permintaan dapat ditingkatkan dengan properti payload opsional. Properti ini dapat berisi objek JSON yang valid. Konten yang tepat akan bergantung pada persyaratan solusi Anda.

Untuk pengesahan dengan TPM, isi permintaan terlihat seperti berikut ini:

{ 
    "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 mengirim payload data ke webhook alokasi kustom

Jika perangkat menyertakan payload permintaan pendaftarannya, DPS meneruskan payload di properti AllocationRequest.deviceRuntimeContext.payload saat memanggil webhook alokasi kustom.

Untuk permintaan pendaftaran TPM di bagian sebelumnya, konteks runtime perangkat akan terlihat seperti berikut ini:

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

Jika ini bukan pendaftaran awal untuk perangkat, maka konteks runtime juga akan menyertakan currentIoTHubHostname dan properti currentDeviceId .

Webhook alokasi kustom mengembalikan data ke DPS

Webhook kebijakan alokasi kustom dapat mengembalikan data yang ditujukan untuk perangkat ke DPS dalam objek JSON menggunakan properti AllocationResponse.payload dalam respons webhook.

JSON berikut menunjukkan respons webhook yang menyertakan payload:

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

DPS mengirim payload data ke perangkat

Jika DPS menerima payload dalam respons webhook, DPS meneruskan data ini kembali ke perangkat di properti RegistrationOperationStatus.registrationState.payload sebagai respons pada pendaftaran yang berhasil. Properti registrationState berjenis DeviceRegistrationResult.

JSON berikut menunjukkan respons pendaftaran yang berhasil untuk perangkat TPM yang menyertakan properti payload :

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

Detail implementasi

Webhook alokasi kustom dapat dipanggil untuk perangkat yang sebelumnya belum terdaftar melalui DPS (penugasan awal) atau untuk perangkat yang sebelumnya telah didaftarkan melalui DPS (provisi ulang). DPS mendukung kebijakan provisi ulang berikut: Provisi ulang dan migrasi data, Provisi ulang dan atur ulang ke konfigurasi awal, dan Jangan pernah provisi ulang. Kebijakan ini diterapkan setiap kali perangkat yang disediakan sebelumnya ditetapkan ke hub IoT baru. Untuk detail selengkapnya, lihat Provisi ulang.

Poin-poin berikut menjelaskan persyaratan yang harus diamati dan perilaku webhook alokasi kustom Anda saat merancang webhook Anda:

Perangkat harus ditetapkan ke salah satu hub IoT di properti AllocationRequest.linkedHubs . Properti ini berisi daftar hub IoT berdasarkan nama host tempat perangkat dapat ditetapkan. Ini biasanya terdiri dari hub IoT yang dipilih untuk entri pendaftaran. Jika tidak ada hub IoT yang dipilih dalam entri pendaftaran, hub IoT akan ditautkan ke instans DPS. Terakhir, jika perangkat provisi ulang dan kebijakan Jangan pernah provisi ulang diatur pada entri pendaftaran, itu hanya akan berisi hub IoT yang saat ini ditetapkan perangkat.
Pada penugasan awal, jika properti initialTwin dikembalikan oleh webhook, DPS akan mengatur kembar awal untuk perangkat pada hub IoT yang ditetapkan. Jika properti initialTwin dihilangkan atau null, DPS mengatur kembar awal untuk perangkat ke pengaturan kembar awal yang ditentukan dalam entri pendaftaran.
Pada provisi ulang, DPS mengikuti kebijakan provisi ulang yang ditetapkan dalam entri pendaftaran. DPS hanya menggunakan properti initialTwin dalam respons jika hub IoT saat ini diubah dan kebijakan provisi ulang yang ditetapkan pada entri pendaftaran adalah Provisi ulang dan reset ke konfigurasi awal. Dalam hal ini, DPS mengatur kembaran awal untuk perangkat pada hub IoT baru persis seperti saat penugasan awal di poin sebelumnya. Dalam semua kasus lain, DPS mengabaikan properti initialTwin .
Jika properti payload diatur dalam respons, DPS akan selalu mengembalikannya ke perangkat terlepas dari apakah permintaan tersebut untuk penugasan awal atau penyediaan ulang.
Jika perangkat sebelumnya telah diprovisikan ke hub IoT, AllocationRequest.deviceRuntimeContext akan berisi properti currentIotHubHostName , yang akan diatur ke nama host hub IoT tempat perangkat saat ini ditetapkan.
Anda dapat menentukan kebijakan penyediaan ulang mana yang saat ini ditetapkan pada entri pendaftaran, dengan memeriksa properti reprovisionPolicy dari properti AllocationRequest.individualEnrollment atau properti AllocationRequest.enrollmentGroup dalam permintaan. JSON berikut menunjukkan pengaturan untuk kebijakan Provisi ulang dan migrasi data :
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

Dukungan SDK

SDK perangkat DPS menyediakan API di C, C#, Java, dan Node.js untuk membantu Anda mendaftarkan perangkat dengan DPS. SDK IoT Hub dan SDK DPS menyediakan kelas yang mewakili artefak perangkat dan layanan seperti kembar perangkat dan entri pendaftaran yang mungkin berguna saat mengembangkan webhook alokasi kustom. Untuk mempelajari selengkapnya tentang Azure IoT SDK yang tersedia untuk IoT Hub dan layanan Provisi Perangkat IoT Hub, lihat SDK Azure IoT Hub dan Azure DPS SDK.

Langkah berikutnya

Untuk contoh end-to-end menggunakan kebijakan alokasi kustom, lihat Menggunakan kebijakan alokasi kustom
Untuk mempelajari selengkapnya tentang Azure Functions, lihat dokumentasi Azure Functions