Mengelola kembar digital IoT Plug and Play
IoT Plug and Play mendukung operasi Mendapatkan kembaran digital dan Memperbarui kembaran digital untuk mengelola kembar digital. Anda dapat menggunakan REST API atau salah satu dari SDK layanan.
Memperbarui kembaran digital
Perangkat IoT Plug and Play mengimplementasikan model yang dijelaskan oleh Digital Twins Definition Language (DTDL). Pengembang solusi dapat menggunakan API Perbarui Kembar Digital untuk memperbarui status komponen dan properti kembar digital.
Perangkat IoT Plug and Play yang digunakan sebagai contoh dalam artikel ini mengimplementasikan model Pengontrol Suhu dengan komponen Thermostat.
Cuplikan berikut menunjukkan respons terhadap permintaan Dapatkan kembar digital yang diformat sebagai objek JSON. Untuk mempelajari selengkapnya tentang format kembar digital, lihat Memahami kembar digital IoT Plug and Play:
{
"$dtId": "sample-device",
"serialNumber": "alwinexlepaho8329",
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 20.4,
"$metadata": {
"targetTemperature": {
"desiredValue": 20.4,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
},
"$metadata": {
"$model": "dtmi:com:example:TemperatureController;1",
"serialNumber": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}
Kembar digital memungkinkan Anda memperbarui seluruh komponen atau properti menggunakan JSON Patch.
Misalnya, Anda dapat memperbarui targetTemperature properti sebagai berikut:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
}
]
Pembaruan sebelumnya menetapkan nilai properti yang diinginkan di tingkat komponen terkait $metadata seperti yang diperlihatkan dalam cuplikan berikut. IoT Hub memperbarui versi properti yang diinginkan:
"thermostat1": {
"targetTemperature": 20.4,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.4,
"desiredVersion": 5,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
}
}
}
Menambahkan, mengganti, atau menghapus komponen
Operasi tingkat komponen memerlukan penanda objek $metadata kosong di dalam nilai.
Operasi tambah atau ganti komponen menetapkan nilai yang diinginkan dari semua properti yang disediakan. Hal ini juga membersihkan nilai yang diinginkan untuk properti yang dapat ditulis yang tidak disediakan dengan pembaruan.
Menghapus komponen membersihkan nilai yang diinginkan dari semua properti yang dapat ditulis yang ada. Perangkat akhirnya menyinkronkan penghapusan ini dan berhenti melaporkan properti individual. Komponen tersebut kemudian dikeluarkan dari kembaran digital.
Sampel JSON Patch berikut menunjukkan cara menambahkan, mengganti, atau menghapus komponen:
[
{
"op": "add",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"anotherWritableProperty": 42,
"$metadata": {}
}
},
{
"op": "replace",
"path": "/thermostat1",
"value": {
"targetTemperature": 21.4,
"$metadata": {}
}
},
{
"op": "remove",
"path": "/thermostat2"
}
]
Menambahkan, mengganti, atau menghapus properti
Operasi tambah atau ganti menetapkan nilai properti yang diinginkan. Perangkat dapat menyinkronkan status dan melaporkan pembaruan nilai bersama dengan ack kode, versi, dan deskripsi.
Menghapus properti akan membersihkan nilai properti yang diinginkan jika sudah ditetapkan. Perangkat kemudian dapat berhenti melaporkan properti ini dan dihapus dari komponen. Jika properti ini adalah yang terakhir dalam komponen, maka komponen juga dihapus.
Contoh JSON Patch berikut menunjukkan cara menambahkan, mengganti, atau menghapus properti dalam komponen:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
Aturan untuk menetapkan nilai properti kembaran digital yang diinginkan
Nama
Nama komponen atau properti harus nama DTDL yang valid.
Karakter yang diperbolehkan adalah a-z, A-Z, 0-9 (bukan sebagai karakter pertama), dan garis bawah (bukan sebagai karakter pertama atau terakhir).
Nama panjangnya bisa 1-64 karakter.
Nilai properti
Nilai harus properti DTDL yang valid.
Semua jenis primitif didukung. Dalam jenis kompleks, enum, peta, dan objek didukung. Untuk mempelajari lebih lanjut, lihat Skema DTDL.
Properti tidak mendukung array atau skema kompleks apa pun dengan array.
Kedalaman maksimum lima tingkat didukung untuk objek yang kompleks.
Semua nama bidang dalam objek kompleks harus nama DTDL yang valid.
Semua kunci peta harus nama DTDL yang valid.
Memecahkan masalah pembaruan kesalahan API kembar digital
API kembar digital memberikan pesan kesalahan generik berikut:
ErrorCode:ArgumentInvalid;'{propertyName}' exists within the device twin and is not digital twin conformant property. Please refer to aka.ms/dtpatch to update this to be conformant.
Jika Anda melihat kesalahan ini, pastikan patch pembaruan mengikuti aturan untuk mengatur nilai properti kembar digital yang diinginkan.
Saat Anda memperbarui komponen, pastikan penanda objek kosong $metadata diset.
Pembaruan dapat gagal jika nilai yang dilaporkan perangkat tidak sesuai dengan konvensi IoT plug and play.
Langkah berikutnya
Sekarang setelah Anda mempelajari tentang digital twins, berikut adalah beberapa sumber daya lainnya: