Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Topik ini menjelaskan pesan yang terkait dengan masing-masing dari tiga metode yang AWS IoT menyediakan untuk bekerja dengan bayangan. Metode-metode ini meliputi:
UPDATE
-
Membuat bayangan jika tidak ada, atau memperbarui konten bayangan yang ada dengan informasi status yang disediakan di badan pesan. AWS IoT merekam stempel waktu dengan setiap pembaruan untuk menunjukkan kapan status terakhir diperbarui. Ketika status bayangan berubah, AWS IoT kirim
/delta
pesan ke semua MQTT pelanggan dengan perbedaan antara statusdesired
danreported
status. Perangkat atau aplikasi yang menerima/delta
pesan dapat melakukan tindakan berdasarkan perbedaannya. Misalnya, perangkat dapat memperbarui statusnya ke status yang diinginkan, atau aplikasi dapat memperbarui UI untuk mencerminkan perubahan status perangkat. GET
-
Mengambil dokumen bayangan saat ini yang berisi status lengkap bayangan, termasuk metadata.
DELETE
-
Menghapus bayangan perangkat dan isinya.
Anda tidak dapat memulihkan dokumen bayangan perangkat yang dihapus, tetapi Anda dapat membuat bayangan perangkat baru dengan nama dokumen bayangan perangkat yang dihapus. Jika Anda membuat dokumen bayangan perangkat yang memiliki nama yang sama dengan yang dihapus dalam 48 jam terakhir, nomor versi dokumen bayangan perangkat baru akan mengikuti yang dihapus. Jika dokumen bayangan perangkat telah dihapus selama lebih dari 48 jam, nomor versi dokumen bayangan perangkat baru dengan nama yang sama adalah 0.
Dukungan protokol
AWS IoT mendukung MQTT
Meminta dan melaporkan status
Saat merancang solusi IoT Anda menggunakan AWS IoT dan bayangan, Anda harus menentukan aplikasi atau perangkat yang akan meminta perubahan dan yang akan menerapkannya. Biasanya, perangkat mengimplementasikan dan melaporkan perubahan kembali ke bayangan dan aplikasi serta layanan merespons dan meminta perubahan dalam bayangan. Solusi Anda mungkin berbeda, tetapi contoh dalam topik ini mengasumsikan bahwa aplikasi klien atau layanan meminta perubahan dalam bayangan dan perangkat melakukan perubahan dan melaporkannya kembali ke bayangan.
Memperbarui bayangan
Aplikasi atau layanan Anda dapat memperbarui status bayangan dengan menggunakan UpdateThingShadow API atau dengan memublikasikan ke /perbarui topik. Pembaruan hanya memengaruhi bidang yang ditentukan dalam permintaan.
Memperbarui bayangan saat klien meminta perubahan status
Ketika klien meminta perubahan status dalam bayangan dengan menggunakan MQTT protokol
-
Klien harus memiliki dokumen bayangan saat ini sehingga dapat mengidentifikasi properti yang akan diubah. Lihat tindakan /get untuk cara mendapatkan dokumen bayangan saat ini.
-
Klien berlangganan MQTT topik-topik ini:
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta -
$aws/things/
thingName
/shadow/name/shadowName
/update/documents
-
-
Klien menerbitkan topik
$aws/things/
permintaan dengan dokumen negara yang berisi status bayangan yang diinginkan. Hanya properti yang akan diubah yang perlu dimasukkan dalam dokumen. Ini adalah contoh dokumen dengan keadaan yang diinginkan.thingName
/shadow/name/shadowName
/update{ "state": { "desired": { "color": { "r": 10 }, "engine": "ON" } } }
-
Jika permintaan pembaruan valid, AWS IoT perbarui status yang diinginkan dalam bayangan dan menerbitkan pesan tentang topik ini:
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta
/update/accepted
Pesan berisi dokumen /dokumen status respons yang diterima bayangan, dan/update/delta
pesan berisi dokumen /dokumen status respons delta bayangan. -
-
Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan
$aws/things/
topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.thingName
/shadow/name/shadowName
/update/rejected
Ketika klien meminta perubahan status dalam bayangan dengan menggunakan API
-
Klien memanggil dokumen
UpdateThingShadow
API dengan Minta dokumen negara status sebagai badan pesannya. -
Jika permintaan itu valid, AWS IoT mengembalikan kode respons HTTP sukses dan dokumen /dokumen status respons yang diterima bayangan sebagai badan pesan responsnya.
AWS IoT juga akan mempublikasikan MQTT pesan ke
$aws/things/
topik dengan dokumen /dokumen status respons delta bayangan untuk perangkat atau klien apa pun yang berlangganan.thingName
/shadow/name/shadowName
/update/delta -
Jika permintaan tidak valid, AWS IoT mengembalikan kode respons HTTP kesalahan Dokumen respons kesalahan sebagai badan pesan responsnya.
Ketika perangkat menerima /desired
status pada /update/delta
topik, itu membuat perubahan yang diinginkan pada perangkat. Kemudian mengirim pesan ke /update
topik untuk melaporkan keadaan saat ini ke bayangan.
Memperbarui bayangan saat perangkat melaporkan statusnya saat ini
Saat perangkat melaporkan statusnya saat ini ke bayangan dengan menggunakan MQTT protokol
-
Perangkat harus berlangganan MQTT topik-topik ini sebelum memperbarui bayangan:
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta -
$aws/things/
thingName
/shadow/name/shadowName
/update/documents
-
-
Perangkat melaporkan statusnya saat ini dengan menerbitkan pesan ke
$aws/things/
topik yang melaporkan status saat ini, seperti dalam contoh ini.thingName
/shadow/name/shadowName
/update{ "state": { "reported" : { "color" : { "r" : 10 }, "engine" : "ON" } } }
-
Jika AWS IoT menerima pembaruan, ia menerbitkan pesan ke
$aws/things/
topik dengan dokumen /dokumen status respons yang diterima bayangan.thingName
/shadow/name/shadowName
/update/accepted -
Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan
$aws/things/
topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.thingName
/shadow/name/shadowName
/update/rejected
Saat perangkat melaporkan statusnya saat ini ke bayangan dengan menggunakan API
-
Perangkat memanggil dokumen
UpdateThingShadow
API dengan Minta dokumen negara status sebagai badan pesannya. -
Jika permintaan itu valid, AWS IoT perbarui bayangan dan mengembalikan kode respons HTTP sukses dengan dokumen /dokumen status respons yang diterima bayangan sebagai badan pesan responsnya.
AWS IoT juga akan mempublikasikan MQTT pesan ke
$aws/things/
topik dengan dokumen /dokumen status respons delta bayangan untuk perangkat atau klien apa pun yang berlangganan.thingName
/shadow/name/shadowName
/update/delta -
Jika permintaan tidak valid, AWS IoT mengembalikan kode respons HTTP kesalahan Dokumen respons kesalahan sebagai badan pesan responsnya.
Penguncian optimis
Anda dapat menggunakan versi dokumen negara untuk memastikan Anda memperbarui versi terbaru dari dokumen bayangan perangkat. Saat Anda menyediakan versi dengan permintaan pembaruan, layanan menolak permintaan dengan kode respons konflik HTTP 409 jika versi dokumen status saat ini tidak cocok dengan versi yang disediakan. Kode respons konflik juga dapat terjadi pada semua API yang memodifikasiThingShadow
, termasukDeleteThingShadow
.
Sebagai contoh:
Dokumen awal:
{
"state": {
"desired": {
"colors": [
"RED",
"GREEN",
"BLUE"
]
}
},
"version": 10
}
Pembaruan: (versi tidak cocok; permintaan ini akan ditolak)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
Hasil:
{
"code": 409,
"message": "Version conflict",
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
Pembaruan: (versi cocok; permintaan ini akan diterima)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
Keadaan akhir:
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
Mengambil dokumen bayangan
Anda dapat mengambil dokumen bayangan dengan menggunakan GetThingShadow API atau dengan berlangganan dan menerbitkan topik. /dapatkan Ini mengambil dokumen bayangan lengkap, termasuk delta apa pun antara status desired
danreported
. Prosedur untuk tugas ini sama apakah perangkat atau klien membuat permintaan.
Untuk mengambil dokumen bayangan dengan menggunakan protokol MQTT
-
Perangkat atau klien harus berlangganan MQTT topik ini sebelum memperbarui bayangan:
-
$aws/things/
thingName
/shadow/name/shadowName
/get/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/get/rejected
-
-
Perangkat atau klien menerbitkan pesan ke
$aws/things/
topik dengan badan pesan kosong.thingName
/shadow/name/shadowName
/get -
Jika permintaan berhasil, AWS IoT menerbitkan pesan ke
$aws/things/
topik dengan /dokumen status respons yang diterima di badan pesan.thingName
/shadow/name/shadowName
/get/accepted -
Jika permintaan tidak valid, AWS IoT menerbitkan pesan ke
$aws/things/
topik dengan Dokumen respons kesalahan di badan pesan.thingName
/shadow/name/shadowName
/get/rejected
Untuk mengambil dokumen bayangan dengan menggunakan REST API
-
Perangkat atau klien memanggil
GetThingShadow
API dengan badan pesan kosong. -
Jika permintaan valid, AWS IoT mengembalikan kode respons HTTP sukses dengan dokumen /dokumen status respons yang diterima bayangan sebagai badan pesan responsnya.
-
Jika permintaan tidak valid, AWS IoT mengembalikan kode respons HTTP kesalahan Dokumen respons kesalahan sebagai badan pesan responsnya.
Menghapus data bayangan
Ada dua cara untuk menghapus data bayangan: Anda dapat menghapus properti tertentu dalam dokumen bayangan dan Anda dapat menghapus bayangan sepenuhnya.
-
Untuk menghapus properti tertentu dari bayangan, perbarui bayangan; namun tetapkan nilai properti yang ingin Anda hapus
null
. Bidang dengan nilainull
dihapus dari dokumen bayangan. -
Untuk menghapus seluruh bayangan, gunakan DeleteThingShadow API atau publikasikan ke /delete topik.
catatan
Menghapus bayangan tidak mengatur ulang nomor versinya ke nol sekaligus. Ini akan diatur ulang ke nol setelah 48 jam.
Menghapus properti dari dokumen bayangan
Untuk menghapus properti dari bayangan dengan menggunakan MQTT protokol
-
Perangkat atau klien harus memiliki dokumen bayangan saat ini sehingga dapat mengidentifikasi properti yang akan diubah. Lihat Mengambil dokumen bayangan untuk informasi tentang cara mendapatkan dokumen bayangan saat ini.
-
Perangkat atau klien berlangganan MQTT topik ini:
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected
-
-
Perangkat atau klien menerbitkan topik
$aws/things/
permintaan dengan dokumen status yang menetapkanthingName
/shadow/name/shadowName
/updatenull
nilai ke properti bayangan yang akan dihapus. Hanya properti yang akan diubah yang perlu dimasukkan dalam dokumen. Ini adalah contoh dokumen yang menghapusengine
properti.{ "state": { "desired": { "engine": null } } }
-
Jika permintaan pembaruan valid, AWS IoT hapus properti yang ditentukan dalam bayangan dan menerbitkan pesan dengan
$aws/things/
topik dengan dokumen /dokumen status respons yang diterima bayangan di badan pesan.thingName
/shadow/name/shadowName
/update/accepted -
Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan
$aws/things/
topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.thingName
/shadow/name/shadowName
/update/rejected
Untuk menghapus properti dari bayangan dengan menggunakan REST API
-
Perangkat atau klien memanggil
UpdateThingShadow
API with a Minta dokumen negara yang memberikannull
nilai ke properti bayangan untuk dihapus. Sertakan hanya properti yang ingin Anda hapus dalam dokumen. Ini adalah contoh dokumen yang menghapusengine
properti.{ "state": { "desired": { "engine": null } } }
-
Jika permintaan itu valid, AWS IoT mengembalikan kode respons HTTP sukses dan dokumen /dokumen status respons yang diterima bayangan sebagai badan pesan responsnya.
-
Jika permintaan tidak valid, AWS IoT mengembalikan kode respons HTTP kesalahan Dokumen respons kesalahan sebagai badan pesan responsnya.
Menghapus bayangan
Berikut ini adalah beberapa pertimbangan saat menghapus bayangan perangkat.
-
Menyetel status bayangan perangkat ke
null
tidak menghapus bayangan. Versi bayangan akan bertambah pada pembaruan berikutnya. -
Menghapus bayangan perangkat tidak menghapus objek benda. Menghapus objek benda tidak menghapus bayangan perangkat yang sesuai.
-
Menghapus bayangan tidak mengatur ulang nomor versinya ke nol sekaligus. Ini akan diatur ulang ke nol setelah 48 jam.
Untuk menghapus bayangan dengan menggunakan MQTT protokol
-
Perangkat atau klien berlangganan MQTT topik ini:
-
$aws/things/
thingName
/shadow/name/shadowName
/delete/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/delete/rejected
-
-
Perangkat atau klien menerbitkan buffer pesan
$aws/things/
dengan kosong.thingName
/shadow/name/shadowName
/delete -
Jika permintaan hapus valid, AWS IoT hapus bayangan dan publikasikan pesan dengan
$aws/things/
topik dan dokumen /dokumen status respons yang diterima bayangan yang disingkat di badan pesan. Ini adalah contoh pesan hapus yang diterima:thingName
/shadow/name/shadowName
/delete/accepted{ "version": 4, "timestamp": 1591057529 }
-
Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan
$aws/things/
topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.thingName
/shadow/name/shadowName
/delete/rejected
Untuk menghapus bayangan dengan menggunakan REST API
-
Perangkat atau klien memanggil
DeleteThingShadow
API dengan buffer pesan kosong. -
Jika permintaan itu valid, AWS IoT mengembalikan kode respons HTTP sukses dan /dokumen status respons yang diterima dan dokumen /dokumen status respons yang diterima bayangan disingkat di badan pesan. Ini adalah contoh pesan hapus yang diterima:
{ "version": 4, "timestamp": 1591057529 }
-
Jika permintaan tidak valid, AWS IoT mengembalikan kode respons HTTP kesalahan Dokumen respons kesalahan sebagai badan pesan responsnya.