Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS IoT Layanan Device Shadow
Layanan AWS IoT Device Shadow menambahkan bayangan ke objek AWS IoT benda. Bayangan dapat membuat status perangkat tersedia untuk aplikasi dan layanan lain apakah perangkat terhubung AWS IoT atau tidak. AWS IoT benda benda dapat memiliki beberapa bayangan bernama sehingga solusi IoT Anda memiliki lebih banyak opsi untuk menghubungkan perangkat Anda ke aplikasi dan layanan lain.
AWS IoT benda benda tidak memiliki bayangan sampai mereka dibuat secara eksplisit. Bayangan dapat dibuat, diperbarui, dan dihapus dengan menggunakan AWS IoT konsol. [Perangkat, klien web lainnya, dan layanan dapat membuat, memperbarui, dan menghapus bayangan dengan menggunakan MQTT dan [topik MQTT yang dicadangkan, HTTP](reserved-topics.md#reserved-topics-shadow) menggunakan Device [Shadow REST](device-shadow-rest-api.md) API, dan for.AWS CLIAWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html) Karena bayangan disimpan oleh AWS di cloud, mereka dapat mengumpulkan dan melaporkan data status perangkat dari aplikasi dan layanan cloud lainnya apakah perangkat terhubung atau tidak.
## Menggunakan bayangan
Shadows menyediakan penyimpanan data yang andal untuk perangkat, aplikasi, dan layanan cloud lainnya untuk berbagi data. Mereka memungkinkan perangkat, aplikasi, dan layanan cloud lainnya untuk terhubung dan memutuskan sambungan tanpa kehilangan status perangkat.
Sementara perangkat, aplikasi, dan layanan cloud lainnya terhubung AWS IoT, mereka dapat mengakses dan mengontrol keadaan perangkat saat ini melalui bayangannya. Misalnya, aplikasi dapat meminta perubahan dalam status perangkat dengan memperbarui bayangan. AWS IoT menerbitkan pesan yang menunjukkan perubahan pada perangkat. Perangkat menerima pesan ini, memperbarui statusnya agar cocok, dan menerbitkan pesan dengan statusnya yang diperbarui. Layanan Device Shadow mencerminkan status yang diperbarui ini dalam bayangan yang sesuai. Aplikasi ini dapat berlangganan pembaruan bayangan atau dapat menanyakan bayangan untuk statusnya saat ini.
Saat perangkat offline, aplikasi masih dapat berkomunikasi dengan AWS IoT dan bayangan perangkat. Ketika perangkat terhubung kembali, ia menerima keadaan bayangannya saat ini sehingga dapat memperbarui statusnya agar sesuai dengan bayangannya, dan kemudian menerbitkan pesan dengan status yang diperbarui. Demikian juga, ketika aplikasi offline dan status perangkat berubah saat offline, perangkat terus memperbarui bayangan sehingga aplikasi dapat menanyakan bayangan untuk statusnya saat ini saat terhubung kembali.
Jika perangkat Anda sering offline dan Anda ingin mengonfigurasi perangkat Anda untuk menerima pesan delta setelah terhubung kembali, Anda dapat menggunakan fitur sesi persisten. Untuk informasi lebih lanjut tentang periode kedaluwarsa sesi persisten, lihat Periode [kedaluwarsa sesi persisten](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
### Memilih untuk menggunakan bayangan bernama atau tidak disebutkan namanya
Layanan Device Shadow mendukung bayangan bernama dan tidak disebutkan namanya, atau klasik. Objek benda dapat memiliki beberapa bayangan bernama, dan tidak lebih dari satu bayangan yang tidak disebutkan namanya. Objek benda juga dapat memiliki bayangan bernama cadangan, yang beroperasi mirip dengan bayangan bernama kecuali Anda tidak dapat memperbarui namanya. Untuk informasi selengkapnya, lihat [Cadangan bernama bayangan](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
Objek benda dapat memiliki bayangan bernama dan tidak disebutkan namanya secara bersamaan; namun, API yang digunakan untuk mengakses masing-masing sedikit berbeda, jadi mungkin lebih efisien untuk memutuskan jenis bayangan mana yang paling cocok untuk solusi Anda dan hanya menggunakan jenis itu. Untuk informasi selengkapnya tentang API untuk mengakses bayangan, lihat[Topik bayangan](reserved-topics.md#reserved-topics-shadow).
Dengan bayangan bernama, Anda dapat membuat tampilan yang berbeda dari keadaan objek benda. Misalnya, Anda dapat membagi objek benda dengan banyak properti menjadi bayangan dengan kelompok properti logis, masing-masing diidentifikasi dengan nama bayangannya. Anda juga dapat membatasi akses ke properti dengan mengelompokkannya ke dalam bayangan yang berbeda dan menggunakan kebijakan untuk mengontrol akses. Untuk informasi selengkapnya tentang kebijakan yang akan digunakan dengan bayangan perangkat, lihat [Tindakan, sumber daya, dan kunci kondisi untuk AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html) dan [AWS IoT Core kebijakan](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html).
Bayangan klasik yang tidak disebutkan namanya lebih sederhana, tetapi agak lebih terbatas daripada bayangan bernama. Setiap AWS IoT benda hanya dapat memiliki satu bayangan yang tidak disebutkan namanya. Jika Anda mengharapkan solusi IoT Anda memiliki kebutuhan terbatas untuk data bayangan, ini mungkin cara Anda ingin mulai menggunakan bayangan. Namun, jika Anda berpikir Anda mungkin ingin menambahkan bayangan tambahan di masa depan, pertimbangkan untuk menggunakan bayangan bernama sejak awal.
Pengindeksan armada mendukung bayangan yang tidak disebutkan namanya dan bayangan bernama secara berbeda. Untuk informasi selengkapnya, lihat [Mengelola pengindeksan armada](managing-fleet-index.md).
### Mengakses bayangan
Setiap bayangan memiliki [topik MQTT](reserved-topics.md#reserved-topics-shadow) yang dicadangkan dan [URL HTTP](device-shadow-rest-api.md) yang mendukung`get`,`update`, dan `delete` tindakan pada bayangan.
Bayangan menggunakan [dokumen bayangan JSON](device-shadow-document.md) untuk menyimpan dan mengambil data. Dokumen bayangan berisi properti state yang menjelaskan aspek-aspek status perangkat ini:
+ `desired`
Aplikasi menentukan status properti perangkat yang diinginkan dengan memperbarui `desired` objek.
+ `reported`
Perangkat melaporkan keadaan mereka saat ini di `reported` objek.
+ `delta`
AWS IoT melaporkan perbedaan antara keadaan yang diinginkan dan yang dilaporkan dalam `delta` objek.
Data yang disimpan dalam bayangan ditentukan oleh properti status badan pesan tindakan pembaruan. Tindakan pembaruan selanjutnya dapat memodifikasi nilai objek data yang ada, dan juga menambahkan dan menghapus kunci dan elemen lain dalam objek status bayangan. Untuk informasi selengkapnya tentang mengakses bayangan, lihat [Menggunakan bayangan di perangkat](device-shadow-comms-device.md) dan[Menggunakan bayangan di aplikasi dan layanan](device-shadow-comms-app.md).
**penting**
Izin untuk membuat permintaan pembaruan harus dibatasi pada aplikasi dan perangkat tepercaya. Ini mencegah properti status bayangan diubah secara tidak terduga; jika tidak, perangkat dan aplikasi yang menggunakan bayangan harus dirancang untuk mengharapkan kunci di properti status berubah.
### Menggunakan bayangan di perangkat, aplikasi, dan layanan cloud lainnya
Menggunakan bayangan di perangkat, aplikasi, dan layanan cloud lainnya membutuhkan konsistensi dan koordinasi di antara semua ini. Layanan AWS IoT Device Shadow menyimpan status bayangan, mengirim pesan saat status bayangan berubah, dan merespons pesan yang mengubah statusnya. Perangkat, aplikasi, dan layanan cloud lainnya dalam solusi IoT Anda harus mengelola statusnya dan menjaganya tetap konsisten dengan status bayangan perangkat.
Data status bayangan bersifat dinamis dan dapat diubah oleh perangkat, aplikasi, dan layanan cloud lainnya dengan izin untuk mengakses bayangan. Untuk alasan ini, penting untuk mempertimbangkan bagaimana setiap perangkat, aplikasi, dan layanan cloud lainnya akan berinteraksi dengan bayangan. Contoh:
+ *Perangkat* harus menulis hanya ke `reported` properti status bayangan saat mengkomunikasikan data status ke bayangan.
+ *Aplikasi dan layanan cloud lainnya* harus menulis hanya ke `desired` properti saat mengkomunikasikan permintaan perubahan status ke perangkat melalui bayangan.
**penting**
Data yang terkandung dalam objek data bayangan independen dari bayangan lain dan properti objek benda lain, seperti atribut benda dan konten pesan MQTT yang mungkin dipublikasikan oleh perangkat objek benda. Namun, perangkat dapat melaporkan data yang sama dalam topik dan bayangan MQTT yang berbeda jika perlu.
Perangkat yang mendukung banyak bayangan harus menjaga konsistensi data yang dilaporkan dalam bayangan yang berbeda.
### Pesanan pesan
Tidak ada jaminan bahwa pesan dari AWS IoT layanan akan tiba di perangkat dalam urutan tertentu. Skenario berikut menunjukkan apa yang terjadi dalam kasus ini.
Dokumen negara awal:
```
{
"state": {
"reported": {
"color": "blue"
}
},
"version": 9,
"timestamp": 123456776
}
```
Pembaruan 1:
```
{
"state": {
"desired": {
"color": "RED"
}
},
"version": 10,
"timestamp": 123456777
}
```
Perbarui 2:
```
{
"state": {
"desired": {
"color": "GREEN"
}
},
"version": 11,
"timestamp": 123456778
}
```
Dokumen negara bagian akhir:
```
{
"state": {
"reported": {
"color": "GREEN"
}
},
"version": 12,
"timestamp": 123456779
}
```
Ini menghasilkan dua pesan delta:
```
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
```
```
{
"state": {
"color": "GREEN"
},
"version": 12,
"timestamp": 123456779
}
```
Perangkat mungkin menerima pesan-pesan ini rusak. Karena status dalam pesan ini bersifat kumulatif, perangkat dapat dengan aman membuang pesan apa pun yang berisi nomor versi yang lebih lama dari yang dilacaknya. Jika perangkat menerima delta untuk versi 12 sebelum versi 11, perangkat dapat dengan aman membuang pesan versi 11.
### Pangkas pesan bayangan
Untuk mengurangi ukuran pesan bayangan yang dikirim ke perangkat Anda, tentukan aturan yang hanya memilih bidang yang dibutuhkan perangkat Anda, lalu memublikasikan kembali pesan pada topik MQTT yang didengarkan perangkat Anda.
Aturan ditentukan dalam JSON dan akan terlihat seperti berikut:
```
{
"sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'",
"ruleDisabled": false,
"actions": [
{
"republish": {
"topic": "${topic(3)}/delta",
"roleArn": "arn:aws:iam:123456789012:role/my-iot-role"
}
}
]
}
```
Pernyataan SELECT menentukan bidang mana dari pesan yang akan dipublikasikan ulang ke topik yang ditentukan. Kartu liar “\$1” digunakan untuk mencocokkan semua nama bayangan. Aturan menetapkan bahwa semua pesan yang cocok harus dipublikasikan ulang ke topik yang ditentukan. Dalam hal ini, `"topic()"` fungsi ini digunakan untuk menentukan topik yang akan diterbitkan ulang. `topic(3)`mengevaluasi nama benda dalam topik asli. Untuk informasi selengkapnya tentang membuat aturan, lihat[Aturan untuk AWS IoT](iot-rules.md).
# Menggunakan bayangan di perangkat
Bagian ini menjelaskan komunikasi perangkat dengan bayangan menggunakan pesan MQTT, metode yang disukai perangkat untuk berkomunikasi dengan layanan AWS IoT Device Shadow.
Komunikasi bayangan meniru request/response model menggunakan model komunikasi terbitkan/berlangganan MQTT. Setiap tindakan bayangan terdiri dari topik permintaan, topik respons yang berhasil (`accepted`), dan topik respons kesalahan (`rejected`).
Jika Anda ingin aplikasi dan layanan dapat menentukan apakah perangkat terhubung, lihat[Mendeteksi jika perangkat terhubung](device-shadow-comms-app.md#thing-connection).
**penting**
Karena MQTT menggunakan model publish/subscribe komunikasi, Anda harus berlangganan topik respons *sebelum* mempublikasikan topik permintaan. Jika tidak, Anda mungkin tidak menerima tanggapan atas permintaan yang Anda publikasikan.
Jika Anda menggunakan [AWS IoT Device SDK](iot-sdks.md)untuk memanggil layanan Device Shadow APIs, ini ditangani untuk Anda.
Contoh di bagian ini menggunakan bentuk singkat dari topik di mana *ShadowTopicPrefix* dapat merujuk ke bayangan bernama atau tidak disebutkan namanya, seperti yang dijelaskan dalam tabel ini.
Bayangan dapat dinamai atau tidak disebutkan namanya (klasik). Topik yang digunakan oleh masing-masing hanya berbeda dalam awalan topik. Tabel ini menunjukkan awalan topik yang digunakan oleh setiap jenis bayangan.
| Nilai *ShadowTopicPrefix* | Jenis bayangan |
| --- | --- |
| \$1aws/things/thingName/shadow | Bayangan tanpa nama (klasik) |
| \$1aws/things/thingName/shadow/name/shadowName | Bernama bayangan |
**penting**
Pastikan penggunaan bayangan aplikasi atau layanan Anda konsisten dan didukung oleh implementasi yang sesuai di perangkat Anda. Misalnya, pertimbangkan bagaimana bayangan dibuat, diperbarui, dan dihapus. Pertimbangkan juga bagaimana pembaruan ditangani di perangkat dan aplikasi atau layanan yang mengakses perangkat melalui bayangan. Desain Anda harus jelas tentang bagaimana status perangkat diperbarui dan dilaporkan serta bagaimana aplikasi dan layanan Anda berinteraksi dengan perangkat dan bayangannya.
Untuk membuat topik lengkap, pilih jenis bayangan yang ingin Anda rujuk, ganti, dan `shadowName` jika berlaku`thingName`, dengan nilai yang sesuai, lalu tambahkan dengan rintisan topik seperti yang ditunjukkan pada tabel berikut. `ShadowTopicPrefix` Ingatlah bahwa topik peka huruf besar/kecil.
Lihat [Topik bayangan](reserved-topics.md#reserved-topics-shadow) untuk informasi lebih lanjut tentang topik yang dicadangkan untuk bayangan.
## Menginisialisasi perangkat pada koneksi pertama ke AWS IoT
Setelah perangkat mendaftar AWS IoT, perangkat harus berlangganan pesan MQTT ini untuk bayangan yang didukungnya.
| Topik | Arti | Tindakan yang harus dilakukan perangkat saat topik ini diterima |
| --- | --- | --- |
| `ShadowTopicPrefix/delete/accepted` | `delete`Permintaan itu diterima dan AWS IoT menghapus bayangan. | Tindakan yang diperlukan untuk mengakomodasi bayangan yang dihapus, seperti berhenti menerbitkan pembaruan. |
| `ShadowTopicPrefix/delete/rejected` | `delete`Permintaan ditolak oleh AWS IoT dan bayangan tidak dihapus. Badan pesan berisi informasi kesalahan. | Menanggapi pesan kesalahan di badan pesan. |
| `ShadowTopicPrefix/get/accepted` | `get`Permintaan diterima oleh AWS IoT, dan badan pesan berisi dokumen bayangan saat ini. | Tindakan yang diperlukan untuk memproses dokumen negara di badan pesan. |
| `ShadowTopicPrefix/get/rejected` | `get`Permintaan ditolak oleh AWS IoT, dan badan pesan berisi informasi kesalahan. | Menanggapi pesan kesalahan di badan pesan. |
| `ShadowTopicPrefix/update/accepted` | `update`Permintaan diterima oleh AWS IoT, dan badan pesan berisi dokumen bayangan saat ini. | Konfirmasikan data yang diperbarui di badan pesan cocok dengan status perangkat. |
| `ShadowTopicPrefix/update/rejected` | `update`Permintaan ditolak oleh AWS IoT, dan badan pesan berisi informasi kesalahan. | Menanggapi pesan kesalahan di badan pesan. |
| `ShadowTopicPrefix/update/delta` | Dokumen bayangan diperbarui oleh permintaan ke AWS IoT, dan badan pesan berisi perubahan yang diminta. | Perbarui status perangkat agar sesuai dengan status yang diinginkan di badan pesan. |
| `ShadowTopicPrefix/update/documents` | Pembaruan bayangan baru-baru ini selesai, dan badan pesan berisi dokumen bayangan saat ini. | Konfirmasikan status yang diperbarui di badan pesan cocok dengan status perangkat. |
Setelah berlangganan pesan di tabel sebelumnya untuk setiap bayangan, perangkat harus menguji untuk melihat apakah bayangan yang didukungnya telah dibuat dengan menerbitkan `/get` topik ke setiap bayangan. Jika `/get/accepted` pesan diterima, badan pesan berisi dokumen bayangan, yang dapat digunakan perangkat untuk menginisialisasi statusnya. Jika `/get/rejected` pesan diterima, bayangan harus dibuat dengan menerbitkan `/update` pesan dengan status perangkat saat ini.
Misalnya, Anda memiliki sesuatu `My_IoT_Thing` yang tidak memiliki bayangan klasik atau bernama. Jika Anda sekarang mempublikasikan `/get` permintaan pada topik yang dicadangkan`$aws/things/My_IoT_Thing/shadow/get`, itu mengembalikan kesalahan pada `$aws/things/My_IoT_Thing/shadow/get/rejected` topik karena benda tersebut tidak memiliki bayangan. Untuk mengatasi kesalahan ini, pertama-tama publikasikan `/update` pesan menggunakan `$aws/things/My_IoT_Thing/shadow/update` topik dengan status perangkat saat ini seperti payload berikut.
```
{
"state": {
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
}
```
Bayangan klasik sekarang dibuat untuk benda itu dan pesan dipublikasikan ke `$aws/things/My_IoT_Thing/shadow/update/accepted` topik. Jika Anda memublikasikan ke topik`$aws/things/My_IoT_Thing/shadow/get`, ia mengembalikan respons ke `$aws/things/My_IoT_Thing/shadow/get/accepted` topik dengan status perangkat.
Untuk bayangan bernama, Anda harus terlebih dahulu membuat bayangan bernama atau mempublikasikan pembaruan dengan nama bayangan sebelum menggunakan permintaan get. Misalnya, untuk membuat bayangan bernama`namedShadow1`, pertama-tama publikasikan informasi status perangkat ke topik`$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update`. Untuk mengambil informasi status, gunakan `/get` permintaan untuk bayangan bernama,`$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get`.
## Memproses pesan saat perangkat terhubung AWS IoT
Saat perangkat terhubung AWS IoT, perangkat dapat menerima pesan **/update/delta** dan harus menjaga status perangkat tetap sesuai dengan perubahan bayangannya dengan:
1. Membaca semua pesan **/update/delta** yang diterima dan menyinkronkan status perangkat agar sesuai.
1. Menerbitkan pesan **/update** dengan badan `reported` pesan yang memiliki status perangkat saat ini, setiap kali status perangkat berubah.
Saat perangkat terhubung, perangkat harus mempublikasikan pesan-pesan ini saat ditunjukkan.
| Indikasi | Topik | Payload |
| --- | --- | --- |
| Status perangkat telah berubah. | `ShadowTopicPrefix/update` | Dokumen bayangan dengan `reported` properti. |
| Perangkat mungkin tidak disinkronkan dengan bayangan. | `ShadowTopicPrefix/get` | (kosong) |
| Tindakan pada perangkat menunjukkan bahwa bayangan tidak akan lagi didukung oleh perangkat, seperti saat perangkat dilepas atau diganti. | `ShadowTopicPrefix/delete` | (kosong) |
## Memproses pesan saat perangkat tersambung kembali AWS IoT
Ketika perangkat dengan satu atau lebih bayangan terhubung AWS IoT, itu harus menyinkronkan statusnya dengan semua bayangan yang didukungnya dengan:
1. Membaca semua pesan **/update/delta** yang diterima dan menyinkronkan status perangkat agar sesuai.
1. Menerbitkan pesan **/update** dengan badan `reported` pesan yang memiliki status perangkat saat ini.
# Menggunakan bayangan di aplikasi dan layanan
Bagian ini menjelaskan cara aplikasi atau layanan berinteraksi dengan layanan AWS IoT Device Shadow. Contoh ini mengasumsikan aplikasi atau layanan hanya berinteraksi dengan bayangan dan, melalui bayangan, perangkat. Contoh ini tidak menyertakan tindakan manajemen apa pun, seperti membuat atau menghapus bayangan.
Contoh ini menggunakan REST API layanan AWS IoT Device Shadow untuk berinteraksi dengan bayangan. Berbeda dengan contoh yang digunakan di[Menggunakan bayangan di perangkat](device-shadow-comms-device.md), yang menggunakan model publish/subscribe communications model, this example uses the request/response komunikasi dari REST API. Ini berarti aplikasi atau layanan harus membuat permintaan sebelum dapat menerima tanggapan dari AWS IoT. Kerugian dari model ini, bagaimanapun, adalah tidak mendukung notifikasi. Jika aplikasi atau layanan Anda memerlukan pemberitahuan perubahan status perangkat secara tepat waktu, pertimbangkan protokol MQTT atau MQTT melalui WSS, yang mendukung model komunikasi, seperti yang dijelaskan dalam. publish/subscribe [Menggunakan bayangan di perangkat](device-shadow-comms-device.md)
**penting**
Pastikan penggunaan bayangan aplikasi atau layanan Anda konsisten dan didukung oleh implementasi yang sesuai di perangkat Anda. Pertimbangkan, misalnya, bagaimana bayangan dibuat, diperbarui, dan dihapus, dan bagaimana pembaruan ditangani di perangkat dan aplikasi atau layanan yang mengakses bayangan. Desain Anda harus secara jelas menentukan bagaimana status perangkat diperbarui dan dilaporkan, dan bagaimana aplikasi dan layanan Anda berinteraksi dengan perangkat dan bayangannya.
URL REST API untuk bayangan bernama adalah:
```
https://endpoint/things/thingName/shadow?name=shadowName
```
dan untuk bayangan yang tidak disebutkan namanya:
```
https://endpoint/things/thingName/shadow
```
di mana:
titik akhir
Titik akhir yang dikembalikan oleh perintah CLI:
```
aws iot describe-endpoint --endpoint-type IOT:Data-ATS
```
thingName
Nama benda benda yang menjadi milik bayangan
shadowName
Nama bayangan bernama. Parameter ini tidak digunakan dengan bayangan yang tidak disebutkan namanya.
## Menginisialisasi aplikasi atau layanan pada koneksi ke AWS IoT
Ketika aplikasi pertama kali terhubung AWS IoT, itu harus mengirim permintaan HTTP GET ke bayangan URLs yang digunakannya untuk mendapatkan status bayangan saat ini yang digunakannya. Ini memungkinkannya untuk menyinkronkan aplikasi atau layanan ke bayangan.
## Status pemrosesan berubah saat aplikasi atau layanan terhubung AWS IoT
Saat aplikasi atau layanan terhubung AWS IoT, aplikasi dapat menanyakan status saat ini secara berkala dengan mengirimkan permintaan HTTP GET pada bayangan URLs yang digunakannya.
Saat pengguna akhir berinteraksi dengan aplikasi atau layanan untuk mengubah status perangkat, aplikasi atau layanan dapat mengirim permintaan HTTP POST ke bayangan yang digunakannya untuk memperbarui `desired` status bayangan. URLs Permintaan ini mengembalikan perubahan yang diterima, tetapi Anda mungkin harus melakukan polling bayangan dengan membuat permintaan HTTP GET hingga perangkat memperbarui bayangan dengan status barunya.
## Mendeteksi jika perangkat terhubung
Untuk menentukan apakah perangkat saat ini terhubung, sertakan `connected` properti dalam dokumen bayangan dan gunakan pesan MQTT Last Will and Testament (LWT) untuk menyetel `connected` properti `false` jika perangkat terputus karena kesalahan.
**catatan**
Pesan MQTT LWT yang dikirim ke topik yang AWS IoT dipesan (topik yang dimulai dengan \$1) diabaikan oleh layanan Device Shadow. AWS IoT Namun, mereka diproses oleh klien berlangganan dan oleh mesin AWS IoT aturan, jadi Anda perlu membuat pesan LWT yang dikirim ke topik yang tidak dipesan dan aturan yang menerbitkan kembali pesan MQTT LWT sebagai pesan pembaruan bayangan ke topik pembaruan bayangan yang dicadangkan,. `ShadowTopicPrefix/update`
**Untuk mengirim pesan LWT ke layanan Device Shadow**
1. Buat aturan yang menerbitkan kembali pesan MQTT LWT pada topik yang dicadangkan. Contoh berikut adalah aturan yang mendengarkan pesan tentang `my/things/myLightBulb/update` topik tersebut dan menerbitkannya kembali. `$aws/things/myLightBulb/shadow/update`
```
{
"rule": {
"ruleDisabled": false,
"sql": "SELECT * FROM 'my/things/myLightBulb/update'",
"description": "Turn my/things/ into $aws/things/",
"actions": [
{
"republish": {
"topic": "$$aws/things/myLightBulb/shadow/update",
"roleArn": "arn:aws:iam:123456789012:role/aws_iot_republish"
}
}
]
}
}
```
1. Saat perangkat terhubung AWS IoT, perangkat akan mendaftarkan pesan LWT ke topik yang tidak dicadangkan agar aturan penerbitan ulang dapat dikenali. Dalam contoh ini, topik itu `my/things/myLightBulb/update` dan menetapkan properti yang terhubung ke`false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Setelah terhubung, perangkat menerbitkan pesan pada topik pembaruan bayangannya,`$aws/things/myLightBulb/shadow/update`, untuk melaporkan statusnya saat ini, yang mencakup pengaturan `connected` propertinya`true`.
```
{
"state": {
"reported": {
"connected":"true"
}
}
}
```
1. Sebelum perangkat terputus dengan anggun, ia menerbitkan pesan tentang topik pembaruan bayangannya,`$aws/things/myLightBulb/shadow/update`, untuk melaporkan status terbarunya, yang mencakup pengaturan propertinya. `connected` `false`
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Jika perangkat terputus karena kesalahan, broker AWS IoT pesan menerbitkan pesan LWT perangkat atas nama perangkat. Aturan republish mendeteksi pesan ini dan menerbitkan pesan pembaruan bayangan untuk memperbarui `connected` properti bayangan perangkat.
**catatan**
Karena sifat asinkron dari pemrosesan pemutusan sambungan, pesan LWT tidak dijamin akan dikirim secara berurutan selama penyambungan ulang. Kami menyarankan Anda menggunakan [peristiwa siklus hidup](life-cycle-events.md) untuk meningkatkan akurasi deteksi status konektivitas, karena peristiwa ini menyediakan atribut untuk mengelola out-of-order peristiwa.
# Simulasi komunikasi layanan Device Shadow
Topik ini menunjukkan bagaimana layanan Device Shadow bertindak sebagai perantara dan memungkinkan perangkat dan aplikasi menggunakan bayangan untuk memperbarui, menyimpan, dan mengambil status perangkat.
Untuk mendemonstrasikan interaksi yang dijelaskan dalam topik ini, dan untuk menjelajahinya lebih lanjut, Anda memerlukan Akun AWS dan sistem tempat Anda dapat menjalankannya AWS CLI. Jika Anda tidak memilikinya, Anda masih dapat melihat interaksi dalam contoh kode.
Dalam contoh ini, AWS IoT konsol mewakili perangkat. AWS CLI Ini mewakili aplikasi atau layanan yang mengakses perangkat melalui bayangan. AWS CLI Antarmukanya sangat mirip dengan API yang mungkin digunakan aplikasi untuk berkomunikasi AWS IoT. Perangkat dalam contoh ini adalah bola lampu pintar dan aplikasi menampilkan status bola lampu dan dapat mengubah status bola lampu.
## Menyiapkan simulasi
Prosedur ini menginisialisasi simulasi dengan membuka [AWS IoT konsol](https://console.aws.amazon.com/iot/home), yang mensimulasikan perangkat Anda, dan jendela baris perintah yang mensimulasikan aplikasi Anda.
**Untuk mengatur lingkungan simulasi Anda**
1. Anda akan perlu Akun AWS untuk menjalankan contoh dari topik ini sendiri. Jika Anda tidak memiliki Akun AWS, buat satu, seperti yang dijelaskan dalam[Mengatur Akun AWS](setting-up.md).
1. Buka [AWS IoT konsol](https://console.aws.amazon.com/iot/home), dan di menu sebelah kiri, pilih **Uji** untuk membuka klien **MQTT**.
1. Di jendela lain, buka jendela terminal pada sistem yang telah AWS CLI diinstal di atasnya.
Anda harus membuka dua jendela: satu dengan AWS IoT konsol di halaman **Uji**, dan satu dengan prompt baris perintah.
## Inisialisasi perangkat
Dalam simulasi ini, kita akan bekerja dengan benda bernama objek,, dan bayangannya bernama *mySimulatedThing*, *SimShadow1*.
**Buat objek benda dan kebijakan IoT-nya**
Untuk membuat objek benda, di **AWS IoT Konsol**:
1. Pilih **Kelola** dan kemudian pilih **Things**.
1. Klik tombol **Create** jika hal-hal tercantum jika tidak, klik **Daftarkan satu hal** untuk membuat satu AWS IoT hal.
1. Masukkan nama`mySimulatedThing`, biarkan pengaturan lain menjadi default, lalu klik **Berikutnya**.
1. Gunakan pembuatan sertifikat sekali klik untuk menghasilkan sertifikat yang akan mengautentikasi koneksi perangkat. AWS IoT Klik **Aktifkan** untuk mengaktifkan sertifikat.
1. Anda dapat melampirkan kebijakan `My_IoT_Policy` yang akan memberikan izin perangkat untuk mempublikasikan dan berlangganan topik yang dicadangkan MQTT. Untuk langkah-langkah lebih rinci tentang cara membuat AWS IoT sesuatu dan cara membuat kebijakan ini, lihat[Buat objek benda](create-iot-resources.md#create-aws-thing).
**Buat bayangan bernama untuk objek benda**
Anda dapat membuat bayangan bernama untuk sesuatu dengan menerbitkan permintaan pembaruan ke topik `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` seperti yang dijelaskan di bawah ini.
Atau, untuk membuat bayangan bernama:
1. Di **AWS IoT Console**, pilih objek benda Anda dalam daftar hal-hal yang ditampilkan dan kemudian pilih **Shadows**.
1. Pilih **Tambahkan bayangan**, masukkan nama`simShadow1`, lalu pilih **Buat** untuk menambahkan bayangan bernama.
**Berlangganan dan publikasikan ke topik MQTT yang dipesan**
Di konsol, berlangganan topik bayangan MQTT yang dipesan. Topik-topik ini adalah tanggapan terhadap `get``update`,, dan `delete` tindakan sehingga perangkat Anda akan siap menerima tanggapan setelah menerbitkan tindakan.
****Untuk berlangganan topik MQTT di klien MQTT****
1. Di **klien MQTT**, pilih **Berlangganan topik**.
1. Masukkan`get`,`update`, dan `delete` topik untuk berlangganan. Salin satu topik pada satu waktu dari daftar berikut, tempelkan di bidang **Filter topik**, lalu klik **Berlangganan**. Anda akan melihat topik muncul di bawah **Langganan**.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/documents`
Pada titik ini, perangkat simulasi Anda siap menerima topik saat dipublikasikan oleh AWS IoT.
****Untuk mempublikasikan ke topik MQTT di klien MQTT****
Setelah perangkat menginisialisasi dirinya sendiri dan berlangganan topik respons, perangkat harus meminta bayangan yang didukungnya. Simulasi ini hanya mendukung satu bayangan, bayangan yang mendukung objek benda bernama, bernama *mySimulatedThing*, *SimShadow1*.
**Untuk mendapatkan status bayangan saat ini dari klien **MQTT****
1. Di **klien MQTT**, pilih **Publikasikan ke topik**.
1. Di bawah **Publikasikan**, masukkan topik berikut dan hapus konten apa pun dari jendela isi pesan di bawah tempat Anda memasukkan topik yang akan didapatkan. Anda kemudian dapat memilih **Publikasikan ke topik** untuk mempublikasikan permintaan. `$aws/things/mySimulatedThing/shadow/name/simShadow1/get`.
Jika Anda belum membuat bayangan bernama`simShadow1`, Anda menerima pesan dalam `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected` topik dan `code` adalah`404`, seperti dalam contoh ini sebagai bayangan belum dibuat, jadi kita akan membuatnya berikutnya.
```
{
"code": 404,
"message": "No shadow exists with name: 'simShadow1'"
}
```
**Untuk membuat bayangan dengan status perangkat saat ini**
1. Di **klien MQTT**, pilih **Publikasikan ke topik dan masukkan topik ini**:
```
$aws/things/mySimulatedThing/shadow/name/simShadow1/update
```
1. Di jendela isi pesan di bawah tempat Anda memasukkan topik, masukkan dokumen bayangan ini untuk menunjukkan perangkat melaporkan ID dan warnanya saat ini dalam nilai RGB. Pilih **Publikasikan** untuk mempublikasikan permintaan.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Jika Anda menerima pesan dalam topik:
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`: Ini berarti bayangan telah dibuat dan badan pesan berisi dokumen bayangan saat ini.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`: Tinjau kesalahan di badan pesan.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`: Bayangan sudah ada dan badan pesan memiliki status bayangan saat ini, seperti dalam contoh ini. Dengan ini, Anda dapat mengatur perangkat Anda atau mengonfirmasi bahwa itu cocok dengan status bayangan.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591140517,
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
## Kirim pembaruan dari aplikasi
Bagian ini menggunakan AWS CLI untuk menunjukkan bagaimana aplikasi dapat berinteraksi dengan bayangan.
**Untuk mendapatkan status bayangan saat ini menggunakan AWS CLI**
Dari baris perintah, masukkan perintah ini.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Pada platform Windows, Anda dapat menggunakan `con` sebagai pengganti`/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
Karena bayangan ada dan telah diinisialisasi oleh perangkat untuk mencerminkan keadaan saat ini, itu harus mengembalikan dokumen bayangan berikut.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591141111
}
```
Aplikasi dapat menggunakan respons ini untuk menginisialisasi representasi status perangkat.
Jika aplikasi memperbarui status, seperti ketika pengguna akhir mengubah warna bola lampu pintar kami menjadi kuning, aplikasi akan mengirim **update-thing-shadow** perintah. Perintah ini sesuai dengan `UpdateThingShadow` REST API.
**Untuk memperbarui bayangan dari aplikasi**
Dari baris perintah, masukkan perintah ini.
------
#### [ AWS CLI v2.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
#### [ AWS CLI v1.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
Jika berhasil, perintah ini harus mengembalikan dokumen bayangan berikut.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
}
},
"version": 4,
"timestamp": 1591141596,
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
## Menanggapi pembaruan di perangkat
Kembali ke **klien MQTT** di AWS konsol, Anda akan melihat pesan yang AWS IoT diterbitkan untuk mencerminkan perintah pembaruan yang dikeluarkan di bagian sebelumnya.
**Untuk melihat pesan pembaruan di klien **MQTT****
**Di **klien MQTT**, pilih **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta** di kolom Langganan.** Jika nama topik terpotong, Anda dapat menjeda untuk melihat topik lengkapnya. Dalam log topik topik ini, Anda akan melihat `/delta` pesan yang mirip dengan yang ini.
```
{
"version": 4,
"timestamp": 1591141596,
"state": {
"ColorRGB": [
255,
255,
0
]
},
"metadata": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
Perangkat Anda akan memproses konten pesan ini untuk menyetel status perangkat agar sesuai dengan `desired` status dalam pesan.
Setelah perangkat memperbarui status agar sesuai dengan `desired` status dalam pesan, perangkat harus mengirim status baru yang dilaporkan kembali AWS IoT dengan menerbitkan pesan pembaruan. Prosedur ini mensimulasikan ini di klien **MQTT**.
**Untuk memperbarui bayangan dari perangkat**
1. Di **klien MQTT**, pilih **Publikasikan ke topik**.
1. Di jendela isi pesan, di bidang topik di atas jendela isi pesan, masukkan topik bayangan diikuti dengan `/update` tindakan: `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` dan di badan pesan, masukkan dokumen bayangan yang diperbarui ini, yang menjelaskan keadaan perangkat saat ini. Klik **Publikasikan** untuk mempublikasikan status perangkat yang diperbarui.
```
{
"state": {
"reported": {
"ColorRGB": [255,255,0]
}
},
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Jika pesan berhasil diterima oleh AWS IoT, Anda akan melihat respons baru di log aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted pesan **\$1** di **klien MQTT** dengan status bayangan saat ini, seperti contoh ini.
```
{
"state": {
"reported": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"reported": {
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Pembaruan yang berhasil ke status perangkat yang dilaporkan juga AWS IoT menyebabkan pengiriman deskripsi komprehensif tentang status bayangan dalam pesan ke `update/documents` topik, seperti badan pesan ini yang dihasilkan dari pembaruan bayangan yang dilakukan oleh perangkat dalam prosedur sebelumnya.
```
{
"previous": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 4
},
"current": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5
},
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
## Amati pembaruan di aplikasi
Aplikasi sekarang dapat menanyakan bayangan untuk status saat ini seperti yang dilaporkan oleh perangkat.
**Untuk mendapatkan status bayangan saat ini menggunakan AWS CLI**
1. Dari baris perintah, masukkan perintah ini.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Pada platform Windows, Anda dapat menggunakan `con` sebagai pengganti`/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
1. Karena bayangan baru saja diperbarui oleh perangkat untuk mencerminkan keadaan saat ini, itu harus mengembalikan dokumen bayangan berikut.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591143269
}
```
## Melampaui simulasi
Bereksperimenlah dengan interaksi antara AWS CLI (mewakili aplikasi) dan konsol (mewakili perangkat) untuk memodelkan solusi IoT Anda.
# Berinteraksi dengan bayangan
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. Saat status bayangan berubah, AWS IoT kirim `/delta` pesan ke semua pelanggan MQTT dengan perbedaan antara status `desired` dan status. `reported` 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](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) dan REST API melalui protokol HTTPS untuk berinteraksi dengan bayangan. AWS IoT menyediakan serangkaian topik permintaan dan respons yang dicadangkan untuk tindakan publikasi dan berlangganan MQTT. Perangkat dan aplikasi harus berlangganan topik respons sebelum memublikasikan topik permintaan untuk informasi tentang cara AWS IoT menangani permintaan. Untuk informasi selengkapnya, lihat [Topik MQTT Bayangan Perangkat](device-shadow-mqtt.md) dan [Device Shadow REST API](device-shadow-rest-api.md).
## 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](device-shadow-rest-api.md#API_UpdateThingShadow) API atau dengan memublikasikan ke [/perbarui](device-shadow-mqtt.md#update-pub-sub-topic) 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 protokol MQTT**
1. Klien harus memiliki dokumen bayangan saat ini sehingga dapat mengidentifikasi properti yang akan diubah. Lihat tindakan /get untuk cara mendapatkan dokumen bayangan saat ini.
1. Klien berlangganan topik MQTT 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`
1. Klien menerbitkan topik `$aws/things/thingName/shadow/name/shadowName/update` 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.
```
{
"state": {
"desired": {
"color": {
"r": 10
},
"engine": "ON"
}
}
}
```
1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan, dan `/update/delta` pesan berisi dokumen [/dokumen status respons delta](device-shadow-document.md#device-shadow-example-response-json-delta) bayangan.
1. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan `$aws/things/thingName/shadow/name/shadowName/update/rejected` topik dengan dokumen [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) bayangan yang menjelaskan kesalahan.
**Saat klien meminta perubahan status dalam bayangan dengan menggunakan API**
1. Klien memanggil `UpdateThingShadow` API dengan dokumen [Minta dokumen negara](device-shadow-document.md#device-shadow-example-request-json) status sebagai badan pesannya.
1. Jika permintaan itu valid, AWS IoT mengembalikan kode respons sukses HTTP dan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan sebagai badan pesan responsnya.
AWS IoT juga akan menerbitkan pesan MQTT ke `$aws/things/thingName/shadow/name/shadowName/update/delta` topik dengan dokumen [/dokumen status respons delta](device-shadow-document.md#device-shadow-example-response-json-delta) bayangan untuk perangkat atau klien apa pun yang berlangganan.
1. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) 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 protokol MQTT**
1. Perangkat harus berlangganan topik MQTT 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`
1. Perangkat melaporkan statusnya saat ini dengan menerbitkan pesan ke `$aws/things/thingName/shadow/name/shadowName/update` topik yang melaporkan status saat ini, seperti dalam contoh ini.
```
{
"state": {
"reported" : {
"color" : { "r" : 10 },
"engine" : "ON"
}
}
}
```
1. Jika AWS IoT menerima pembaruan, ia menerbitkan pesan ke `$aws/things/thingName/shadow/name/shadowName/update/accepted` topik dengan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan.
1. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan `$aws/things/thingName/shadow/name/shadowName/update/rejected` topik dengan dokumen [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) bayangan yang menjelaskan kesalahan.
**Saat perangkat melaporkan statusnya saat ini ke bayangan dengan menggunakan API**
1. Perangkat memanggil `UpdateThingShadow` API dengan dokumen [Minta dokumen negara](device-shadow-document.md#device-shadow-example-request-json) status sebagai badan pesannya.
1. Jika permintaan itu valid, AWS IoT perbarui bayangan dan mengembalikan kode respons sukses HTTP dengan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan sebagai badan pesan responsnya.
AWS IoT juga akan menerbitkan pesan MQTT ke `$aws/things/thingName/shadow/name/shadowName/update/delta` topik dengan dokumen [/dokumen status respons delta](device-shadow-document.md#device-shadow-example-response-json-delta) bayangan untuk perangkat atau klien apa pun yang berlangganan.
1. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) 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 API apa pun yang memodifikasi`ThingShadow`, termasuk`DeleteThingShadow`.
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](device-shadow-rest-api.md#API_GetThingShadow) API atau dengan berlangganan dan menerbitkan topik. [/dapatkan](device-shadow-mqtt.md#get-pub-sub-topic) Ini mengambil dokumen bayangan lengkap, termasuk delta apa pun antara status `desired` dan`reported`. Prosedur untuk tugas ini sama apakah perangkat atau klien membuat permintaan.
**Untuk mengambil dokumen bayangan dengan menggunakan protokol MQTT**
1. Perangkat atau klien harus berlangganan topik MQTT ini sebelum memperbarui bayangan:
+ `$aws/things/thingName/shadow/name/shadowName/get/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/get/rejected`
1. Perangkat atau klien menerbitkan pesan ke `$aws/things/thingName/shadow/name/shadowName/get` topik dengan badan pesan kosong.
1. Jika permintaan berhasil, AWS IoT menerbitkan pesan ke `$aws/things/thingName/shadow/name/shadowName/get/accepted` topik dengan [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) di badan pesan.
1. Jika permintaan tidak valid, AWS IoT menerbitkan pesan ke `$aws/things/thingName/shadow/name/shadowName/get/rejected` topik dengan [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) di badan pesan.
**Untuk mengambil dokumen bayangan dengan menggunakan REST API**
1. Perangkat atau klien memanggil `GetThingShadow` API dengan badan pesan kosong.
1. Jika permintaan valid, AWS IoT mengembalikan kode respons sukses HTTP dengan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan sebagai badan pesan responsnya.
1. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) 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 nilai `null` dihapus dari dokumen bayangan.
+ Untuk menghapus seluruh bayangan, gunakan [DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow) API atau publikasikan ke [/delete](device-shadow-mqtt.md#delete-pub-sub-topic) 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 protokol MQTT**
1. Perangkat atau klien harus memiliki dokumen bayangan saat ini sehingga dapat mengidentifikasi properti yang akan diubah. Lihat [Mengambil dokumen bayangan](#retrieving-device-shadow) untuk informasi tentang cara mendapatkan dokumen bayangan saat ini.
1. Perangkat atau klien berlangganan topik MQTT ini:
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
1. Perangkat atau klien menerbitkan topik `$aws/things/thingName/shadow/name/shadowName/update` permintaan dengan dokumen status yang menetapkan `null` nilai ke properti bayangan yang akan dihapus. Hanya properti yang akan diubah yang perlu dimasukkan dalam dokumen. Ini adalah contoh dokumen yang menghapus `engine` properti.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Jika permintaan pembaruan valid, AWS IoT hapus properti yang ditentukan dalam bayangan dan menerbitkan pesan dengan `$aws/things/thingName/shadow/name/shadowName/update/accepted` topik dengan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan di badan pesan.
1. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan `$aws/things/thingName/shadow/name/shadowName/update/rejected` topik dengan dokumen [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) bayangan yang menjelaskan kesalahan.
**Untuk menghapus properti dari bayangan dengan menggunakan REST API**
1. Perangkat atau klien memanggil `UpdateThingShadow` API dengan [Minta dokumen negara](device-shadow-document.md#device-shadow-example-request-json) yang menetapkan `null` nilai ke properti bayangan untuk dihapus. Sertakan hanya properti yang ingin Anda hapus dalam dokumen. Ini adalah contoh dokumen yang menghapus `engine` properti.
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. Jika permintaan itu valid, AWS IoT mengembalikan kode respons sukses HTTP dan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan sebagai badan pesan responsnya.
1. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) 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 protokol MQTT**
1. Perangkat atau klien berlangganan topik MQTT ini:
+ `$aws/things/thingName/shadow/name/shadowName/delete/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/delete/rejected`
1. Perangkat atau klien menerbitkan buffer pesan `$aws/things/thingName/shadow/name/shadowName/delete` dengan kosong.
1. Jika permintaan hapus valid, AWS IoT hapus bayangan dan publikasikan pesan dengan `$aws/things/thingName/shadow/name/shadowName/delete/accepted` topik dan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan yang disingkat di badan pesan. Ini adalah contoh pesan hapus yang diterima:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan `$aws/things/thingName/shadow/name/shadowName/delete/rejected` topik dengan dokumen [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) bayangan yang menjelaskan kesalahan.
**Untuk menghapus bayangan dengan menggunakan REST API**
1. Perangkat atau klien memanggil `DeleteThingShadow` API dengan buffer pesan kosong.
1. Jika permintaan itu valid, AWS IoT mengembalikan kode respons sukses HTTP dan [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) dan dokumen [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted) bayangan disingkat di badan pesan. Ini adalah contoh pesan hapus yang diterima:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json) sebagai badan pesan responsnya.
# Device Shadow REST API
Bayangan mengekspos URI berikut untuk memperbarui informasi status:
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
Titik akhir khusus untuk Anda Akun AWS. Untuk menemukan titik akhir Anda, Anda dapat:
+ Gunakan [perintah describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) dari file. AWS CLI
+ Gunakan pengaturan AWS IoT konsol. Di **Pengaturan**, titik akhir tercantum di bawah titik akhir **Kustom**
+ Gunakan halaman detail hal AWS IoT konsol. Di konsol:
1. Buka **Kelola** dan di bawah **Kelola**, pilih **Hal**.
1. Dalam daftar hal-hal, pilih hal yang ingin Anda dapatkan URI endpoint.
1. Pilih tab **Device Shadows** dan pilih bayangan Anda. Anda dapat melihat URI titik akhir di bagian **URL Device Shadow** pada halaman **detail Device Shadow**.
Format titik akhir adalah sebagai berikut:
```
identifier.iot.region.amazonaws.com
```
Shadow REST API mengikuti protocols/port pemetaan HTTPS yang sama seperti yang dijelaskan dalam. [Protokol komunikasi perangkat](protocols.md)
**catatan**
Untuk menggunakan APIs, Anda harus menggunakan `iotdevicegateway` sebagai nama layanan untuk otentikasi. Untuk informasi lebih lanjut, lihat [Io TData Plane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html).
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
Anda juga dapat menggunakan API untuk membuat bayangan bernama dengan menyediakan `name=shadowName` sebagai bagian dari parameter kueri API.
## GetThingShadow
Mendapat bayangan untuk hal yang ditentukan.
Dokumen status respons mencakup delta antara negara `reported` bagian `desired` dan negara bagian.
**Permintaan**
Permintaan termasuk header HTTP standar ditambah URI berikut:
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Parameter `name` kueri tidak diperlukan untuk bayangan (klasik) yang tidak disebutkan namanya.
**Respons**
Setelah berhasil, respon mencakup header HTTP standar ditambah kode dan tubuh berikut:
```
HTTP 200
Response Body: response state document
```
Untuk informasi selengkapnya, lihat [Contoh Dokumen Status Respons](device-shadow-document.md#device-shadow-example-response-json).
**Otorisasi**
Mengambil bayangan memerlukan kebijakan yang memungkinkan pemanggil untuk melakukan tindakan. `iot:GetThingShadow` Layanan Device Shadow menerima dua bentuk otentikasi: Signature Version 4 dengan kredensyal IAM atau otentikasi timbal balik TLS dengan sertifikat klien.
Berikut ini adalah contoh kebijakan yang memungkinkan pemanggil untuk mengambil bayangan perangkat:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
Memperbarui bayangan untuk hal yang ditentukan.
Pembaruan hanya memengaruhi bidang yang ditentukan dalam dokumen status permintaan. Bidang apa pun dengan nilai `null` dihapus dari bayangan perangkat.
**Permintaan**
Permintaan mencakup header HTTP standar ditambah URI dan isi berikut:
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
Parameter `name` kueri tidak diperlukan untuk bayangan (klasik) yang tidak disebutkan namanya.
Untuk informasi selengkapnya, lihat [Contoh Permintaan Dokumen Negara](device-shadow-document.md#device-shadow-example-request-json).
**Respons**
Setelah berhasil, respon mencakup header HTTP standar ditambah kode dan tubuh berikut:
```
HTTP 200
Response body: response state document
```
Untuk informasi selengkapnya, lihat [Contoh Dokumen Status Respons](device-shadow-document.md#device-shadow-example-response-json).
**Otorisasi**
Memperbarui bayangan memerlukan kebijakan yang memungkinkan pemanggil untuk melakukan `iot:UpdateThingShadow` tindakan. Layanan Device Shadow menerima dua bentuk otentikasi: Signature Version 4 dengan kredensyal IAM atau otentikasi timbal balik TLS dengan sertifikat klien.
Berikut ini adalah contoh kebijakan yang memungkinkan pemanggil memperbarui bayangan perangkat:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
Menghapus bayangan untuk objek yang ditentukan.
**Permintaan**
Permintaan termasuk header HTTP standar ditambah URI berikut:
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Parameter `name` kueri tidak diperlukan untuk bayangan (klasik) yang tidak disebutkan namanya.
**Respons**
Setelah berhasil, respon mencakup header HTTP standar ditambah kode dan tubuh berikut:
```
HTTP 200
Response body: Empty response state document
```
Perhatikan bahwa menghapus bayangan tidak mengatur ulang nomor versinya ke 0.
**Otorisasi**
Menghapus bayangan perangkat memerlukan kebijakan yang memungkinkan pemanggil melakukan tindakan. `iot:DeleteThingShadow` Layanan Device Shadow menerima dua bentuk otentikasi: Signature Version 4 dengan kredensyal IAM atau otentikasi timbal balik TLS dengan sertifikat klien.
Berikut ini adalah contoh kebijakan yang memungkinkan pemanggil menghapus bayangan perangkat:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
Daftar bayangan untuk hal yang ditentukan.
**Permintaan**
Permintaan termasuk header HTTP standar ditambah URI berikut:
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
Token untuk mengambil set hasil berikutnya.
Nilai ini dikembalikan pada hasil berhalaman dan digunakan dalam panggilan yang mengembalikan halaman berikutnya.
pageSize
Jumlah nama bayangan yang akan dikembalikan di setiap panggilan. Lihat juga `nextToken`.
thingName
Nama objek perangkat yang bayangan bernama didaftar untuknya.
**Respons**
Setelah berhasil, responsnya mencakup header HTTP standar ditambah kode respons berikut dan a[Dokumen respons daftar nama bayangan](device-shadow-document.md#device-shadow-list-json).
**catatan**
Bayangan yang tidak disebutkan namanya (klasik) tidak muncul dalam daftar ini. Responsnya adalah daftar kosong jika Anda hanya memiliki bayangan klasik atau jika yang `thingName` Anda tentukan tidak ada.
```
HTTP 200
Response body: Shadow name list document
```
**Otorisasi**
Membuat daftar bayangan perangkat memerlukan kebijakan yang memungkinkan pemanggil untuk melakukan `iot:ListNamedShadowsForThing` tindakan. Layanan Device Shadow menerima dua bentuk otentikasi: Signature Version 4 dengan kredensyal IAM atau otentikasi timbal balik TLS dengan sertifikat klien.
Berikut ini adalah contoh kebijakan yang memungkinkan pemanggil untuk membuat daftar bayangan bernama sesuatu:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
# Topik MQTT Bayangan Perangkat
Layanan Device Shadow menggunakan topik MQTT yang dicadangkan untuk memungkinkan perangkat dan aplikasi mendapatkan, memperbarui, atau menghapus informasi status untuk perangkat (bayangan).
Menerbitkan dan berlangganan topik bayangan memerlukan otorisasi berbasis topik. AWS IoT berhak untuk menambahkan topik baru ke struktur topik yang ada. Untuk alasan ini, kami menyarankan Anda menghindari langganan wild card ke topik bayangan. Misalnya, hindari berlangganan filter topik seperti `$aws/things/thingName/shadow/#` karena jumlah topik yang cocok dengan filter topik ini mungkin meningkat saat AWS IoT memperkenalkan topik bayangan baru. Untuk contoh pesan yang dipublikasikan pada topik ini lihat[Berinteraksi dengan bayangan](device-shadow-data-flow.md).
Bayangan dapat dinamai atau tidak disebutkan namanya (klasik). Topik yang digunakan oleh masing-masing hanya berbeda dalam awalan topik. Tabel ini menunjukkan awalan topik yang digunakan oleh setiap jenis bayangan.
| Nilai *ShadowTopicPrefix* | Jenis bayangan |
| --- | --- |
| \$1aws/things/thingName/shadow | Bayangan tanpa nama (klasik) |
| \$1aws/things/thingName/shadow/name/shadowName | Bernama bayangan |
Untuk membuat topik lengkap, pilih jenis bayangan yang ingin Anda rujuk, ganti, dan `shadowName` jika berlaku`thingName`, dengan nilai yang sesuai, lalu tambahkan dengan rintisan topik seperti yang ditunjukkan pada bagian berikut. `ShadowTopicPrefix`
Berikut ini adalah topik MQTT yang digunakan untuk berinteraksi dengan bayangan.
**Topics**
+ [/dapatkan](#get-pub-sub-topic)
+ [/dapatkan/diterima](#get-accepted-pub-sub-topic)
+ [/dapatkan/ditolak](#get-rejected-pub-sub-topic)
+ [/perbarui](#update-pub-sub-topic)
+ [/perbarui/delta](#update-delta-pub-sub-topic)
+ [/perbarui/diterima](#update-accepted-pub-sub-topic)
+ [/pembaruan/dokumen](#update-documents-pub-sub-topic)
+ [/perbarui/ditolak](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/hapus/diterima](#delete-accepted-pub-sub-topic)
+ [/hapus/ditolak](#delete-rejected-pub-sub-topic)
## /dapatkan
Publikasikan pesan kosong ke topik ini untuk mendapatkan bayangan perangkat:
```
ShadowTopicPrefix/get
```
AWS IoT merespons dengan menerbitkan salah satu [/dapatkan/diterima](#get-accepted-pub-sub-topic) atau[/dapatkan/ditolak](#get-rejected-pub-sub-topic).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get"
]
}
]
}
```
## /dapatkan/diterima
AWS IoT menerbitkan dokumen bayangan respons ke topik ini saat mengembalikan bayangan perangkat:
```
ShadowTopicPrefix/get/accepted
```
Untuk informasi selengkapnya, lihat [Dokumen negara respons](device-shadow-document.md#device-shadow-example-response-json).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/accepted"
]
}
]
}
```
## /dapatkan/ditolak
AWS IoT menerbitkan dokumen respons kesalahan ke topik ini jika tidak dapat mengembalikan bayangan perangkat:
```
ShadowTopicPrefix/get/rejected
```
Untuk informasi selengkapnya, lihat [Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/rejected"
]
}
]
}
```
## /perbarui
Publikasikan dokumen status permintaan ke topik ini untuk memperbarui bayangan perangkat:
```
ShadowTopicPrefix/update
```
Badan pesan berisi [dokumen status permintaan sebagian](device-shadow-document.md#device-shadow-example-request-json).
Klien yang mencoba memperbarui status perangkat akan mengirim dokumen status permintaan JSON dengan `desired` properti seperti ini:
```
{
"state": {
"desired": {
"color": "red",
"power": "on"
}
}
}
```
Perangkat yang memperbarui bayangannya akan mengirim dokumen status permintaan JSON dengan `reported` properti, seperti ini:
```
{
"state": {
"reported": {
"color": "red",
"power": "on"
}
}
}
```
AWS IoT merespons dengan menerbitkan salah satu [/perbarui/diterima](#update-accepted-pub-sub-topic) atau[/perbarui/ditolak](#update-rejected-pub-sub-topic).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update"
]
}
]
}
```
## /perbarui/delta
AWS IoT menerbitkan dokumen status respons ke topik ini saat menerima perubahan untuk bayangan perangkat, dan dokumen status respons berisi nilai `desired` dan `reported` status yang berbeda:
```
ShadowTopicPrefix/update/delta
```
Buffer pesan berisi file. [/dokumen status respons delta](device-shadow-document.md#device-shadow-example-response-json-delta)
### Detail isi pesan
+ Pesan yang dipublikasikan hanya `update/delta` mencakup atribut yang diinginkan yang berbeda antara bagian `desired` dan `reported` bagian. Ini berisi semua atribut ini, terlepas dari apakah atribut ini terkandung dalam pesan pembaruan saat ini atau sudah disimpan di AWS IoT. Atribut yang tidak berbeda antara `reported` bagian `desired` dan bagian tidak termasuk.
+ Jika atribut ada di `reported` bagian tetapi tidak memiliki padanan di `desired` bagian, itu tidak termasuk.
+ Jika atribut ada di `desired` bagian tetapi tidak memiliki padanan di `reported` bagian, itu disertakan.
+ Jika atribut dihapus dari `reported` bagian tetapi masih ada di `desired` bagian, itu disertakan.
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta"
]
}
]
}
```
## /perbarui/diterima
AWS IoT menerbitkan dokumen status respons ke topik ini saat menerima perubahan untuk bayangan perangkat:
```
ShadowTopicPrefix/update/accepted
```
Buffer pesan berisi file. [/dokumen status respons yang diterima](device-shadow-document.md#device-shadow-example-response-json-accepted)
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/accepted"
]
}
]
}
```
## /pembaruan/dokumen
AWS IoT menerbitkan dokumen status ke topik ini setiap kali pembaruan bayangan berhasil dilakukan:
```
ShadowTopicPrefix/update/documents
```
Badan pesan berisi a[/dokumen dokumen status respon](device-shadow-document.md#device-shadow-example-response-json-documents).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents"
]
}
]
}
```
## /perbarui/ditolak
AWS IoT menerbitkan dokumen respons kesalahan ke topik ini saat menolak perubahan bayangan perangkat:
```
ShadowTopicPrefix/update/rejected
```
Badan pesan berisi[Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/rejected"
]
}
]
}
```
## /delete
Untuk menghapus bayangan perangkat, publikasikan pesan kosong ke topik hapus:
```
ShadowTopicPrefix/delete
```
Isi pesan diabaikan.
Perhatikan bahwa menghapus bayangan tidak mengatur ulang nomor versinya ke 0.
AWS IoT merespons dengan menerbitkan salah satu [/hapus/diterima](#delete-accepted-pub-sub-topic) atau[/hapus/ditolak](#delete-rejected-pub-sub-topic).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete"
]
}
]
}
```
## /hapus/diterima
AWS IoT menerbitkan pesan ke topik ini saat bayangan perangkat dihapus:
```
ShadowTopicPrefix/delete/accepted
```
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/accepted"
]
}
]
}
```
## /hapus/ditolak
AWS IoT menerbitkan dokumen respons kesalahan ke topik ini jika tidak dapat menghapus bayangan perangkat:
```
ShadowTopicPrefix/delete/rejected
```
Badan pesan berisi[Dokumen respons kesalahan](device-shadow-document.md#device-shadow-example-error-json).
### Contoh kebijakan
Berikut ini adalah contoh kebijakan yang diperlukan:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected"
]
}
]
}
```
# Dokumen layanan Device Shadow
Layanan Device Shadow menghormati semua aturan spesifikasi JSON. Nilai, objek, dan array disimpan dalam dokumen bayangan perangkat.
**Topics**
+ [Contoh dokumen bayangan](#device-shadow-document-syntax)
+ [Properti dokumen](#document-structure)
+ [Negara bagian Delta](#delta-state)
+ [Versioning dokumen bayangan](#versioning)
+ [Token klien dalam dokumen bayangan](#client-token)
+ [Properti dokumen bayangan kosong](#device-shadow-empty-fields)
+ [Nilai array dalam dokumen bayangan](#device-shadow-arrays)
## Contoh dokumen bayangan
Layanan Device Shadow menggunakan dokumen-dokumen ini dalam operasi UPDATE, GET, dan DELETE menggunakan [REST API](device-shadow-rest-api.md) atau [MQTT Messages Pub/Sub ](device-shadow-mqtt.md).
**Topics**
+ [Minta dokumen negara](#device-shadow-example-request-json)
+ [Dokumen negara respons](#device-shadow-example-response-json)
+ [Dokumen respons kesalahan](#device-shadow-example-error-json)
+ [Dokumen respons daftar nama bayangan](#device-shadow-list-json)
### Minta dokumen negara
Dokumen status permintaan memiliki format berikut:
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"clientToken": "token",
"version": version
}
```
+ `state`— Pembaruan hanya memengaruhi bidang yang ditentukan. Biasanya, Anda akan menggunakan properti `desired` atau `reported` properti, tetapi tidak keduanya dalam permintaan yang sama.
+ `desired`— Properti dan nilai status yang diminta untuk diperbarui di perangkat.
+ `reported`— Properti dan nilai status yang dilaporkan oleh perangkat.
+ `clientToken`— Jika digunakan, Anda dapat mencocokkan permintaan dan respons yang sesuai dengan token klien.
+ `version`— Jika digunakan, layanan Device Shadow memproses pembaruan hanya jika versi yang ditentukan cocok dengan versi terbaru yang dimilikinya.
### Dokumen negara respons
Dokumen status respons memiliki format berikut tergantung pada jenis respons.
#### /dokumen status respons yang diterima
```
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### /dokumen status respons delta
```
{
"state": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"metadata": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"timestamp": timestamp,
"clientToken": "token",
"version": version
}
```
#### /dokumen dokumen status respon
```
{
"previous" : {
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"version": version-1
},
"current": {
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"version": version
},
"timestamp": timestamp,
"clientToken": "token"
}
```
#### Properti dokumen status respons
+ `previous`— Setelah pembaruan berhasil, berisi objek sebelum pembaruan. `state`
+ `current`— Setelah pembaruan berhasil, berisi objek setelah pembaruan. `state`
+ `state`
+ `reported`— Hadir hanya jika sesuatu melaporkan data apa pun di `reported` bagian dan hanya berisi bidang yang ada di dokumen negara permintaan.
+ `desired`— Hadir hanya jika perangkat melaporkan data apa pun di `desired` bagian dan hanya berisi bidang yang ada di dokumen negara permintaan.
+ `metadata`— Berisi stempel waktu untuk setiap atribut di `reported` bagian `desired` dan sehingga Anda dapat menentukan kapan status diperbarui.
+ `timestamp`— Tanggal dan waktu Epoch respons dihasilkan oleh AWS IoT.
+ `clientToken`— Hadir hanya jika token klien digunakan saat menerbitkan JSON yang valid ke `/update` topik tersebut.
+ `version`— Versi dokumen saat ini untuk bayangan perangkat yang dibagikan AWS IoT. Ini meningkat satu kali lipat dari versi dokumen sebelumnya.
### Dokumen respons kesalahan
Dokumen respons kesalahan memiliki format berikut:
```
{
"code": error-code,
"message": "error-message",
"timestamp": timestamp,
"clientToken": "token"
}
```
+ `code`— Kode respons HTTP yang menunjukkan jenis kesalahan.
+ `message`— Pesan teks yang memberikan informasi tambahan.
+ `timestamp`— Tanggal dan waktu respons dihasilkan oleh AWS IoT. Properti ini tidak ada di semua dokumen respons kesalahan.
+ `clientToken`— Hadir hanya jika token klien digunakan dalam pesan yang diterbitkan.
Untuk informasi selengkapnya, lihat [Pesan kesalahan Device Shadow](device-shadow-error-messages.md).
### Dokumen respons daftar nama bayangan
Dokumen respons daftar nama bayangan memiliki format berikut:
```
{
"results": [
"shadowName-1",
"shadowName-2",
"shadowName-3",
"shadowName-n"
],
"nextToken": "nextToken",
"timestamp": timestamp
}
```
+ `results`— Array nama bayangan.
+ `nextToken`— Nilai token yang digunakan dalam permintaan halaman untuk mendapatkan halaman berikutnya dalam urutan. Properti ini tidak ada ketika tidak ada lagi nama bayangan untuk dikembalikan.
+ `timestamp`— Tanggal dan waktu respons dihasilkan oleh AWS IoT.
## Properti dokumen
Dokumen bayangan perangkat memiliki properti berikut:
`state`
`desired`
Keadaan perangkat yang diinginkan. Aplikasi dapat menulis ke bagian dokumen ini untuk memperbarui status perangkat secara langsung tanpa harus menghubungkannya.
`reported`
Status perangkat yang dilaporkan. Perangkat menulis ke bagian dokumen ini untuk melaporkan keadaan baru mereka. Aplikasi membaca bagian dokumen ini untuk menentukan status perangkat yang dilaporkan terakhir.
`metadata`
Informasi tentang data yang disimpan di `state` bagian dokumen. Ini termasuk stempel waktu, dalam waktu Epoch, untuk setiap atribut di `state` bagian, yang memungkinkan Anda untuk menentukan kapan mereka diperbarui.
Metadata tidak berkontribusi pada ukuran dokumen untuk batas layanan atau harga. Untuk informasi selengkapnya, lihat [Batas AWS IoT Layanan](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot).
`timestamp`
Menunjukkan kapan pesan dikirim oleh AWS IoT. Dengan menggunakan stempel waktu dalam pesan dan stempel waktu untuk atribut individual di `reported` bagian `desired` atau, perangkat dapat menentukan usia properti, meskipun perangkat tidak memiliki jam internal.
`clientToken`
String unik untuk perangkat yang memungkinkan Anda mengaitkan respons dengan permintaan di lingkungan MQTT.
`version`
Versi dokumen. Setiap kali dokumen diperbarui, nomor versi ini bertambah. Digunakan untuk memastikan versi dokumen yang diperbarui adalah yang terbaru.
Untuk informasi selengkapnya, lihat [Contoh dokumen bayangan](#device-shadow-document-syntax).
## Negara bagian Delta
Delta state adalah jenis virtual state yang berisi perbedaan antara state `desired` dan `reported` state. Bidang di `desired` bagian yang tidak ada di `reported` bagian termasuk dalam delta. Bidang yang ada di `reported` bagian dan bukan di `desired` bagian tidak termasuk dalam delta. Delta berisi metadata, dan nilainya sama dengan metadata di lapangan. `desired` Contoh:
```
{
"state": {
"desired": {
"color": "RED",
"state": "STOP"
},
"reported": {
"color": "GREEN",
"engine": "ON"
},
"delta": {
"color": "RED",
"state": "STOP"
}
},
"metadata": {
"desired": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
},
"reported": {
"color": {
"timestamp": 12345
},
"engine": {
"timestamp": 12345
}
},
"delta": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
}
},
"version": 17,
"timestamp": 123456789
}
}
```
Ketika objek bersarang berbeda, delta berisi jalur sampai ke root.
```
{
"state": {
"desired": {
"lights": {
"color": {
"r": 255,
"g": 255,
"b": 255
}
}
},
"reported": {
"lights": {
"color": {
"r": 255,
"g": 0,
"b": 255
}
}
},
"delta": {
"lights": {
"color": {
"g": 255
}
}
}
},
"version": 18,
"timestamp": 123456789
}
```
Layanan Device Shadow menghitung delta dengan mengulangi setiap bidang dalam `desired` status dan membandingkannya dengan status. `reported`
Array diperlakukan seperti nilai. Jika array di `desired` bagian tidak cocok dengan array di `reported` bagian, maka seluruh array yang diinginkan disalin ke delta.
## Versioning dokumen bayangan
Layanan Device Shadow mendukung pembuatan versi pada setiap pesan pembaruan, baik permintaan maupun respons. Ini berarti bahwa dengan setiap pembaruan bayangan, versi dokumen JSON bertambah. Ini memastikan dua hal:
+ Klien dapat menerima kesalahan jika mencoba menimpa bayangan menggunakan nomor versi yang lebih lama. Klien diberi tahu bahwa ia harus melakukan sinkronisasi ulang sebelum dapat memperbarui bayangan perangkat.
+ Klien dapat memutuskan untuk tidak bertindak atas pesan yang diterima jika pesan memiliki versi yang lebih rendah dari versi yang disimpan oleh klien.
Klien dapat melewati pencocokan versi dengan tidak menyertakan versi dalam dokumen bayangan.
## Token klien dalam dokumen bayangan
Anda dapat menggunakan token klien dengan pesan berbasis MQTT untuk memverifikasi token klien yang sama terkandung dalam permintaan dan respons permintaan. Ini memastikan respons dan permintaan terkait.
**catatan**
Token klien tidak boleh lebih dari 64 byte. Token klien yang lebih panjang dari 64 byte menyebabkan respons 400 (Permintaan Buruk) dan pesan kesalahan *ClientToken Tidak Valid*.
## Properti dokumen bayangan kosong
`desired`Properti `reported` dan dalam dokumen bayangan dapat kosong atau dihilangkan ketika tidak berlaku untuk status bayangan saat ini. Misalnya, dokumen bayangan berisi `desired` properti hanya jika memiliki status yang diinginkan. Berikut ini adalah contoh valid dari dokumen negara tanpa `desired` properti:
```
{
"reported" : { "temp": 55 }
}
```
`reported`Properti juga bisa kosong, seperti jika bayangan belum diperbarui oleh perangkat:
```
{
"desired" : { "color" : "RED" }
}
```
Jika pembaruan menyebabkan `reported` properti `desired` atau menjadi nol, itu dihapus dari dokumen. Berikut ini menunjukkan cara menghapus `desired` properti dengan menyetelnya ke`null`. Anda dapat melakukan ini ketika perangkat memperbarui statusnya, misalnya.
```
{
"state": {
"reported": {
"color": "red"
},
"desired": null
}
}
```
Dokumen bayangan juga dapat memiliki keduanya `desired` atau `reported` properti, membuat dokumen bayangan kosong. Ini adalah contoh dokumen bayangan kosong namun valid.
```
{
}
```
## Nilai array dalam dokumen bayangan
Shadows mendukung array, tetapi memperlakukannya sebagai nilai normal karena pembaruan ke array menggantikan seluruh array. Hal ini tidak mungkin untuk memperbarui bagian dari array.
Keadaan awal:
```
{
"desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
```
Memperbarui:
```
{
"desired" : { "colors" : ["RED"] }
}
```
Keadaan akhir:
```
{
"desired" : { "colors" : ["RED"] }
}
```
Array tidak dapat memiliki nilai null. Misalnya, array berikut tidak valid dan akan ditolak.
```
{
"desired" : {
"colors" : [ null, "RED", "GREEN" ]
}
}
```
# Pesan kesalahan Device Shadow
Layanan Device Shadow menerbitkan pesan tentang topik kesalahan (melalui MQTT) ketika upaya untuk mengubah dokumen status gagal. Pesan ini hanya dipancarkan sebagai tanggapan atas permintaan publikasi pada salah satu topik yang dicadangkan`$aws`. Jika klien memperbarui dokumen menggunakan REST API, maka ia menerima kode kesalahan HTTP sebagai bagian dari responsnya, dan tidak ada pesan kesalahan MQTT yang dipancarkan.
****
| Kode kesalahan HTTP | Pesan kesalahan |
| --- | --- |
| 400 (Permintaan Buruk) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 401 (Tidak Sah) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 403 (Terlarang) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 404 (Tidak Ditemukan) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 409 (Konflik) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 413 (Muatan Terlalu Besar) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 415 (Tipe Media yang Tidak Didukung) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 429 (Terlalu Banyak Permintaan) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |
| 500 (Kesalahan Server Internal) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/device-shadow-error-messages.html) |