Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# 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.