Berinteraksi dengan bayangan - AWS IoT Core
Dukungan protokolMeminta dan melaporkan statusMemperbarui bayanganMengambil dokumen bayanganMenghapus data bayangan

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 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 tersebut. Lihat informasi yang lebih lengkap di Topik Device Shadow MQTT dan Device Shadow REST API.

Meminta dan melaporkan status

Saat merancang solusi IoT Anda menggunakan AWS IoT dan bayangan, Anda harus menentukan aplikasi atau perangkat yang akan meminta perubahan dan yang akan menerapkannya. Biasanya, perangkat mengimplementasikan dan melaporkan perubahan kembali ke bayangan dan aplikasi serta layanan merespons dan meminta perubahan dalam bayangan. Solusi Anda mungkin berbeda, tetapi contoh dalam topik ini mengasumsikan bahwa aplikasi klien atau layanan meminta perubahan dalam bayangan dan perangkat melakukan perubahan dan melaporkannya kembali ke bayangan.

Memperbarui bayangan

Aplikasi atau layanan Anda dapat memperbarui status bayangan dengan menggunakan UpdateThingShadow API atau dengan memublikasikan ke /perbarui topik. Pembaruan hanya memengaruhi bidang yang ditentukan dalam permintaan.

Memperbarui bayangan saat klien meminta perubahan status

Ketika klien meminta perubahan status dalam bayangan dengan menggunakan 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.

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

  3. 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"
    }
  }
}

  4. 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/acceptedPesan berisi dokumen /dokumen status respons yang diterima bayangan, dan /update/delta pesan berisi dokumen /dokumen status respons delta bayangan.

  5. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan $aws/things/thingName/shadow/name/shadowName/update/rejected topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.

Saat klien meminta perubahan status dalam bayangan dengan menggunakan API

  1. Klien memanggil UpdateThingShadow API dengan dokumen Minta dokumen negara status sebagai badan pesannya.

  2. Jika permintaan itu valid, AWS IoT mengembalikan kode respons sukses HTTP dan dokumen /dokumen status respons yang diterima 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 bayangan untuk perangkat atau klien apa pun yang berlangganan.

  3. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP Dokumen respons kesalahan sebagai badan pesan responsnya.

Ketika perangkat menerima /desired status pada /update/delta topik, itu membuat perubahan yang diinginkan pada perangkat. Kemudian mengirim pesan ke /update topik untuk melaporkan keadaan saat ini ke bayangan.

Memperbarui bayangan saat perangkat melaporkan statusnya saat ini

Saat perangkat melaporkan statusnya saat ini ke bayangan dengan menggunakan 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

  2. 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"
        }
    }
}

  3. 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 bayangan.

  4. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan $aws/things/thingName/shadow/name/shadowName/update/rejected topik dengan dokumen Dokumen respons kesalahan 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 status sebagai badan pesannya.

  2. Jika permintaan itu valid, AWS IoT perbarui bayangan dan mengembalikan kode respons sukses HTTP dengan dokumen /dokumen status respons yang diterima 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 bayangan untuk perangkat atau klien apa pun yang berlangganan.

  3. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP Dokumen respons kesalahan sebagai badan pesan responsnya.

Penguncian optimis

Anda dapat menggunakan versi dokumen negara untuk memastikan Anda memperbarui versi terbaru dari dokumen bayangan perangkat. Saat Anda menyediakan versi dengan permintaan pembaruan, layanan menolak permintaan dengan kode respons konflik HTTP 409 jika versi dokumen status saat ini tidak cocok dengan versi yang disediakan. Kode respons konflik juga dapat terjadi pada API apa pun yang memodifikasiThingShadow, termasukDeleteThingShadow.

Sebagai contoh:

Dokumen awal:

{
  "state": {
    "desired": {
      "colors": [
        "RED",
        "GREEN",
        "BLUE"
      ]
    }
  },
  "version": 10
}

Pembaruan: (versi tidak cocok; permintaan ini akan ditolak)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

Hasil:

{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

Pembaruan: (versi cocok; permintaan ini akan diterima)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

Keadaan akhir:

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

Mengambil dokumen bayangan

Anda dapat mengambil dokumen bayangan dengan menggunakan GetThingShadow API atau dengan berlangganan dan menerbitkan topik. /dapatkan Ini mengambil dokumen bayangan lengkap, termasuk delta apa pun antara status desired danreported. Prosedur untuk tugas ini sama apakah perangkat atau klien membuat permintaan.

Untuk mengambil dokumen bayangan dengan menggunakan protokol MQTT

  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

  2. Perangkat atau klien menerbitkan pesan ke $aws/things/thingName/shadow/name/shadowName/get topik dengan badan pesan kosong.

  3. Jika permintaan berhasil, AWS IoT menerbitkan pesan ke $aws/things/thingName/shadow/name/shadowName/get/accepted topik dengan /dokumen status respons yang diterima di badan pesan.

  4. Jika permintaan tidak valid, AWS IoT menerbitkan pesan ke $aws/things/thingName/shadow/name/shadowName/get/rejected topik dengan Dokumen respons kesalahan di badan pesan.

Untuk mengambil dokumen bayangan dengan menggunakan REST API

  1. Perangkat atau klien memanggil GetThingShadow API dengan badan pesan kosong.

  2. Jika permintaan valid, AWS IoT mengembalikan kode respons sukses HTTP dengan dokumen /dokumen status respons yang diterima bayangan sebagai badan pesan responsnya.

  3. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP Dokumen respons kesalahan sebagai badan pesan responsnya.

Menghapus data bayangan

Ada dua cara untuk menghapus data bayangan: Anda dapat menghapus properti tertentu dalam dokumen bayangan dan Anda dapat menghapus bayangan sepenuhnya.

  • Untuk menghapus properti tertentu dari bayangan, perbarui bayangan; namun tetapkan nilai properti yang ingin Anda hapusnull. Bidang dengan nilai null dihapus dari dokumen bayangan.

  • Untuk menghapus seluruh bayangan, gunakan DeleteThingShadow API atau publikasikan ke /delete topik.

catatan

Menghapus bayangan tidak mengatur ulang nomor versinya ke nol sekaligus. Ini akan diatur ulang ke nol setelah 48 jam.

Menghapus properti dari dokumen bayangan

Untuk menghapus properti dari bayangan dengan menggunakan protokol MQTT

  1. Perangkat atau klien harus memiliki dokumen bayangan saat ini sehingga dapat mengidentifikasi properti yang akan diubah. Lihat Mengambil dokumen bayangan untuk informasi tentang cara mendapatkan dokumen bayangan saat ini.

  2. Perangkat atau klien berlangganan topik MQTT ini:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. 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
    }
  }
}

  4. 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 bayangan di badan pesan.

  5. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan $aws/things/thingName/shadow/name/shadowName/update/rejected topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.

Untuk menghapus properti dari bayangan dengan menggunakan REST API

  1. Perangkat atau klien memanggil UpdateThingShadow API dengan Minta dokumen negara 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
    }
  }
}

  2. Jika permintaan itu valid, AWS IoT mengembalikan kode respons sukses HTTP dan dokumen /dokumen status respons yang diterima bayangan sebagai badan pesan responsnya.

  3. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP Dokumen respons kesalahan sebagai badan pesan responsnya.

Menghapus bayangan

Berikut ini adalah beberapa pertimbangan saat menghapus bayangan perangkat.

  • Menyetel status bayangan perangkat ke null tidak menghapus bayangan. Versi bayangan akan bertambah pada pembaruan berikutnya.

  • Menghapus bayangan perangkat tidak menghapus objek benda. Menghapus objek benda tidak menghapus bayangan perangkat yang sesuai.

  • Menghapus bayangan tidak mengatur ulang nomor versinya ke nol sekaligus. Ini akan diatur ulang ke nol setelah 48 jam.

Untuk menghapus bayangan dengan menggunakan 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

  2. Perangkat atau klien menerbitkan buffer pesan $aws/things/thingName/shadow/name/shadowName/delete dengan kosong.

  3. 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 bayangan yang disingkat di badan pesan. Ini adalah contoh pesan hapus yang diterima:

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. Jika permintaan pembaruan tidak valid, AWS IoT menerbitkan pesan dengan $aws/things/thingName/shadow/name/shadowName/delete/rejected topik dengan dokumen Dokumen respons kesalahan bayangan yang menjelaskan kesalahan.

Untuk menghapus bayangan dengan menggunakan REST API

  1. Perangkat atau klien memanggil DeleteThingShadow API dengan buffer pesan kosong.

  2. Jika permintaan itu valid, AWS IoT mengembalikan kode respons sukses HTTP dan /dokumen status respons yang diterima dan dokumen /dokumen status respons yang diterima bayangan disingkat di badan pesan. Ini adalah contoh pesan hapus yang diterima:

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. Jika permintaan tidak valid, AWS IoT mengembalikan kode respons kesalahan HTTP Dokumen respons kesalahan sebagai badan pesan responsnya.