Memahami kebijakan alokasi kustom dengan Azure IoT Hub Device Provisioning Service

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:

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

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

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

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

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

6. Perangkat terhubung ke hub IoT yang ditetapkan dan mengunduh status kembar awalnya. Jika payload kustom 00000000000000000000000000000000000000000000000000000000returned 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.

Mengelola kunci fungsi

Kebijakan alokasi kustom menggunakan kunci fungsi untuk mengautentikasi panggilan ke Azure Functions tempat tingkat otorisasi diatur ke Function. Perilaku manajemen kunci berbeda berdasarkan apakah Anda mengonfigurasi kebijakan alokasi kustom melalui portal Azure atau secara terprogram.

Kunci fungsi di portal

Saat Anda membuat pendaftaran di portal Azure dan menentukan kebijakan alokasi kustom, portal secara otomatis menangani pengambilan dan penyematan kunci fungsi.

Setelah memilih fungsi untuk kebijakan alokasi kustom, portal mengambil kunci fungsi. Langkah ini tidak terlihat oleh pengguna melalui antarmuka portal. Kemudian, kunci fungsi disimpan sebagai bagian dari URL webhook terenkripsi yang digunakan oleh DPS untuk memanggil fungsi. Kunci tidak ditampilkan di portal.

Anda dapat memverifikasi bahwa kunci disematkan di URL webhook dengan menjalankan perintah GET untuk mengambil detail pendaftaran. Dalam konfigurasi pendaftaran, kunci fungsi disertakan dalam bidang webhookUrl .

Kunci fungsi dengan API

Saat Anda membuat pendaftaran secara terprogram menggunakan API DPS, Anda perlu memberikan kunci secara manual selama pembuatan pendaftaran. Jika kunci tidak disediakan, panggilan Azure Functions gagal autentikasi.

Sebelum Anda membuat pendaftaran individu atau grup, ambil kunci fungsi dari fungsi Anda. Untuk informasi selengkapnya, lihat Mendapatkan kunci akses fungsi Anda. Kemudian, sertakan kunci fungsi di bidang webhookUrl dari CustomAllocationDefinition.

Untuk informasi selengkapnya, lihat Otorisasi kunci Akses pemicu > HTTP Azure Functions.

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 :

Objek DeviceRuntimeContext memiliki properti berikut:

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 .

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