Memahami registri identitas di IoT hub Anda
Setiap IoT hub memiliki registri identitas yang menyimpan informasi tentang perangkat dan modul yang diizinkan untuk terhubung ke IoT hub. Sebelum perangkat atau modul dapat terhubung ke IoT hub, harus ada entri untuk perangkat atau modul tersebut di registri identitas IoT hub. Perangkat atau modul juga harus mengautentikasi dengan IoT hub berdasarkan info masuk yang disimpan dalam registri identitas.
ID perangkat atau modul yang disimpan dalam registri identitas peka huruf besar/kecil.
Pada tingkat tinggi, registri identitas adalah koleksi perangkat berkemampuan REST atau sumber daya identitas modul. Saat Anda menambahkan entri dalam registri identitas, IoT Hub membuat sekumpulan sumber daya per perangkat seperti antrean yang berisi pesan cloud ke perangkat dalam penerbangan.
Gunakan registri identitas saat Anda perlu:
- Provisi perangkat atau modul yang terhubung ke IoT hub Anda.
- Kontrol akses per perangkat/per modul ke perangkat hub atau titik akhir yang menghadap modul Anda.
Operasional registri identitas
Registri identitas IoT Hub memaparkan operasi berikut:
- Membuat identitas perangkat atau modul
- Memperbarui identitas perangkat atau modul
- Memperoleh identitas perangkat atau modul dengan ID
- Menghapus identitas perangkat atau modul
- Mencantumkan hingga 1000 identitas
- Mengekspor identitas perangkat ke Azure blob storage
- Mengimpor identitas perangkat ke Azure blob storage
Semua operasi ini dapat menggunakan konkurensi optimis, seperti yang ditentukan dalam RFC7232.
Penting
Satu-satunya cara untuk mengambil semua identitas dalam registri identitas IoT hub adalah dengan menggunakan fungsionalitas Ekspor.
Registri identitas IoT Hub:
- Tidak berisi metadata aplikasi apa pun.
Penting
Hanya gunakan registri identitas untuk manajemen perangkat dan operasi provisi. Operasi throughput tinggi pada waktu proses seharusnya tidak tergantung pada melakukan operasi di registri identitas. Misalnya, memeriksa status koneksi perangkat sebelum mengirim perintah bukanlah pola yang didukung. Pastikan untuk memeriksa tingkat pembatasan untuk registri identitas.
Catatan
Diperlukan waktu beberapa detik agar identitas perangkat atau modul tersedia untuk dapat diambil setelah pembuatan. Harap coba lagi get pengoperasian identitas perangkat atau modul jika terjadi kegagalan.
Menonaktifkan perangkat
Anda dapat menonaktifkan perangkat dengan memperbarui properti status identitas di registri identitas. Biasanya, Anda menggunakan properti ini dalam dua skenario:
Selama proses orkestrasi provisi. Untuk informasi selengkapnya, lihat Provisi Perangkat.
Jika Menurut Anda perangkat disusupi atau telah menjadi tidak sah karena alasan apa pun.
Penting
IoT Hub tidak memeriksa daftar pencabutan sertifikat saat mengautentikasi perangkat dengan autentikasi berbasis sertifikat. Jika Anda memiliki perangkat yang perlu diblokir agar tidak tersambung ke IoT Hub karena sertifikat yang berpotensi disusupi, Anda harus menonaktifkan perangkat di registri identitas.
Fitur ini tidak tersedia untuk modul.
Untuk informasi selengkapnya, lihat Menonaktifkan atau menghapus perangkat di hub IoT.
Impor dan ekspor identitas perangkat
Gunakan operasi asinkron pada titik akhir penyedia sumber daya IoT Hub untuk mengekspor identitas perangkat secara massal dari registri identitas IoT Hub. Ekspor adalah pekerjaan jangka panjang yang menggunakan kontainer blob yang disediakan pelanggan untuk menyimpan data identitas perangkat yang dibaca dari registri identitas.
Gunakan operasi asinkron pada titik akhir penyedia sumber daya IoT Hub untuk mengimpor identitas perangkat secara massal ke registri identitas IoT Hub. Impor adalah pekerjaan jangka panjang yang menggunakan kontainer blob yang disediakan pelanggan untuk menulis data identitas perangkat ke registri identitas.
Untuk informasi selengkapnya tentang API impor dan ekspor, lihat REST API penyedia sumber daya IoT Hub. Untuk mempelajari selengkapnya tentang menjalankan pekerjaan impor dan ekspor, lihat Manajemen massal identitas perangkat IoT Hub.
Identitas perangkat juga dapat diekspor dan diimpor dari hub IoT dengan menggunakan API Layanan melalui REST API atau salah satu SDK Layanan IoT Hub.
Provisi perangkat
Data perangkat yang disimpan solusi IoT tertentu tergantung pada persyaratan khusus dari solusi tersebut. Tapi, minimal, solusi harus menyimpan identitas perangkat dan kunci autentikasi. Azure IoT Hub menyertakan registri identitas yang dapat menyimpan nilai untuk setiap perangkat seperti ID, kunci autentikasi, dan kode status. Solusi dapat menggunakan layanan Azure lainnya seperti penyimpanan Tabel, penyimpanan Blob, atau Azure Cosmos DB untuk menyimpan data perangkat lainnya.
Provisi perangkat adalah proses penambahan data perangkat awal ke penyimpanan dalam solusi Anda. Untuk mengaktifkan perangkat baru agar tersambung ke hub, Anda harus menambahkan kunci dan ID perangkat ke registri identitas IoT Hub. Sebagai bagian dari proses provisi, Anda mungkin perlu menginisialisasi data khusus perangkat di penyimpanan solusi lainnya. Anda juga dapat menggunakan Azure IoT Hub Device Provisioning Service untuk mengaktifkan provisi just-in-time tanpa sentuhan ke satu atau beberapa IoT Hub tanpa memerlukan intervensi manusia. Untuk mempelajari lebih lanjut, lihat dokumentasi layanan provisi.
Pemberitahuan siklus hidup modul dan perangkat
IoT Hub dapat memberi tahu solusi IoT Anda saat identitas perangkat dibuat atau dihapus dengan mengirim notifikasi siklus hidup. Untuk melakukannya, solusi IoT Anda perlu membuat rute dan mengatur sumber data yang sama dengan DeviceLifecycleEvents. Secara default, tidak ada pemberitahuan siklus hidup yang dikirim, yaitu tidak ada rute seperti itu yang sudah ada sebelumnya. Dengan membuat rute dengan Sumber Data yang sama dengan DeviceLifecycleEvents, peristiwa siklus hidup dikirim untuk identitas perangkat dan identitas modul; namun, konten pesan berbeda tergantung pada apakah peristiwa dihasilkan untuk identitas modul atau identitas perangkat. Perlu dicatat bahwa untuk modul IoT Edge, aliran pembuatan identitas modul berbeda dari modul lain, sebagai hasilnya untuk modul IoT Edge, pemberitahuan pembuatan hanya dikirim jika Perangkat IoT Edge yang sesuai untuk identitas modul IoT Edge yang diperbarui berjalan. Untuk semua modul lainnya, notifikasi siklus hidup dikirim setiap kali identitas modul diperbarui di sisi IoT Hub. Untuk mempelajari lebih lanjut tentang properti dan isi yang dikembalikan dalam pesan notifikasi, lihat Skema peristiwa non-telemetri.
Properti identitas perangkat
Identitas perangkat dinyatakan sebagai dokumen JSON dengan properti berikut:
| Properti | Opsi | Deskripsi |
|---|---|---|
| deviceId | diperlukan, baca-saja pada pembaruan | Untai (karakter) peka huruf besar/kecil (panjang maksimal 128 karakter) karakter alfanumerik 7-bit ASCII plus karakter khusus tertentu: - . % _ * ? ! ( ) , : = @ $ '. Karakter khusus: + # tidak didukung. |
| generationId | diperlukan, baca-saja | Untai (karakter) dihasilkan IoT hub, peka huruf besar kecil hingga 128 karakter. Nilai ini digunakan untuk membedakan perangkat dengan deviceId yang sama, ketika telah dihapus dan dibuat ulang. |
| etag | diperlukan, baca-saja | Untai (karakter) yang mewakili ETag lemah untuk identitas perangkat, sesuai RFC7232. |
| Autentikasi | Opsional. | Objek komposit yang berisi informasi autentikasi dan materi keamanan. Untuk informasi selengkapnya, lihat Mekanisme Autentikasi di dokumentasi REST API. |
| capabilities | opsional | Set kemampuan perangkat. Misalnya, apakah perangkat adalah perangkat edge atau tidak. Untuk informasi selengkapnya, lihat Kemampuan Perangkat di dokumentasi REST API. |
| deviceScope | opsional | Cakupan perangkat. Di perangkat edge, dibuat otomatis dan tidak berubah. Tidak digunakan lagi di perangkat non-edge. Namun, di perangkat anak (leaf), atur properti ini ke nilai yang sama dengan properti parentScopes (deviceScope dari perangkat induk) untuk kompatibilitas mundur dengan versi API sebelumnya. Untuk informasi selengkapnya, lihat IoT Edge sebagai gateway: Hubungan induk dan anak. |
| parentScopes | opsional | Cakupan induk langsung dari perangkat anak (nilai properti deviceScope dari perangkat induk). Di perangkat edge, nilai kosong jika perangkat tidak memiliki induk. Di perangkat non-edge, properti tidak ada jika perangkat tidak memiliki induk. Untuk informasi selengkapnya, lihat IoT Edge sebagai gateway: Hubungan induk dan anak. |
| status | diperlukan | Indikator akses. Bisa Diaktifkan atau Dinonaktifkan. Jika Diaktifkan, perangkat diperbolehkan untuk terhubung. Jika Dinonaktifkan, perangkat ini tidak dapat mengakses titik akhir yang menghadap perangkat apa pun. |
| statusReason | Opsional. | Untai (karakter) sepanjang 128 karakter yang menyimpan alasan status identitas perangkat. Semua karakter UTF-8 diperbolehkan. |
| statusUpdateTime | baca-saja | Indikator sementara, memperlihatkan tanggal dan waktu pembaruan status terakhir. |
| connectionState | baca-saja | Bidang yang menunjukkan status koneksi: baik Tersambung atau Terputus. Bidang ini mewakili tampilan IoT Hub dari status koneksi perangkat. Penting: Bidang ini harus digunakan hanya untuk tujuan pengembangan/penelusuran kesalahan. Status koneksi diperbarui hanya untuk perangkat yang menggunakan MQTT atau AMQP. Selain itu, ini didasarkan pada ping tingkat protokol (ping MQTT, atau ping AMQP), dan dapat memiliki penundaan maksimum hanya 5 menit. Untuk alasan ini, mungkin ada positif palsu, seperti perangkat yang terputus yang dilaporkan tersambung. |
| connectionStateUpdatedTime | baca-saja | Indikator sementara, memperlihatkan tanggal dan terakhir kali status koneksi diperbarui. |
| lastActivityTime | baca-saja | Indikator sementara, memperlihatkan tanggal dan terakhir kali perangkat terhubung, menerima, atau mengirim pesan. Properti ini akhirnya konsisten, tetapi bisa tertunda hingga 5 hingga 10 menit. Untuk alasan ini, itu tidak boleh digunakan dalam skenario produksi. |
Catatan
Status koneksi hanya dapat mewakili tampilan IoT Hub dari status koneksi. Pembaruan untuk status ini bisa tertunda, tergantung pada kondisi dan konfigurasi jaringan.
Catatan
Saat ini SDK perangkat tidak mendukung penggunaan karakter + dan # di deviceId.
Properti identitas modul
Identitas modul dinyatakan sebagai dokumen JSON dengan properti berikut:
| Properti | Opsi | Deskripsi |
|---|---|---|
| deviceId | diperlukan, baca-saja pada pembaruan | Untai (karakter) peka huruf besar/kecil (panjang maksimal 128 karakter) karakter alfanumerik 7-bit ASCII plus karakter khusus tertentu: - . + % _ # * ? ! ( ) , : = @ $ '. |
| moduleId | diperlukan, baca-saja pada pembaruan | Untai (karakter) peka huruf besar/kecil (panjang maksimal 128 karakter) karakter alfanumerik 7-bit ASCII plus karakter khusus tertentu: - . + % _ # * ? ! ( ) , : = @ $ '. |
| generationId | diperlukan, baca-saja | Untai (karakter) dihasilkan IoT hub, peka huruf besar kecil hingga 128 karakter. Nilai ini digunakan untuk membedakan perangkat dengan deviceId yang sama, ketika telah dihapus dan dibuat ulang. |
| etag | diperlukan, baca-saja | Untai (karakter) yang mewakili ETag lemah untuk identitas perangkat, sesuai RFC7232. |
| Autentikasi | Opsional. | Objek komposit yang berisi informasi autentikasi dan materi keamanan. Untuk informasi selengkapnya, lihat Mekanisme Autentikasi di dokumentasi REST API. |
| managedBy | opsional | Mengidentifikasi siapa yang mengelola modul ini. Misalnya, nilai ini adalah "IoT Edge" jika runtime edge memiliki modul ini. |
| cloudToDeviceMessageCount | baca-saja | Jumlah pesan cloud-to-module saat ini mengantre untuk dikirim ke modul. |
| connectionState | baca-saja | Bidang yang menunjukkan status koneksi: baik Tersambung atau Terputus. Bidang ini mewakili tampilan IoT Hub dari status koneksi perangkat. Penting: Bidang ini harus digunakan hanya untuk tujuan pengembangan/penelusuran kesalahan. Status koneksi diperbarui hanya untuk perangkat yang menggunakan MQTT atau AMQP. Selain itu, ini didasarkan pada ping tingkat protokol (ping MQTT, atau ping AMQP), dan dapat memiliki penundaan maksimum hanya 5 menit. Untuk alasan ini, mungkin ada positif palsu, seperti perangkat yang terputus yang dilaporkan tersambung. |
| connectionStateUpdatedTime | baca-saja | Indikator sementara, memperlihatkan tanggal dan terakhir kali status koneksi diperbarui. |
| lastActivityTime | baca-saja | Indikator sementara, memperlihatkan tanggal dan terakhir kali perangkat terhubung, menerima, atau mengirim pesan. |
Catatan
Saat ini SDK perangkat tidak mendukung penggunaan karakter + dan # di deviceId dan moduleId.
Materi referensi tambahan
Artikel referensi lain dalam panduan pengembang IoT Hub meliputi:
Titik akhir IoT Hub menjelaskan berbagai titik akhir tempat setiap IoT Hub diekspos untuk operasi run-time dan pengelolaan.
Pembatasan dan kuota menjelaskan perilaku kuota dan pembatasan yang berlaku untuk layanan IoT Hub.
SDK perangkat dan layanan Azure IoT mencantumkan berbagai SDK bahasa yang dapat digunakan saat Anda mengembangkan aplikasi perangkat dan layanan yang berinteraksi dengan IoT Hub.
Bahasa kueri IoT Hub menjelaskan bahasa kueri yang dapat Anda gunakan untuk mengambil informasi dari IoT Hub tentang twin perangkat dan pekerjaan Anda.
Dukungan MQTT IoT Hub memberikan informasi selengkapnya tentang dukungan IoT Hub untuk protokol MQTT.
Langkah berikutnya
Sekarang setelah Anda mempelajari cara menggunakan registri identitas IoT Hub, Anda mungkin tertarik dengan artikel panduan pengembang IoT Hub berikut:
Untuk menjelajahi menggunakan IoT Hub Device Provisioning Service untuk mengaktifkan provisi just-in-time, tanpa sentuhan, lihat: