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.

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

• 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 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:

• Aplikasi perangkat dan aplikasi 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 aplikasi back-end. Tag tidak terlihat oleh aplikasi perangkat.

• Properti yang diinginkan. Digunakan beserta 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 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 aplikasi back-end 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 connectionStateUpdatedTime dan generationId tidak 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

Dalam contoh sebelumnya, perangkat kembar berisi properti yang batteryLevel dilaporkan. 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.

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. Contohnya:

1. 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"
       },
       ...
   },
   

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

3. Aplikasi back-end melacak hasil operasi konfigurasi di banyak perangkat dengan mengkueri kembar perangkat.

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 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 diatur ke null akan dihapus. Contoh berikut membuat properti baru yang diinginkan dengan nilai {"newProperty": "newValue"}, menimpa nilai existingProperty yang ada dengan "otherNewValue", dan menghapus otherOldProperty. 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 sepenuhnya menimpa semua properti yang diinginkan yang ada dan menggantikan dokumen JSON baru untuk properties/desired.

• Mengganti tag. Operasi ini sepenuhnya menimpa semua tag yang ada dan menggantikan dokumen JSON baru untuk tags.

• Menerima pemberitahuan ganda. Operasi ini memberi tahu ketika kembar dimodifikasi. Untuk menerima pemberitahuan perubahan kembar perangkat, solusi IoT Anda perlu membuat rute dan untuk mengatur Sumber Data yang 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.

• Mengamati properti yang diinginkan. Perangkat yang tersambung saat ini dapat memilih untuk diberi tahu tentang pembaruan properti yang diinginkan saat pembaruan tersebut terjadi.

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:

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

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 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 properti etagETag , sesuai RFC7232, yang mewakili representasi JSON kembar. Anda dapat menggunakan properti etag dalam operasi pembaruan kondisional dari ujung belakang solusi untuk memastikan konsistensi. Properti ini adalah satu-satunya opsi untuk memastikan konsistensi dalam operasi yang melibatkan tags kontainer.

Properti perangkat kembar yang diinginkan dan dilaporkan tidak memiliki $version yang dijamin akan bertambah secara bertahap. 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 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:

1. Aplikasi perangkat tersambung ke IoT Hub.
2. Aplikasi perangkat berlangganan untuk pemberitahuan pembaruan properti yang diinginkan.
3. 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

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

• Tutorial: Mengonfigurasi perangkat Anda dengan properti kembar perangkat
• Cara menggunakan perangkat kembar