Dokumen layanan Device Shadow - AWS IoT Core
Contoh dokumen bayanganProperti dokumenNegara bagian DeltaDokumen bayangan versiToken klien dalam dokumen bayanganProperti dokumen bayangan kosongNilai array dalam dokumen bayangan

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Dokumen layanan Device Shadow

Layanan Device Shadow menghormati semua aturan spesifikasi JSON. Nilai, objek, dan array disimpan dalam dokumen bayangan perangkat.

Contoh dokumen bayangan

Layanan Device Shadow menggunakan dokumen-dokumen ini dalam operasi UPDATE, GET, dan DELETE menggunakan REST API atau MQTT Pub/Sub Messages.

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 respons

{
  "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.

    • delta— Hadir hanya jika desired data berbeda dari reported data bayangan saat ini.

  • 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.

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 terhubung ke sana.

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.

catatan

Metadata tidak berkontribusi pada ukuran dokumen untuk batas layanan atau harga. Untuk informasi selengkapnya, lihat Batas AWS IoT Layanan.

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.

Negara bagian Delta

Delta state adalah jenis virtual state yang berisi perbedaan antara negara bagian desired dan reported negara bagian. 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 Sebagai 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.

Dokumen bayangan versi

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

desiredProperti 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 }
}

reportedProperti 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 kenull. 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" ]
    }
}