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 melakukan kueri terhadap database untuk menentukan hub IoT mana yang harus ditetapkan untuk perangkat atau bagaimana kembar awal perangkat harus diatur.

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

Gambaran Umum

Langkah-langkah berikut menjelaskan cara kerja polisi alokasi kustom:

  1. Pengembang alokasi kustom mengembangkan webhook yang menerapkan kebijakan alokasi yang diinginkan dan menyebarkannya sebagai fungsi trigger HTTP ke Azure Functions. Webhook mengambil informasi tentang entri pendaftaran DPS dan perangkat dan mengembalikan hub IoT tempat perangkat tersebut harus didaftarkan serta, secara opsional, informasi tentang status awal perangkat.

  2. Operator IoT mengonfigurasi satu atau beberapa pendaftaran individu dan/atau grup pendaftaran untuk penjatahan kustom dan memberikan detail panggilan untuk webhook penjatahan kustom di Azure Functions.

  3. Ketika perangkat mendaftar melalui entri pendaftaran yang telah dikonfigurasi untuk webhook alokasi kustom, DPS mengirimkan permintaan POST ke webhook dengan isi permintaan yang diset sebagai objek permintaan AllocationRequest. Objek AllocationRequest berisi informasi tentang perangkat yang mencoba untuk mengonfigurasi dan jalur pendaftaran individu atau grup pendaftaran yang melaluinya pengonfigurasian dilakukan. 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 dijalankan dan mengembalikan objek AllocationResponse jika berhasil. Objek AllocationResponse berisi hub IoT tempat perangkat harus disediakan, status kembar awal, dan payload kustom opsional yang dikirimkan kembali ke perangkat. Untuk informasi selengkapnya, lihat Respons terhadap kebijakan alokasi khusus.

  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 tersebut terhubung ke hub IoT yang ditetapkan dan mengunduh status awal kembarannya. 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 informasi selengkapnya tentang contoh lengkap dari kebijakan alokasi kustom, lihat Tutorial: Menggunakan kebijakan alokasi kustom dengan Device Provisioning Service (DPS).

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.

Permintaan kebijakan alokasi khusus

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
pendaftaran individu Catatan pendaftaran individu yang memuat properti yang berkaitan dengan pendaftaran individu dimana permintaan alokasi berasal dari. Tersedia jika perangkat mendaftar melalui pendaftaran individu.
kelompok pendaftaran Rekaman grup pendaftaran yang berisi properti yang terkait dengan grup pendaftaran tempat permintaan alokasi berasal. Hadir jika perangkat sedang mendaftar melalui kelompok pendaftaran.
deviceRuntimeContext Objek yang berisi properti yang terkait dengan perangkat yang mendaftar. Selalu ada.
linkedHubs Sebuah array yang berisi nama host dari hub IoT yang ditautkan ke entri pendaftaran tempat permintaan alokasi berasal. Perangkat mungkin ditetapkan ke salah satu hub IoT ini. Selalu ada.

Objek DeviceRuntimeContext memiliki properti berikut:

Properti Tipe Deskripsi
IdRegistrasi string ID pendaftaran yang disediakan oleh perangkat saat runtime. Selalu ada.
currentIotHubHostName string Nama host hub IoT yang sebelumnya ditetapkan untuk perangkat ini (jika ada). Tidak ditampilkan jika ini adalah penugasan awal. Anda dapat menggunakan properti ini untuk menentukan apakah ini merupakan penetapan awal perangkat atau apakah perangkat sebelumnya telah ditetapkan.
IDPerangkatSaatIni string ID perangkat dari penugasan perangkat sebelumnya (jika ada). Tidak ditampilkan jika ini adalah penugasan awal.
x509 X509PerangkatPengesahan Untuk pengesahan X.509, berisi rincian sertifikat.
kunci simetris SymmetricKeyAttestation Untuk atestasi kunci simetris, berisi detail kunci primer dan sekunder.
Tpm Pengesahan Tpm Untuk pengesahan TPM, berisi kunci pengesahan dan detail kunci akar penyimpanan.
payload objek Berisi properti yang ditentukan oleh perangkat dalam properti payload selama proses pendaftaran. Ada jika perangkat mengirim payload kustom dalam permintaan pendaftaran DPS.

JSON berikut menunjukkan objek AllocationRequest yang dikirimkan untuk perangkat oleh DPS saat mendaftar melalui grup pendaftaran berbasis kunci simetris.

{
   "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 hub IoT dan ID perangkat 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 khusus

Permintaan yang berhasil mengembalikan objek AllocationResponse .

Properti Deskripsi
inisialKembar 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 ke mana perangkat akan ditetapkan. 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 tergantung 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 pendaftaran dalam contoh sebelumnya.

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

Menggunakan muatan perangkat dalam pengalokasian kustom

Perangkat dapat mengirim payload kustom yang diteruskan oleh DPS ke webhook penjatahan kustom Anda, yang kemudian dapat menggunakan data tersebut dalam logikanya. Webhook mungkin menggunakan data ini dalam banyak 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 mungkin 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 meneruskan payload ini ke webhook alokasi kustom, yang menentukan hub IoT mana yang disediakan perangkat berdasarkan informasi model perangkat. Jika diperlukan, webhook dapat mengembalikan data kembali ke DPS sebagai objek JSON dalam respons webhook, dan DPS mengembalikan data ini ke perangkat Anda dalam respons pendaftaran.

Perangkat mengirim payload data ke DPS

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

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

{ 
    "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 mengirimkan muatan data ke webhook alokasi yang disesuaikan

Jika sebuah perangkat menyertakan payload dalam permintaan pendaftarannya, DPS akan meneruskan payload tersebut melalui properti AllocationRequest.deviceRuntimeContext.payload saat memanggil webhook alokasi kustom.

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

{ 
    "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 menyertakan currentIoTHubHostname dan properti currentDeviceId .

Webhook alokasi kustom mengembalikan data ke DPS

Webhook kebijakan alokasi kustom dapat mengembalikan data ke DPS yang ditujukan untuk perangkat dalam bentuk 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 tidak terdaftar melalui DPS (penugasan awal) atau untuk perangkat yang sebelumnya terdaftar 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 informasi selengkapnya, lihat Konsep provisi ulang Perangkat IoT Hub.

Poin-poin berikut menjelaskan persyaratan yang harus dipatuhi dan perilaku yang harus Anda sadari ketika merancang webhook alokasi kustom 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, maka akan mencakup semua hub IoT yang ditautkan ke instance DPS. Terakhir, jika perangkat sedang diprovisikan ulang dan kebijakan Jangan pernah provisi ulang diatur pada entri pendaftaran, entri tersebut hanya berisi hub IoT yang saat ini ditetapkan untuk perangkat.

  • Pada penugasan awal, jika properti initialTwin dikembalikan oleh webhook, DPS menetapkan kembar awal untuk perangkat pada IoT hub yang telah ditetapkan. Jika properti initialTwin dihilangkan atau null, DPS menetapkan kembar awal untuk perangkat sesuai dengan pengaturan kembar awal yang ditentukan dalam entri pendaftaran.

  • Ketika melakukan 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 reprovisi yang ditetapkan pada entri pendaftaran adalah Reprovisi dan reset ke konfigurasi awal. Dalam kondisi ini, DPS mengatur kembaran awal untuk perangkat pada hub IoT baru persis seperti saat penugasan pertama kali di poin sebelumnya. Dalam semua kasus lain, DPS mengabaikan properti initialTwin .

  • Jika properti payload diatur dalam respons, DPS selalu mengembalikannya ke perangkat terlepas dari apakah permintaan tersebut untuk penugasan awal atau penyediaan ulang.

  • Jika perangkat sebelumnya disediakan ke hub IoT, AllocationRequest.deviceRuntimeContext berisi properti currentIotHubHostName , yang 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 Konfigurasi 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 IoT Hub Device Provisioning Service, lihat Azure IoT Hub SDK dan Microsoft SDK for IoT Hub Device Provisioning Service.

Langkah berikutnya

  • Last updated on