Penerusan data bayangan perangkat - IoT Platform

Data bayangan perangkat diteruskan melalui topik. Data ini diteruskan ketika perangkat mengirimkan status ke bayangan, aplikasi mengubah status perangkat, perangkat meminta bayangan setelah online, atau perangkat menghapus properti bayangan. Artikel ini juga menjelaskan topik spesifik bayangan perangkat dan format data dari topik-topik tersebut.

Topik spesifik bayangan perangkat

IoT Platform telah mendefinisikan dua topik untuk meneruskan data bayangan.

/shadow/update/${YourProductKey}/${YourDeviceName}
Setiap perangkat dan aplikasi mempublikasikan pesan ke topik ini. Setelah pesan dikirim ke topik, IoT Platform menyinkronkan status dalam pesan tersebut ke bayangan perangkat.
/shadow/get/${YourProductKey}/${YourDeviceName}
Status terbaru dalam bayangan perangkat dikirim ke topik ini. Setiap perangkat dapat berlangganan topik ini untuk mendapatkan status terbaru.

Contoh

Artikel ini menjelaskan cara perangkat mengirimkan status ke bayangan, aplikasi mengubah status perangkat, perangkat meminta bayangan, dan perangkat menghapus properti bayangan. Dalam contoh ini, digunakan perangkat bohlam.

ProductKey adalah a1PbRCF****, dan DeviceName adalah lightbulb. Perangkat berlangganan dua topik spesifik bayangan perangkat dan mempublikasikan pesan QoS 1.

Perangkat mengirimkan status

Jika perangkat sedang online, perangkat dapat mengirimkan statusnya ke bayangan. Aplikasi kemudian dapat mendapatkan status dari bayangan.

Gambar berikut menunjukkan proses penerusan data.

Ketika perangkat bohlam online, perangkat mengirimkan status terbarunya ke bayangan menggunakan topik /shadow/update/a1PbRCF****/lightbulb.

Pesan berformat JSON:

{
  "method": "update", 
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "version": 1
}

Tabel 1. Parameter
Parameter	Deskripsi
method	Jenis operasi dalam permintaan yang dikirim oleh perangkat atau aplikasi ke bayangan perangkat. Untuk operasi pembaruan, parameter method diperlukan dan harus diatur ke update.
state	Informasi status yang dikirim oleh perangkat ke bayangan perangkat. Parameter reported diperlukan. Informasi status disinkronkan ke parameter reported dari bayangan perangkat.
version	Informasi versi dalam permintaan. Parameter ini diperiksa oleh bayangan perangkat. Bayangan perangkat hanya memperbarui versi jika versi baru yang ditentukan dalam permintaan lebih baru daripada versi saat ini. Jika parameter version diatur ke `-1`, semua data bayangan perangkat dihapus. Bayangan perangkat memperbarui versinya menjadi `0`.

Setelah bayangan perangkat menerima status yang dikirim oleh bohlam, bayangan perangkat memperbarui file JSON.

{
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }
  }, 
  "timestamp": 1469564492, 
  "version": 1
}

Setelah file JSON diperbarui, bayangan perangkat mengembalikan respons ke bohlam menggunakan topik /shadow/get/a1PbRCF****/lightbulb.

Jika pembaruan berhasil, bayangan perangkat mengirimkan pesan berikut:

{
  "method": "reply", 
  "payload": {
    "status": "success", 
    "version": 1
  }, 
  "timestamp": 1469564576
}

Jika pembaruan gagal, bayangan perangkat mengirimkan pesan berikut:

{
  "method": "reply", 
  "payload": {
    "status": "error", 
    "content": {
      "errorcode": "${errorcode}", 
      "errormessage": "${errormessage}"
    }
  }, 
  "timestamp": 1469564576
}

Tabel 2. Kode Kesalahan
Kode kesalahan	Pesan kesalahan
400	Format JSON tidak valid.
401	Parameter method tidak ditentukan.
402	Parameter state tidak ditentukan.
403	Nilai parameter version bukan angka.
404	Parameter reported tidak ditentukan.
405	Parameter reported kosong.
406	Nilai parameter method tidak valid.
407	Bayangan perangkat kosong.
408	Parameter reported berisi lebih dari 128 properti.
409	Konflik versi telah terjadi.
500	Pengecualian server telah terjadi.

Aplikasi mengubah status perangkat

Aplikasi mengirimkan status yang diinginkan ke bayangan perangkat dengan memanggil operasi UpdateDeviceShadow. Kemudian, IoT Platform mengirimkan file bayangan ke perangkat. Perangkat memperbarui statusnya berdasarkan file bayangan dan mengirimkan status terbaru ke bayangan perangkat.

Gambar berikut menunjukkan proses penerusan data.

Aplikasi memanggil operasi UpdateDeviceShadow untuk mengubah status bohlam. Dalam contoh ini, operasi dipanggil untuk mengubah nilai properti color menjadi green.
Kode berikut menunjukkan parameter ShadowMessage dalam permintaan API:
```
{
  "method": "update", 
  "state": {
    "desired": {
      "color": "green"
    }
  }, 
  "version": 2
}
```

Bayangan perangkat menerima permintaan pembaruan dan memperbarui file JSON.

{
  "state": {
    "reported": {
      "color": "red"
    }, 
    "desired": {
      "color": "green"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }, 
    "desired": {
      "color": {
        "timestamp": 1469564576
      }
    }
  }, 
  "timestamp": 1469564576, 
  "version": 2
}

Setelah bayangan perangkat menyelesaikan pembaruan, ia mengembalikan respons ke topik /shadow/get/a1PbRCF****/lightbulb. Informasi yang dikembalikan ditentukan oleh bayangan perangkat.

{
  "method": "control", 
  "payload": {
    "state": {
      "reported": {
        "color": "red"
      }, 
      "desired": {
        "color": "green"
      }
    }, 
    "metadata": {
      "reported": {
        "color": {
          "timestamp": 1469564492
        }
      }, 
      "desired": {
        "color": {
          "timestamp": 1469564576
        }
      }
    }
  }, 
  "version": 2, 
  "timestamp": 1469564576
}

Jika bohlam online dan telah berlangganan topik /shadow/get/a1PbRCF****/lightbulb, bohlam dapat menerima pesan.
Setelah bohlam menerima pesan, ia mengubah warnanya menjadi hijau berdasarkan nilai parameter desired dalam pesan.
Setelah bohlam memperbarui statusnya, ia mengirimkan status terbaru ke IoT Platform.
```
{
  "method": "update", 
  "state": {
    "reported": {
      "color": "green"
    }
  }, 
  "version": 3
}
```
Catatan Jika bohlam menentukan bahwa perintah telah kedaluwarsa berdasarkan timestamp, ia tidak melakukan pembaruan.
Setelah status terbaru dikirimkan ke IoT Platform, perangkat dan bayangan perangkat melakukan operasi berikut:
- Perangkat mengirimkan pesan ke topik /shadow/update/a1PbRCF****/lightbulb untuk menghapus properti desired. Kode berikut menunjukkan pesan:
```
{
  "method": "update", 
  "state": {
    "desired": "null"
  }, 
  "version": 4
}
```
- Bayangan perangkat memperbarui file JSON. Kode berikut menunjukkan file JSON setelah pembaruan:
```
{
  "state": {
    "reported": {
      "color": "green"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564577
      }
    }, 
    "desired": {
      "timestamp": 1469564576
    }
  }, 
  "version": 4
}
```

Perangkat meminta bayangan

Ketika aplikasi mengirimkan perintah, perangkat mungkin offline. Setelah perangkat online, perangkat dapat meminta bayangan.

Gambar berikut menunjukkan proses penerusan data.

Bohlam mengirimkan pesan berikut ke topik /shadow/update/a1PbRCF****/lightbulb untuk meminta status terbaru yang disimpan dalam bayangan perangkat:
```
{
"method": "get"
}
```

Setelah bayangan perangkat menerima pesan, bayangan perangkat mengirimkan status terbaru ke topik /shadow/get/a1PbRCF****/lightbulb. Bohlam mendapatkan status terbaru dengan berlangganan topik tersebut. Kode berikut menunjukkan pesan yang dikirim oleh bayangan perangkat ke perangkat:

{
  "method": "reply", 
  "payload": {
    "status": "success", 
    "state": {
      "reported": {
        "color": "red"
      }, 
      "desired": {
        "color": "green"
      }
    }, 
    "metadata": {
      "reported": {
        "color": {
          "timestamp": 1469564492
        }
      }, 
      "desired": {
        "color": {
          "timestamp": 1469564492
        }
      }
    }
  }, 
  "version": 2, 
  "timestamp": 1469564576
}

Perangkat menghapus properti bayangan

Jika perangkat berada dalam status terbaru, perangkat dapat mengirimkan perintah untuk menghapus properti dalam bayangan perangkat.

Gambar berikut menunjukkan proses penerusan data.

Perangkat mengirimkan pesan berikut ke topik /shadow/update/a1PbRCF****/lightbulb.

Dalam kode berikut, nilai parameter method adalah delete. Nilai propertinya adalah null.

Menghapus properti dalam bayangan.

{
  "method": "delete", 
  "state": {
    "reported": {
      "color": "null", 
      "temperature": "null"
    }
  }, 
  "version": 1
}

Hapus semua properti dalam bayangan.

{
  "method": "delete", 
  "state": {
    "reported": "null"
  }, 
  "version": 1
}