Memahami dan menggunakan perangkat ganda di IoT Hub
Perangkat ganda adalah dokumen JSON yang menyimpan informasi status perangkat termasuk metadata, konfigurasi, dan kondisi. Azure IoT Hub mempertahankan perangkat ganda untuk setiap perangkat yang Anda sambungkan ke IoT Hub.
Catatan
Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.
Artikel ini menjelaskan:
- Struktur perangkat kembar: tag, properti yang diinginkan, dan properti yang dilaporkan.
- Operasi yang dapat dilakukan aplikasi perangkat dan back-end pada perangkat kembar.
Gunakan perangkat ganda untuk:
Simpan metadata khusus perangkat di cloud. Misalnya, lokasi mesin penjual otomatis.
Melaporkan informasi status terkini seperti kemampuan dan kondisi yang tersedia dari aplikasi perangkat Anda. Misalnya, perangkat tersambung ke IoT Hub Anda melalui seluler atau WiFi.
Menyinkronkan status alur kerja jangka panjang antara aplikasi perangkat dan aplikasi back-end. Misalnya, saat back end solusi menentukan versi firmware baru untuk diinstal, dan aplikasi perangkat melaporkan berbagai tahap proses pembaruan.
Mengkueri metadata, konfigurasi, atau status perangkat Anda.
Untuk informasi selengkapnya tentang menggunakan properti yang dilaporkan, pesan perangkat ke cloud, atau unggahan file, lihat Panduan komunikasi perangkat ke cloud.
Untuk informasi selengkapnya tentang menggunakan properti yang diinginkan, metode langsung, atau pesan cloud-ke-perangkat, lihat Panduan komunikasi cloud-ke-perangkat.
Untuk mempelajari bagaimana perangkat ganda berhubungan dengan model perangkat yang digunakan oleh perangkat Azure IoT Plug and Play, lihat Memahami digital ganda IoT Plug and Play.
Perangkat ganda
Perangkat ganda menyimpan informasi terkait perangkat yang:
Perangkat dan back end dapat digunakan untuk menyinkronkan kondisi dan konfigurasi perangkat.
Solusi back end solusi dapat menggunakan untuk mengkueri dan menargetkan operasi yang berjalan lama.
Siklus hidup perangkat kembar ditautkan ke identitas perangkat yang sesuai. Perangkat ganda secara implisit dibuat dan dihapus saat identitas perangkat dibuat atau dihapus di IoT Hub.
Perangkat ganda adalah dokumen JSON yang mencakup:
Tag. Bagian dari dokumen JSON yang dapat dibaca dan ditulis oleh back end solusi. Tag tidak terlihat oleh aplikasi perangkat.
Properti yang diinginkan. Digunakan beserta properti yang dilaporkan untuk menyinkronkan konfigurasi atau kondisi perangkat. Back end solusi dapat mengatur properti yang diinginkan, dan aplikasi perangkat dapat membacanya. Aplikasi perangkat juga dapat menerima pemberitahuan tentang perubahan pada properti yang diinginkan.
Properti yang dilaporkan. Digunakan beserta properti yang diinginkan untuk menyinkronkan konfigurasi atau kondisi perangkat. Aplikasi perangkat dapat mengatur properti yang dilaporkan, dan back end solusi dapat membaca dan mengkuerinya.
Properti identitas perangkat. Akar dokumen JSON perangkat ganda berisi properti baca-saja dari identitas perangkat terkait yang disimpan dalam registri identitas. Properti
connectionStateUpdatedTimedangenerationIdtidak akan disertakan.
Contoh berikut menunjukkan dokumen JSON perangkat ganda:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
Objek akar berisi properti identitas perangkat, dan objek kontainer untuk tags dan properti dan desired .reported Kontainer properties berisi beberapa elemen baca-saja ($metadata dan $version) yang dijelaskan dalam Metadata perangkat kembar dan bagian Konkurensi optimis.
Contoh properti yang dilaporkan
Pada contoh sebelumnya, perangkat ganda berisi properti batteryLevel yang dilaporkan oleh aplikasi perangkat. Properti ini memungkinkan untuk mengkueri dan mengoperasikan perangkat berdasarkan tingkat baterai yang terakhir dilaporkan. Contoh lain termasuk kemampuan perangkat pelaporan aplikasi perangkat atau opsi konektivitas.
Catatan
Properti yang dilaporkan menyederhanakan skenario di mana back end solusi tertarik pada nilai terakhir properti yang diketahui. Gunakan pesan perangkat-ke-cloud jika back end solusi perlu memproses telemetri perangkat dalam bentuk urutan peristiwa bertanda waktu, seperti rangkaian waktu.
Contoh properti yang diinginkan
Dalam contoh sebelumnya, properti yang diinginkan dan dilaporkan dari perangkat ganda telemetryConfig digunakan oleh back end solusi dan aplikasi perangkat untuk menyinkronkan konfigurasi telemetri untuk perangkat ini. Misalnya:
Back end solusi mengatur properti yang diinginkan dengan nilai konfigurasi yang diinginkan. Berikut adalah bagian dokumen dengan kumpulan properti yang diinginkan:
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },Aplikasi perangkat diberi tahu tentang perubahan segera jika terhubung. Jika tidak terhubung, aplikasi perangkat mengikuti alur rekoneksi perangkat saat terhubung. Aplikasi perangkat kemudian melaporkan konfigurasi yang diperbarui (atau kondisi kesalahan menggunakan properti
status). Berikut adalah bagian dari properti yang dilaporkan:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Back end solusi dapat melacak hasil operasi konfigurasi di banyak perangkat dengan mengkueri perangkat ganda.
Catatan
Cuplikan sebelumnya adalah contoh, dioptimalkan untuk keterbacaan, salah satu cara untuk mengodekan konfigurasi perangkat dan statusnya. IoT Hub tidak memaksakan skema khusus untuk perangkat ganda yang diinginkan dan dilaporkan properti di perangkat ganda.
Penting
IoT Plug and Play mendefinisikan skema yang menggunakan beberapa properti tambahan untuk menyinkronkan perubahan ke properti yang diinginkan dan dilaporkan. Jika solusi Anda menggunakan IoT Plug and Play, Anda harus mengikuti konvensi Plug and Play saat memperbarui properti kembar. Untuk informasi lebih lanjut dan contoh, lihat Properti yang dapat ditulis di IoT Plug and Play.
Anda dapat menggunakan ganda untuk menyinkronkan operasi jangka panjang seperti pembaruan firmware. Untuk informasi selengkapnya tentang cara menggunakan properti untuk menyinkronkan dan melacak operasi jangka panjang di seluruh perangkat, lihat Menggunakan properti yang diinginkan untuk mengonfigurasi perangkat.
Operasi back-end
Back end solusi beroperasi pada perangkat ganda menggunakan operasi atom berikut, diekspos melalui HTTPS:
Mengambil perangkat ganda dengan ID. Operasi ini mengembalikan dokumen perangkat ganda, termasuk tag dan properti sistem yang diinginkan dan dilaporkan.
Memperbarui sebagian perangkat ganda. Operasi ini memungkinkan back end solusi untuk memperbarui sebagian tag atau properti yang diinginkan dalam perangkat ganda. Pembaruan parsial dinyatakan sebagai dokumen JSON yang menambahkan atau memperbarui properti apa pun. Properti yang diatur ke
nullakan dihapus. Contoh berikut membuat properti baru yang diinginkan dengan nilai{"newProperty": "newValue"}, menimpa nilaiexistingPropertyyang ada dengan"otherNewValue", dan menghapusotherOldProperty. Tidak ada perubahan lain yang dilakukan pada properti atau tag yang diinginkan:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Mengganti properti yang diinginkan. Operasi ini memungkinkan back end solusi untuk sepenuhnya menimpa semua properti yang diinginkan yang ada dan mengganti dokumen JSON baru untuk
properties/desired.Mengganti tag. Operasi ini memungkinkan back end solusi untuk sepenuhnya menimpa semua tag yang ada dan mengganti dokumen JSON baru untuk
tags.Menerima pemberitahuan ganda. Operasi ini memungkinkan back end solusi untuk diberitahu saat ganda dimodifikasi. Untuk melakukannya, solusi IoT Anda perlu membuat rute dan mengatur Sumber Data sama dengan twinChangeEvents. Secara default, tidak ada rute seperti itu sebelumnya, jadi tidak ada pemberitahuan ganda yang dikirim. Jika tingkat perubahan terlalu tinggi, atau karena alasan lain seperti kegagalan internal, IoT Hub mungkin hanya mengirim satu pemberitahuan yang berisi semua perubahan. Oleh karena itu, jika aplikasi Anda memerlukan audit dan pengelogan yang andal dari semua status perantara, Anda harus menggunakan pesan perangkat-ke-cloud. Untuk mempelajari selengkapnya tentang properti dan isi yang dikembalikan dalam pesan pemberitahuan kembar, lihat Skema peristiwa nontelemetry.
Semua operasi sebelumnya mendukung Konkurensi optimis dan memerlukan izin ServiceConnect, seperti yang ditentukan dalam Kontrol Akses ke IoT Hub.
Selain operasi ini, back end solusi dapat:
Buat kueri perangkat ganda menggunakan bahasa pemrogram kueri IoT Hub seperti SQL.
Melakukan operasi pada kumpulan besar perangkat ganda menggunakan pekerjaan.
Operasi perangkat
Aplikasi perangkat beroperasi pada perangkat ganda menggunakan operasi atom berikut:
Mengambil perangkat ganda. Operasi ini mengembalikan dokumen perangkat ganda (termasuk properti sistem yang diinginkan dan dilaporkan) untuk perangkat yang tersambung saat ini. (Tag tidak terlihat oleh aplikasi perangkat.)
Memperbarui sebagian properti yang dilaporkan. Operasi ini memungkinkan pembaruan sebagian dari properti yang dilaporkan dari perangkat yang saat ini tersambung. Operasi ini menggunakan format pembaruan JSON yang sama yang digunakan back end solusi untuk pembaruan sebagian properti yang diinginkan.
Mengamati properti yang diinginkan. Perangkat yang tersambung saat ini dapat memilih untuk diberi tahu tentang pembaruan properti yang diinginkan saat pembaruan tersebut terjadi. Perangkat menerima bentuk pembaruan yang sama (penggantian sebagian atau penuh) yang dijalankan oleh back end solusi.
Semua operasi sebelumnya memerlukan izin DeviceConnect, seperti yang ditentukan dalam Akses Kontrol ke IoT Hub.
SDK perangkat Azure IoT memudahkan penggunaan operasi sebelumnya dari banyak bahasa pemrogram dan platform. Untuk informasi selengkapnya tentang detail IoT Hub primitif untuk sinkronisasi properti yang diinginkan, lihat Alur koneksi ulang perangkat.
Format tag dan properti
Tag, properti yang diinginkan, dan properti yang dilaporkan adalah objek JSON dengan batasan berikut:
Kunci: Semua kunci dalam objek JSON dikodekan UTF-8, peka huruf besar/kecil, dan panjangnya hingga 1 KB. Karakter yang diizinkan mengecualikan karakter kontrol UNICODE (segmen C0 dan C1), dan
.,$, dan SP.Catatan
Kueri IoT Hub yang digunakan dalam Perutean Pesan tidak mendukung spasi kosong atau karakter berikut sebagai bagian dari nama kunci:
()<>@,;:\"/?={}.Nilai: Semua nilai dalam objek JSON dapat berupa jenis JSON berikut: boolean, angka, string, objek. Array yang juga didukung.
Bilangan bulat dapat memiliki nilai minimum -4503599627370496 dan nilai maksimum 4503599627370495.
Nilai string yang dikodekan adalah UTF-8 dan dapat memiliki panjang maksimum 4 KB.
Kedalaman: Kedalaman maksimum objek JSON dalam tag, properti yang diinginkan, dan properti yang dilaporkan adalah 10. Misalnya, objek berikut ini valid:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Ukuran perangkat ganda
IoT Hub memberlakukan batas ukuran 8 KB pada nilai tags, dan batas ukuran 32 KB masing-masing pada nilai properties/desired dan properties/reported. Jumlah ini tidak termasuk elemen baca-saja seperti $version dan $metadata/$lastUpdated.
Ukuran ganda dihitung sebagai berikut:
Untuk setiap properti dalam dokumen JSON, IoT Hub secara kumulatif menghitung dan menambahkan panjang kunci dan nilai properti.
Kunci properti dianggap sebagai string yang dikodekan UTF8.
Nilai properti sederhana dianggap sebagai string yang dikodekan UTF8, nilai numerik (8 Byte), atau nilai Boolean (4 Byte).
Ukuran string UTF8 yang dikodekan dihitung dengan menghitung semua karakter, tidak termasuk karakter kontrol UNICODE (segmen C0 dan C1).
Nilai properti kompleks (objek berlapis) dihitung berdasarkan ukuran agregat kunci properti dan nilai properti yang dimuatnya.
IoT Hub menolak dengan kesalahan semua operasi yang akan meningkatkan ukuran dokumen tags, properties/desired, atau properties/reported di atas batas.
Metadata perangkat ganda
IoT Hub mempertahankan tanda waktu pembaruan terakhir untuk setiap objek JSON di properti perangkat ganda yang diinginkan dan dilaporkan. Tanda waktu dalam UTC dan dikodekan dalam format ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ.
Misalnya:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Informasi ini disimpan di setiap tingkat (bukan hanya bagian dari struktur JSON) untuk mempertahankan pembaruan yang menghapus kunci objek.
Konkurensi optimis
Tag, properti yang diinginkan, dan properti yang dilaporkan semuanya mendukung konkurensi optimis. Jika Anda perlu menjamin urutan pembaruan properti kembar, pertimbangkan untuk menerapkan sinkronisasi di tingkat aplikasi dengan menunggu panggilan balik properti yang dilaporkan sebelum mengirim pembaruan berikutnya.
Perangkat kembar memiliki ETag (properti etag), sesuai RFC7232, yang mewakili representasi JSON kembar. Anda dapat menggunakan properti etag dalam operasi pembaruan kondisional dari ujung belakang solusi untuk memastikan konsistensi. Ini adalah satu-satunya opsi untuk memastikan konsistensi dalam operasi yang melibatkan kontainer tags.
Properti perangkat kembar yang diinginkan dan dilaporkan tidak memiliki $version yang dijamin akan bertambah secara bertahap. Demikian pula dengan ETag, versi dapat digunakan oleh pihak yang memperbarui untuk menegakkan konsistensi pembaruan. Misalnya, aplikasi perangkat untuk properti yang dilaporkan atau back end solusi untuk properti yang diinginkan.
Versi juga berguna saat agen pengamat (seperti aplikasi perangkat yang mengamati properti yang diinginkan) harus menyelaraskan kecepatan antara hasil operasi pengambilan dan pemberitahuan pembaruan. Bagian alur koneksi ulang perangkat memberikan informasi selengkapnya.
Alur koneksi ulang perangkat
IoT Hub tidak mempertahankan pemberitahuan pembaruan properti yang diinginkan untuk perangkat yang terputus. Oleh karena itu, perangkat yang tersambung harus mengambil dokumen properti yang diinginkan secara lengkap, selain berlangganan pemberitahuan pembaruan. Mengingat kemungkinan kecepatan antara pemberitahuan pembaruan dan pengambilan penuh, alur berikut harus dipastikan:
- Aplikasi perangkat tersambung ke IoT Hub.
- Aplikasi perangkat berlangganan untuk pemberitahuan pembaruan properti yang diinginkan.
- Aplikasi perangkat mengambil dokumen lengkap untuk properti yang diinginkan.
Aplikasi perangkat dapat mengabaikan semua notifikasi dengan $version kurang atau sama dengan versi dokumen lengkap yang diambil. Pendekatan ini dimungkinkan karena IoT Hub menjamin bahwa versi selalu bertahap.
Langkah berikutnya
Sekarang Anda telah mempelajari tentang perangkat ganda, Anda mungkin tertarik dengan topik panduan pengembang IoT Hub berikut:
- Memahami dan menggunakan modul ganda di IoT Hub
- Memanggil metode langsung pada perangkat
- Menjadwalkan pekerjaan di beberapa perangkat
Untuk mencoba beberapa konsep yang dijelaskan dalam artikel ini, lihat tutorial IoT Hub berikut ini: