Memahami dan menggunakan modul ganda di IoT Hub

  • Artikel

Artikel ini mengasumsikan Anda telah membaca Pahami dan gunakan perangkat kembar di IoT Hub terlebih dahulu. Di Azure IoT Hub, pada setiap identitas perangkat, Anda dapat membuat hingga 50 identitas modul. Setiap identitas modul membuat kembaran modul secara implisit. Mirip dengan perangkat kembar, kembaran modul adalah dokumen JSON yang menyimpan informasi status modul termasuk metadata, konfigurasi, dan kondisi. Azure IoT Hub mempertahankan kembaran modul untuk setiap modul yang Anda sambungkan ke IoT Hub.

Di sisi perangkat, SDK perangkat IoT Hub memungkinkan Anda membuat modul di mana masing-masing modul membuka koneksi independen ke IoT Hub. Fungsionalitas ini memungkinkan Anda menggunakan namespace layanan terpisah untuk komponen yang berbeda di perangkat Anda. Misalnya, Anda memiliki mesin penjual otomatis yang memiliki tiga sensor berbeda. Setiap sensor dikendalikan oleh departemen yang berbeda di perusahaan Anda. Anda dapat membuat modul untuk setiap sensor. Dengan cara ini, setiap departemen hanya dapat mengirim pekerjaan atau metode langsung ke sensor yang mereka kontrol, menghindari konflik dan kesalahan pengguna.

Identitas modul dan kembar modul memberikan kemampuan yang sama seperti identitas perangkat dan kembar perangkat, tetapi pada granularitas yang lebih halus. Granularitas yang lebih halus ini memungkinkan perangkat yang mumpuni, seperti perangkat berbasis sistem operasi atau perangkat firmware yang mengelola beberapa komponen, untuk mengisolasi konfigurasi dan kondisi untuk masing-masing komponen tersebut. Modul identitas dan kembaran modul memberikan pemisahan manajemen permasalahan ketika bekerja dengan perangkat IoT yang memiliki komponen perangkat lunak modular. Kami bertujuan untuk mendukung semua fungsi kembar perangkat pada tingkat kembar modul dengan modul ketersediaan umum kembar.

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 kembaran modul: tag, properti yang diinginkan dan dilaporkan.
  • Operasi yang dapat dilakukan modul dan ujung belakang pada kembaran modul.

Lihat panduan komunikasi perangkat ke cloud untuk panduan tentang penggunaan properti yang dilaporkan, pesan perangkat ke cloud, atau unggahan file.

Lihat panduan komunikasi cloud-ke-perangkat untuk panduan tentang penggunaan properti yang diinginkan, metode langsung, atau pesan cloud-ke-perangkat.

Kembaran modul

Kembar modul menyimpan informasi terkait-modul sehingga:

  • Modul pada perangkat dan IoT Hub dapat menggunakannya untuk menyinkronkan kondisi dan konfigurasi modul.

  • Solusi back end solusi dapat menggunakan untuk mengkueri dan menargetkan operasi yang berjalan lama.

Siklus hidup kembar modul terkait dengan identitas modul yang sesuai. Kembaran modul secara implisit dibuat dan dihapus ketika identitas modul dibuat atau dihapus di IoT Hub.

Kembaran modul adalah dokumen JSON yang mencakup:

  • Tag. Bagian dari dokumen JSON yang dapat dibaca dan ditulis oleh back end solusi. Tag tidak terlihat oleh modul pada perangkat. Tag diatur untuk tujuan kueri.

  • Properti yang diinginkan. Digunakan bersama dengan properti yang dilaporkan untuk menyinkronkan konfigurasi atau kondisi modul. Back end solusi dapat mengatur properti yang diinginkan, dan aplikasi modul dapat membacanya. Aplikasi modul juga dapat menerima notifikasi perubahan properti yang diinginkan.

  • Properti yang dilaporkan. Digunakan bersama dengan properti yang diinginkan untuk menyinkronkan konfigurasi atau kondisi modul. Aplikasi modul dapat mengatur properti yang dilaporkan, dan back end solusi dapat membaca dan memintanya.

  • Properti identitas modul. Akar kembaran modul dokumen JSON berisi properti baca-saja dari identitas modul yang sesuai yang disimpan dalam registri identitas.

Architectural representation of device twin

Contoh berikut menunjukkan modul dokumen kembaran JSON:

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "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
        }
    }
}

Dalam objek root, terdapat properti identitas modul, dan objek kontainer untuk tags serta properti reported dan desired. properties Kontainer berisi beberapa elemen hanya-baca ($metadata dan $version) yang dijelaskan di bagian Metadata twin modul dan Konkurensi optimis.

Contoh properti yang dilaporkan

Dalam contoh sebelumnya, kembaran modul berisi properti batteryLevel yang dilaporkan oleh aplikasi modul. Properti ini memungkinkan untuk meminta dan mengoperasikan modul berdasarkan tingkat baterai yang terakhir yang dilaporkan. Contoh lainnya termasuk aplikasi modul yang melaporkan kemampuan modul 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 modul dalam bentuk urutan peristiwa bertanda waktu, seperti rangkaian waktu.

Contoh properti yang diinginkan

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

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

  2. Aplikasi modul segera diberitahu tentang perubahan jika modul tersambung. Jika tidak tersambung, aplikasi modul mengikuti alur sambungan ulang modul saat tersambung. Aplikasi modul 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. Back end solusi dapat melacak hasil operasi konfigurasi di banyak modul, dengan mengkueri kembaran modul.

Catatan

Cuplikan sebelumnya adalah contoh, yang dioptimalkan untuk keterbacaan, dari salah satu cara untuk menyandikan konfigurasi modul dan statusnya. IoT Hub tidak memaksakan skema tertentu untuk kembaran modul yang diinginkan dan melaporkan properti dalam kembaran modul.

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.

Operasi back-end

Back end solusi beroperasi pada kembaran modul menggunakan operasi atom berikut, diekspos melalui HTTPS:

  • Mengambil kembaran modul dengan ID. Operasi ini mengembalikan dokumen kembaran modul, termasuk tag dan properti sistem yang diinginkan dan dilaporkan.

  • Memperbarui sebagian kembaran modul. Operasi ini memungkinkan solusi back end untuk memperbarui sebagian tag atau properti yang diinginkan dalam kembaran modul. 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 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 ganda, lihat Skema peristiwa non-telemetri.

Semua operasi sebelumnya mendukung Konkurensi optimis dan memerlukan izin ServiceConnect, sebagaimana didefinisikan dalam artikel Kontrol Akses ke IoT Hub.

Selain operasi ini, back end solusi dapat meminta kembaran modul menggunakan bahasa kueri IoT Hub seperti SQL.

Operasi modul

Aplikasi modul beroperasi pada kembaran modul menggunakan operasi atom berikut:

  • Mengambil kembaran modul. Operasi ini mengembalikan dokumen ganda modul (termasuk properti sistem yang diinginkan dan dilaporkan) untuk modul yang tersambung saat ini.

  • Memperbarui sebagian properti yang dilaporkan. Operasi ini memungkinkan pembaruan parsial properti yang dilaporkan dari modul 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. Modul yang saat ini terhubung dapat memilih untuk mendapatkan pemberitahuan tentang pembaruan pada properti yang diinginkan ketika pembaruan tersebut terjadi. Modul menerima bentuk pembaruan yang sama (penggantian parsial atau penuh) yang dijalankan oleh back end solusi.

Semua operasi sebelumnya memerlukan izin ModuleConnect, seperti yang ditentukan dalam artikel Akses Kontrol ke IoT Hub.

SDK perangkat Azure IoT memudahkan penggunaan operasi sebelumnya dari banyak bahasa pemrogram dan platform.

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.

  • 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 kembaran modul

IoT Hub memberlakukan batas ukuran 8 KB pada nilai tags, dan batas ukuran 32 KB masing-masing pada nilai properties/desireddan 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 tersebut di atas batas.

Metadata kembaran modul

IoT Hub mempertahankan tanda waktu pembaruan terakhir untuk setiap objek JSON dalam modul yang diinginkan dan dilaporkan properti. 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": "5m",
                    "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.

Twin modul memiliki ETag (etag properti), sesuai RFC7232, yang mewakili representasi JSON twin. 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.

Modul twin yang diinginkan dan properti yang dilaporkan juga memiliki $version nilai yang dijamin bertambah secara bertahap. Demikian pula dengan ETag, versi dapat digunakan oleh pihak yang memperbarui untuk menegakkan konsistensi pembaruan. Misalnya, aplikasi modul untuk properti yang dilaporkan atau back end solusi untuk properti yang diinginkan.

Versi juga berguna ketika agen pengamat (seperti aplikasi modul yang mengamati properti yang diinginkan) harus menyelaraskan kecepatan antara hasil operasi pengambilan dan pemberitahuan pembaruan. Bagian Alur rekoneksi modul memberikan informasi lebih lanjut.

Aliran sambungan ulang modul

IoT Hub tidak mempertahankan pemberitahuan pembaruan properti yang diinginkan untuk modul yang terputus. Oleh karena itu, modul 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 modul tersambung ke IoT hub.
  2. Aplikasi modul berlangganan pemberitahuan pembaruan properti yang diinginkan.
  3. Aplikasi modul mengambil dokumen lengkap untuk properti yang diinginkan.

Aplikasi modul dapat mengabaikan semua pemberitahuan 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 tutorial IoT Hub berikut ini: