Memahami dan menggunakan modul ganda di IoT Hub

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.

Artikel ini mengasumsikan bahwa Anda membaca Memahami dan menggunakan perangkat kembar di IoT Hub terlebih dahulu.

Di sisi perangkat, kit pengembangan perangkat lunak perangkat IoT Hub (SDK) memungkinkan Anda membuat modul di mana masing-masing 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. Departemen yang berbeda di perusahaan Anda mengontrol setiap sensor. Anda dapat membuat modul untuk setiap sensor sehingga 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.

Artikel ini menjelaskan:

• Struktur kembaran modul: tag, properti yang diinginkan dan dilaporkan.
• Operasi yang dapat dilakukan aplikasi perangkat dan back end solusi pada modul kembar.

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 aplikasi back-end. Tag tidak terlihat oleh modul di perangkat. Tag diatur untuk tujuan kueri.

• Properti yang diinginkan. Digunakan bersama dengan properti yang dilaporkan untuk menyinkronkan konfigurasi atau kondisi modul. Aplikasi back-end 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 aplikasi back-end dapat membaca dan mengkuerinya.

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

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

Di tingkat atas, objek kembar modul berisi properti identitas modul dan objek kontainer untuk tags dan properti dan keduanya reporteddesired . 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, modul kembar berisi properti yang batteryLevel dilaporkan. 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.

Contoh properti yang diinginkan

Dalam contoh sebelumnya, telemetryConfig properti kembar modul yang diinginkan dan dilaporkan digunakan oleh aplikasi back-end dan aplikasi modul untuk menyinkronkan konfigurasi telemetri untuk modul 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 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. Aplikasi back-end dapat melacak hasil operasi konfigurasi di banyak modul, dengan mengkueri modul kembar.

Operasi back-end

Aplikasi back-end beroperasi pada modul kembar menggunakan operasi atom berikut, yang 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 memperbarui sebagian tag atau properti yang diinginkan dalam modul 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 modul, 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 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, aplikasi back-end dapat mengkueri modul kembar 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.

• Mengamati properti yang diinginkan. Modul yang saat ini terhubung dapat memilih untuk mendapatkan pemberitahuan tentang pembaruan pada properti yang diinginkan ketika pembaruan tersebut terjadi.

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/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 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. 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": "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 etag properti dalam operasi pembaruan bersyarat dari aplikasi back-end untuk memastikan konsistensi. Opsi ini memastikan konsistensi dalam operasi yang melibatkan tags kontainer.

Modul twin yang diinginkan dan properti yang dilaporkan juga memiliki $version nilai yang dijamin bertambah secara bertahap. Demikian pula dengan ETag, Anda dapat menggunakan nilai versi untuk memberlakukan konsistensi pembaruan. Misalnya, aplikasi modul untuk properti yang dilaporkan atau aplikasi back-end 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:

• Mulai dengan identitas modul IoT Hub dan kembaran modul menggunakan back end .NET dan perangkat .NET