Gunakan topik untuk meneruskan dan manage data device shadow - IoT Platform - Alibaba Cloud - IoT Platform

Data device shadow mengalir melalui topik MQTT yang telah ditentukan sebelumnya. Aliran data mencakup empat skenario: perangkat melaporkan status terkininya, aplikasi mengirim status yang diinginkan ke perangkat, perangkat mengambil konten shadow setelah kembali online, dan perangkat menghapus properti shadow.

Topik device shadow

Platform IoT menyediakan dua topik per perangkat untuk menangani aliran data device shadow.

/shadow/update/${YourProductKey}/${YourDeviceName}

Perangkat dan aplikasi menerbitkan pesan ke topik ini. Saat Platform IoT menerima pesan pada topik tersebut, shadow perangkat diperbarui dengan status dalam pesan tersebut.
/shadow/get/${YourProductKey}/${YourDeviceName}

Device shadow menerbitkan pembaruan status ke topik ini. Perangkat berlangganan ke topik ini untuk menerima pesan terbaru.

Contoh penggunaan

Contoh berikut menggunakan bola lampu untuk menggambarkan interaksi antara perangkat, device shadow-nya, dan sebuah aplikasi. Contoh ini mencakup keempat skenario aliran data: pelaporan status, perubahan status perangkat dari aplikasi, pengambilan konten shadow saat koneksi ulang, dan penghapusan properti shadow.

Dalam contoh ini, ProductKey adalah a1PbRCF**** dan DeviceName adalah lightbulb. Perangkat menerbitkan dan berlangganan ke kedua topik device shadow dengan Quality of Service (QoS) sebesar 1.

Perangkat melaporkan statusnya

Saat perangkat online, perangkat tersebut melaporkan status terkininya ke device shadow. Aplikasi kemudian dapat membaca status perangkat dari shadow kapan saja.

Gambar berikut menunjukkan aliran data.

Device reports status

Bola lampu online dan menerbitkan status terkininya ke topik /shadow/update/a1PbRCF****/lightbulb.

Format pesan JSON adalah:

{
    "method": "update", 
    "state": {
        "reported": {
            "color": "red"
        }
    }, 
    "version": 1
}

Tabel 1. Deskripsi parameter

Parameter	Deskripsi
method	Jenis operasi. Saat melakukan pembaruan, field method wajib diisi. Atur nilainya menjadi update.
state	Data status yang dikirim ke device shadow. Field reported wajib diisi. Nilainya ditulis ke bagian reported dalam dokumen shadow.
version	Versi permintaan. Device shadow hanya menerima pembaruan jika versi baru lebih besar daripada versi saat ini. Jika version diatur ke `-1`, seluruh data shadow dihapus dan versi diatur ulang ke `0`.

Device shadow memperbarui dokumen shadownya dengan status yang dilaporkan.

{
    "state": {
        "reported": {
            "color": "red"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1
}

Setelah memperbarui dokumen shadow, device shadow mengirim hasilnya ke topik /shadow/get/a1PbRCF****/lightbulb. Berlanggananlah ke topik ini sebelum menerbitkan ke topik update agar hasilnya diterima.

Jika pembaruan berhasil:

{
    "method": "reply", 
    "payload": {
        "status": "success", 
        "version": 1
    }, 
    "timestamp": 1469564576
}

Jika pembaruan gagal:

{
    "method": "reply", 
    "payload": {
        "status": "error", 
        "content": {
            "errorcode": "${errorcode}", 
            "errormessage": "${errormessage}"
        }
    }, 
    "timestamp": 1469564576
}

Tabel 2. Kode error

errorCode	errorMessage
400	Format JSON tidak valid.
401	Data shadow tidak memiliki field method.
402	Data shadow tidak memiliki field state.
403	Nilai field version bukan angka.
404	Data shadow tidak memiliki field reported.
405	Field reported kosong.
406	Nilai method tidak valid.
407	Konten shadow kosong.
408	Jumlah properti dalam field reported melebihi 128.
409	Konflik versi.
500	Error pemrosesan di sisi server.

Aplikasi mengubah status perangkat

Aplikasi memanggil API UpdateDeviceShadow untuk menulis status yang diinginkan ke device shadow. Shadow tersebut kemudian mendorong status yang diinginkan ke perangkat, yang lalu menerapkan perubahan tersebut dan melaporkan kembali status terbarunya.

Gambar berikut menunjukkan aliran data.

Application changes device status

Aplikasi memanggil API UpdateDeviceShadow untuk mengatur properti color menjadi green.

Nilai parameter ShadowMessage adalah:

{
    "method": "update", 
    "state": {
        "desired": {
            "color": "green"
        }
    }, 
    "version": 2
}

Device shadow menerima pembaruan dan menulis status yang diinginkan ke dokumen shadownya:

{
    "state": {
        "reported": {
            "color": "red"
        }, 
        "desired": {
            "color": "green"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }, 
        "desired": {
            "color": {
                "timestamp": 1469564576
            }
        }
    }, 
    "timestamp": 1469564576, 
    "version": 2
}

Device shadow menerbitkan dokumen yang diperbarui ke topik /shadow/get/a1PbRCF****/lightbulb dengan nilai method diatur ke control, memberi sinyal kepada perangkat untuk menerapkan perubahan yang diinginkan.

{
    "method": "control", 
    "payload": {
        "state": {
            "reported": {
                "color": "red"
            }, 
            "desired": {
                "color": "green"
            }
        }, 
        "metadata": {
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }, 
            "desired": {
                "color": {
                    "timestamp": 1469564576
                }
            }
        }
    }, 
    "version": 2, 
    "timestamp": 1469564576
}

Jika bola lampu sedang online dan telah berlangganan ke topik /shadow/get/a1PbRCF****/lightbulb, perangkat tersebut langsung menerima pesan tersebut.

Perangkat membaca field desired dan mengubah warna bola lampu menjadi hijau.

Setelah memperbarui statusnya, bola lampu melaporkan status terbaru ke Platform IoT.
```
{
    "method": "update", 
    "state": {
        "reported": {
            "color": "green"
        }
    }, 
    "version": 3
}
```
Catatan
Jika timestamp digunakan untuk menentukan bahwa perintah telah kedaluwarsa, Anda dapat memilih untuk tidak melakukan pembaruan.
Device shadow mengirim tanggapan ke perangkat pada topik /shadow/get/a1PbRCF****/lightbulb. Untuk format tanggapan, lihat Langkah 3 di bagian "Perangkat melaporkan statusnya".

Setelah status berhasil dilaporkan, perangkat dan device shadow membersihkan status yang diinginkan.

Perangkat menerbitkan pesan ke topik /shadow/update/a1PbRCF****/lightbulb untuk mengosongkan field desired:
```
{
    "method": "update", 
    "state": {
        "desired": "null"
    }, 
    "version": 4
}
```

Device shadow memperbarui dokumennya. Field desired dikosongkan dan dokumen shadow mencerminkan status akhir:

{
    "state": {
        "reported": {
            "color": "green"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564577
            }
        }, 
        "desired": {
            "timestamp": 1469564576
        }
    }, 
    "version": 4
}

Perangkat mendapatkan konten shadow

Jika perangkat offline saat aplikasi mengirim perintah, perangkat tersebut dapat mengambil konten shadow setelah terhubung kembali.

Gambar berikut menunjukkan aliran data.

Device retrieves shadow content

Setelah terhubung kembali, bola lampu menerbitkan permintaan get ke topik /shadow/update/a1PbRCF****/lightbulb untuk mengambil konten shadow terbaru.
```
{
    "method": "get"
}
```

Device shadow merespons dengan menerbitkan konten shadow terbaru ke topik /shadow/get/a1PbRCF****/lightbulb. Berlanggananlah ke topik ini sebelum mengirim permintaan get agar responsnya diterima.

{
    "method": "reply", 
    "payload": {
        "status": "success", 
        "state": {
            "reported": {
                "color": "red"
            }, 
            "desired": {
                "color": "green"
            }
        }, 
        "metadata": {
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }, 
            "desired": {
                "color": {
                    "timestamp": 1469564492
                }
            }
        }
    }, 
    "version": 2, 
    "timestamp": 1469564576
}

Perangkat menghapus properti shadow

Jika perangkat sudah memiliki status terbaru, perangkat tersebut dapat menghapus properti tertentu dari device shadow.

Gambar berikut menunjukkan aliran data.

Device deletes shadow properties

Untuk menghapus properti shadow, terbitkan ke topik /shadow/update/a1PbRCF****/lightbulb dengan nilai method diatur ke delete dan nilai properti target diatur ke null.

Menghapus properti tertentu dari shadow.

{
    "method": "delete", 
    "state": {
        "reported": {
            "color": "null", 
            "temperature": "null"
        }
    }, 
    "version": 1
}

Menghapus semua properti dari shadow.

{
    "method": "delete", 
    "state": {
        "reported": "null"
    }, 
    "version": 1
}