Memahami dan menggunakan perangkat ganda di IoT Hub

Perangkat kembar adalah dokumen JSON yang menyimpan informasi status perangkat termasuk metadata, konfigurasi, dan kondisi. Azure IoT Hub mempertahankan perangkat kembar 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 dan ukuran 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 solusi pada perangkat kembar.

Gunakan perangkat kembar untuk:

Simpan metadata khusus perangkat di cloud. Misalnya, lokasi mesin penjual otomatis.
Laporkan informasi status saat ini seperti kemampuan dan kondisi yang tersedia dari aplikasi perangkat Anda. Misalnya, apakah perangkat terhubung ke hub IoT Anda melalui seluler atau WiFi.
Sinkronkan status alur kerja yang berjalan lama antara aplikasi perangkat dan aplikasi back-end. Misalnya, ketika aplikasi back-end 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 kembar perangkat berhubungan dengan model perangkat yang digunakan oleh perangkat Azure IoT Plug and Play, lihat Memahami Kembar Digital IoT Plug and Play.

Perangkat ganda

Kembar perangkat menyimpan informasi terkait perangkat seperti:

Aplikasi perangkat dan aplikasi back-end dapat digunakan untuk menyinkronkan kondisi dan konfigurasi perangkat.
Solusi backend dapat menggunakan untuk mengkueri dan menargetkan operasi jangka panjang.

Siklus hidup perangkat kembar ditautkan ke identitas perangkat yang sesuai. Perangkat kembar secara implisit dibuat dan dihapus saat identitas perangkat dibuat atau dihapus di IoT Hub.

Sebuah perangkat kembar adalah dokumen JSON yang mencakup:

Tags. Bagian dari dokumen JSON yang dapat dibaca dan ditulis oleh aplikasi back-end. Tag tidak terlihat oleh aplikasi perangkat.
Properti yang diinginkan. Digunakan bersama dengan properti yang dilaporkan untuk menyinkronkan konfigurasi atau kondisi perangkat. Aplikasi back-end dapat mengatur properti yang diinginkan, dan aplikasi perangkat dapat membacanya. Aplikasi perangkat juga dapat menerima pemberitahuan perubahan di properti yang diinginkan.
Properti yang dilaporkan. Digunakan bersama dengan properti yang diinginkan untuk menyinkronkan konfigurasi atau kondisi perangkat. Aplikasi perangkat dapat mengatur properti yang dilaporkan, dan aplikasi back-end dapat membaca dan mengkuerinya.
Properti identitas perangkat. Akar dokumen JSON kembar perangkat berisi properti baca-saja dari identitas perangkat yang sesuai yang disimpan dalam registri identitas. Properti connectionStateUpdatedTime dan generationId tidak disertakan.

Diagram yang menunjukkan aplikasi mana yang berinteraksi dengan properti perangkat kembar mana.

Contoh berikut menunjukkan dokumen JSON kembar perangkat:

{
    "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 serta properti reported dan desired. Kontainer properties berisi beberapa elemen baca-saja ($metadata dan $version) yang dijelaskan dalam bagian Metadata kembar perangkat dan Konkurensi optimis .

Contoh properti yang dilaporkan

Dalam contoh sebelumnya, perangkat kembar berisi sebuah properti yang dilaporkan batteryLevel. Properti ini memungkinkan melakukan pencarian dan operasi pada perangkat berdasarkan tingkat baterai terakhir yang dilaporkan. Contoh lain termasuk aplikasi perangkat yang melaporkan kemampuan perangkat atau opsi konektivitas.

Catatan

Properti yang dilaporkan menyederhanakan skenario di mana Anda tertarik dengan nilai terakhir yang diketahui dari sebuah properti. Gunakan pesan perangkat ke cloud jika Anda ingin memproses telemetri perangkat dalam bentuk urutan peristiwa bertanda waktu, seperti rangkaian waktu.

Contoh properti yang diinginkan

Dalam contoh sebelumnya, telemetryConfig properti perangkat kembar yang diinginkan dan dilaporkan digunakan oleh back end solusi dan aplikasi perangkat untuk menyinkronkan konfigurasi telemetri untuk perangkat ini. Contohnya:

Aplikasi back-end mengatur properti yang diinginkan dengan nilai konfigurasi yang diinginkan. Berikut adalah bagian dokumen dengan kumpulan properti yang diinginkan:
```
"desired": {
    "telemetryConfig": {
        "sendFrequency": "5m"
    },
    ...
},
```
Aplikasi perangkat akan segera diberi tahu tentang perubahan jika perangkat tersambung. Jika tidak tersambung, aplikasi perangkat mengikuti alur koneksi ulang perangkat saat tersambung. Aplikasi perangkat kemudian melaporkan konfigurasi yang diperbarui (atau kondisi kesalahan menggunakan status properti ). Berikut adalah bagian dari properti yang dilaporkan:
```
"reported": {
    "telemetryConfig": {
        "sendFrequency": "5m",
        "status": "success"
    }
    ...
}
```
Aplikasi back-end melacak hasil operasi konfigurasi di banyak perangkat dengan mengkueri kembar perangkat.

Catatan

Cuplikan sebelumnya adalah contoh, yang dioptimalkan untuk keterbacaan, dari salah satu cara untuk mengodekan konfigurasi perangkat dan statusnya. IoT Hub tidak memberlakukan skema tertentu untuk perangkat kembar yang diinginkan dan dilaporkan properti di perangkat kembar.

Penting

IoT Plug and Play mendefinisikan skema yang menggunakan beberapa properti tambahan untuk menyinkronkan perubahan pada 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 selengkapnya dan contohnya, lihat Properti yang dapat ditulis di IoT Plug and Play.

Anda dapat menggunakan kembar untuk menyinkronkan operasi jangka panjang seperti pembaruan firmware. Untuk informasi selengkapnya tentang cara menggunakan properti untuk menyinkronkan dan melacak operasi yang berjalan lama di seluruh perangkat, lihat Menggunakan properti yang diinginkan untuk mengonfigurasi perangkat.

Operasi back-end

Bagian belakang solusi beroperasi pada kembar perangkat menggunakan operasi atom berikut, yang diekspos melalui HTTPS.

Ambil perangkat kembar berdasarkan ID. Operasi ini mengembalikan dokumen kembar perangkat, termasuk tag dan properti sistem yang diinginkan dan dilaporkan.
Memperbarui perangkat kembar sebagian. Operasi ini memperbarui sebagian tag atau properti yang diinginkan dalam perangkat kembar. Pembaruan parsial dinyatakan sebagai dokumen JSON yang menambahkan atau memperbarui properti apa pun. Properti yang disetel ke null akan dihapus. Contoh berikut membuat properti baru diinginkan dengan nilai {"newProperty": "newValue"}, mengganti nilai existingProperty yang ada dengan "otherNewValue", dan menghapus otherOldProperty. Tidak ada perubahan lain yang dilakukan pada properti atau tag yang diinginkan yang ada:
```
{
     "properties": {
         "desired": {
             "newProperty": {
                 "nestedProperty": "newValue"
             },
             "existingProperty": "otherNewValue",
             "otherOldProperty": null
         }
     }
}
```
Ganti properti yang diinginkan. Operasi ini sepenuhnya menimpa semua properti yang diinginkan yang ada dan menggantikan dokumen JSON baru untuk properties/desired.
Ganti tag. Operasi ini sepenuhnya menimpa semua tag yang ada dan menggantikan dokumen JSON baru untuk tags.
Menerima dua pemberitahuan. Operasi ini memberi tahu ketika kembar dimodifikasi. Untuk menerima notifikasi perubahan kembar perangkat, solusi IoT Anda perlu membuat rute dan menetapkan Sumber Data ke twinChangeEvents. Secara default, tidak ada rute seperti itu, sehingga tidak ada pemberitahuan kembar 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 membutuhkan audit dan pencatatan yang andal dari semua status perantara, Anda harus menggunakan pesan dari perangkat ke cloud. Untuk mempelajari lebih lanjut tentang properti dan badan yang dikembalikan dalam pesan pemberitahuan kembar, lihat Skema peristiwa nontelemetri.

Semua operasi sebelumnya mendukung Konkurensi optimis dan memerlukan izin ServiceConnect , seperti yang didefinisikan dalam Mengontrol akses ke IoT Hub.

Selain operasi ini, backend solusi dapat:

Kueri perangkat kembar menggunakan bahasa kueri IoT Hub seperti SQL.
Lakukan operasi pada set besar perangkat kembar menggunakan pekerjaan.

Operasi perangkat

Aplikasi perangkat beroperasi pada perangkat ganda menggunakan operasi atom berikut:

Ambil perangkat kembar. Operasi ini mengembalikan dokumen kembar perangkat (termasuk properti sistem yang diinginkan dan dilaporkan) untuk perangkat yang saat ini tersambung. (Tag tidak terlihat oleh aplikasi perangkat.)
Memperbarui sebagian properti yang dilaporkan. Operasi ini memungkinkan pembaruan parsial properti yang dilaporkan dari perangkat yang saat ini tersambung.
Amati properti yang diinginkan. Perangkat yang saat ini tersambung dapat memilih untuk diberi tahu tentang pembaruan properti yang diinginkan ketika mereka terjadi.

Semua operasi sebelumnya memerlukan izin DeviceConnect , seperti yang didefinisikan dalam Kontrol Akses ke IoT Hub.

SDK perangkat Azure IoT memudahkan penggunaan operasi sebelumnya dari banyak bahasa dan platform. Untuk informasi selengkapnya tentang detail primitif IoT Hub 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 up-to 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 salah satu karakter berikut sebagai bagian dari nama kunci: ()<>@,;:\"/?={}.
Nilai: Semua nilai dalam objek JSON dapat berupa jenis JSON berikut: boolean, angka, string, objek. Array juga didukung.
- Bilangan bulat dapat memiliki nilai minimum -4503599627370496 dan nilai maksimum 4503599627370495.
- Nilai string dikodekan 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 valid:

{
     ...
     "tags": {
         "one": {
             "two": {
                 "three": {
                     "four": {
                         "five": {
                             "six": {
                                 "seven": {
                                     "eight": {
                                         "nine": {
                                             "ten": {
                                                 "property": "value"
                                             }
                                         }
                                     }
                                 }
                             }
                         }
                     }
                 }
             }
         }
     },
     ...
}

Ukuran kembar perangkat

IoT Hub memberlakukan batas ukuran 8 KB pada nilai tags, dan batas ukuran 32 KB masing-masing pada nilai properties/desired dan properties/reported. Total ini tidak termasuk elemen baca-saja seperti $version dan $metadata/$lastUpdated.

Ukuran kembar dihitung sebagai berikut:

IoT Hub secara kumulatif menghitung dan menambahkan panjang kunci dan nilai setiap 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 yang dikodekan UTF8 dihitung dengan menghitung semua karakter, tidak termasuk karakter kontrol UNICODE (segmen C0 dan C1).
Nilai properti kompleks (objek tertanam) dihitung berdasarkan ukuran keseluruhan dari kunci properti dan nilai properti yang terdapat di dalamnya.

IoT Hub akan menolak semua operasi dengan kesalahan jika operasi tersebut meningkatkan ukuran dokumen tags, properties/desired, atau properties/reported melebihi batas yang ditetapkan.

Metadata kembar perangkat

IoT Hub mempertahankan tanda waktu pembaruan terakhir untuk setiap objek JSON di perangkat kembar yang diinginkan dan dilaporkan properti. Tanda waktu dalam UTC dan dikodekan dalam format YYYY-MM-DDTHH:MM:SS.mmmZ .

Contohnya:

{
    ...
    "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 daun 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.

Kembar perangkat memiliki properti etagETag, sesuai RFC7232, yang mewakili representasi JSON dari kembar perangkat tersebut. Anda dapat menggunakan etag properti dalam operasi pembaruan bersyarat dari ujung belakang solusi untuk memastikan konsistensi. Properti ini adalah satu-satunya opsi untuk memastikan konsistensi dalam operasi yang melibatkan tags kontainer.

Properti device twin yang diinginkan dan dilaporkan juga memiliki $version nilai yang dijamin bertambah. Demikian pula dengan ETag, Anda dapat menggunakan properti versi untuk memberlakukan konsistensi pembaruan. Misalnya, aplikasi perangkat untuk properti yang dilaporkan atau aplikasi back-end untuk properti yang diinginkan.

Versi juga berguna ketika agen pengamatan (seperti aplikasi perangkat yang mengamati properti yang diinginkan) harus mendamaikan balapan antara hasil operasi pengambilan dan pemberitahuan pembaruan. Bagian Alur koneksi ulang perangkat menyediakan informasi selengkapnya.

Alur koneksi ulang perangkat

IoT Hub tidak mempertahankan pemberitahuan pembaruan properti yang diinginkan untuk perangkat yang terputus. Oleh karena itu, perangkat yang terhubung harus mengambil dokumen semua properti yang diinginkan, dan berlangganan notifikasi pembaruan. Mengingat kemungkinan persaingan antara pemberitahuan pembaruan dan pengambilan penuh, alur berikut harus dipastikan:

Aplikasi perangkat tersambung ke hub IoT.
Aplikasi perangkat berlangganan pemberitahuan pembaruan properti yang diinginkan.
Aplikasi perangkat mengambil dokumen lengkap untuk properti yang diinginkan.

Aplikasi perangkat dapat mengabaikan semua pemberitahuan dengan $version kurang atau sama dengan versi dokumen lengkap yang diambil. Pendekatan ini dimungkinkan karena IoT Hub menjamin bahwa nomor versi selalu meningkat.

Langkah berikutnya

Untuk mencoba beberapa konsep yang dijelaskan dalam artikel ini, lihat artikel IoT Hub berikut ini:

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-03-30

Memahami dan menggunakan perangkat ganda di IoT Hub

Perangkat ganda

Contoh properti yang dilaporkan

Contoh properti yang diinginkan

Operasi back-end

Operasi perangkat

Format tag dan properti

Ukuran kembar perangkat

Metadata kembar perangkat

Konkurensi optimis

Alur koneksi ulang perangkat

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: