Memahami olahpesan cloud-ke-perangkat dari hub IoT

Pesan cloud-ke-perangkat adalah pemberitahuan satu arah dari ujung belakang solusi Anda ke aplikasi perangkat. Untuk pembahasan tentang opsi cloud-ke-perangkat lainnya yang didukung oleh Azure IoT Hub, lihat Panduan komunikasi cloud-ke-perangkat.

Anda mengirim pesan dari cloud ke perangkat melalui titik akhir yang menghadap ke layanan, /messages/devicebound. Perangkat kemudian menerima pesan melalui titik akhir khusus perangkat, /devices/{deviceId}/messages/devicebound.

Untuk menargetkan setiap pesan cloud-ke-perangkat di satu perangkat, hub IoT Anda mengatur properti to ke /devices/{deviceId}/messages/devicebound.

Setiap antrean perangkat menampung, paling banyak, 50 pesan cloud-ke-perangkat. Kesalahan terjadi jika Anda mencoba mengirim lebih banyak pesan ke perangkat yang sama.

Artikel ini membahas konsep dan proses sekeliling pesan cloud-ke-perangkat. Untuk panduan tentang mengembangkan aplikasi yang menangani pesan cloud-ke-perangkat, lihat Mengirim dan menerima pesan cloud-to-device.

Siklus hidup pesan cloud-ke-perangkat

Untuk menjamin pengiriman pesan setidaknya sekali, hub IoT Anda menyimpan pesan cloud-ke-perangkat dalam antrean per-perangkat. Perangkat harus secara eksplisit mengakui penyelesaian pesan sebelum hub IoT menghapus pesan dari antrean. Pendekatan ini menjamin ketahanan terhadap konektivitas dan kegagalan perangkat.

Grafik status siklus hidup ditampilkan dalam diagram berikut:

Saat layanan hub IoT mengirim pesan ke perangkat, layanan mengatur status pesan ke Masuk Antrean. Saat utas perangkat siap menerima pesan, hub IoT mengunci pesan dengan mengatur status ke Tidak Terlihat. Status ini memungkinkan utas lain di perangkat untuk mulai menerima pesan lain. Saat utas perangkat menyelesaikan pemrosesan pesan, utas akan memberi tahu hub IoT dengan menyelesaikan pesan. Hub IoT kemudian menyetel status ke Selesai.

Perangkat juga dapat:

• Menolak pesan, yang menyebabkan hub IoT mengaturnya menjadi status Pengiriman dihentikan. Tidak ada antrean surat mati untuk memulihkan pesan ini. Perangkat yang tersambung melalui protokol Message Queuing Telemetry Transport (MQTT) tidak dapat menolak pesan cloud-to-device.

• Mengabaikan pesan, yang menyebabkan hub IoT mengembalikan pesan ke antrean, dengan status disetel ke Masuk Antrean. Perangkat yang terhubung melalui protokol MQTT tidak dapat meninggalkan pesan cloud-ke-perangkat.

Utas dapat gagal memproses pesan tanpa memberi tahu hub IoT. Dalam hal ini, pesan secara otomatis beralih dari status Tidak Terlihat kembali ke status Antrean setelah waktu visibilitas habis (atau mengunci waktu habis). Lama waktu habis ini adalah satu menit dan tidak dapat diubah.

Properti jumlah pengiriman maksimum di hub IoT menentukan berapa kali pesan dapat bertransisi antara status Masuk Antrean dan Tak Terlihat. Setelah jumlah transisi tersebut, hub IoT menyetel status pesan ke Pengiriman dihentikan. Demikian pula, hub IoT menyetel status pesan ke Pengiriman dihentikan setelah waktu habis masa berlakunya.

Perangkat biasanya menyelesaikan pesan cloud-ke-perangkat ketika hilangnya pesan tidak memengaruhi logika aplikasi. Contoh penyelesaian ini mungkin ketika perangkat telah mempertahankan konten pesan secara lokal atau telah berhasil menjalankan operasi. Pesan juga dapat membawa informasi sementara, yang jika hilang tidak akan berdampak pada fungsionalitas aplikasi. Terkadang, untuk tugas yang berjalan lama, Anda bisa:

• Menyelesaikan pesan cloud-ke-perangkat setelah perangkat mempertahankan deskripsi tugas di penyimpanan lokal.

• Memberi tahu solusi ujung akhir dengan satu atau lebih pesan perangkat-ke-cloud di berbagai tahap progres tugas.

Masa kedaluwarsa pesan (waktu aktif)

Setiap pesan cloud-ke-perangkat memiliki waktu kedaluwarsa. Kali ini diatur oleh salah satu opsi berikut:

• Properti ExpiryTimeUtc dalam layanan
• Hub IoT, dengan menggunakan waktu aktif default yang ditetapkan sebagai properti hub IoT

Untuk informasi selengkapnya tentang kedaluwarsa pesan, lihat Opsi konfigurasi cloud-ke-perangkat.

Cara umum untuk memanfaatkan masa berlaku pesan dan untuk menghindari pengiriman pesan ke perangkat yang terputus adalah dengan menyetel nilai waktu aktif yang singkat. Pendekatan ini mencapai hasil yang sama dengan mempertahankan status koneksi perangkat, tetapi lebih efisien. Saat Anda meminta pengakuan pesan, hub IoT memberi tahu Anda perangkat mana yang:

• Mampu menerima pesan.
• Tidak online atau gagal.

Memberikan tanggapan

Saat Anda mengirim pesan cloud-ke-perangkat, layanan dapat meminta pengiriman tanggapan per-pesan tentang status akhir pesan tersebut. Anda dapat mengonfigurasi umpan balik pesan dengan mengatur properti aplikasi iothub-ack di pesan cloud-to-device yang dikirim ke salah satu dari empat nilai berikut:

Jika nilai properti Ack diatur ke penuh, dan Anda tidak menerima pesan umpan balik, itu berarti bahwa pesan umpan balik telah kedaluwarsa. Layanan tidak dapat mengetahui apa yang terjadi pada pesan asli. Dalam praktiknya, layanan harus memastikan bahwa ia dapat memproses tanggapan sebelum kedaluwarsa. Waktu kedaluwarsa maksimum adalah dua hari, yang menyisakan waktu untuk menjalankan kembali layanan jika terjadi kegagalan.

Seperti yang dijelaskan di Titik Akhir, hub IoT memberikan tanggapan melalui titik akhir yang menghadap layanan, /messages/servicebound/feedback, sebagai pesan. Semantik untuk menerima tanggapan sama dengan pesan cloud-ke-perangkat. Bila memungkinkan, tanggapan pesan dikelompokkan dalam satu pesan, dengan format berikut:

Sistem akan mengirimkan umpan balik baik ketika batch mencapai 64 pesan, atau dalam 15 detik dari terakhir dikirim, mana yang lebih dulu.

Badannya berisi larik rekaman berseri JSON, masing-masing dengan properti berikut:

Layanan harus menentukan MessageId sehingga pesan cloud-ke-perangkat dapat menghubungkan umpan baliknya dengan pesan asli.

Isi pesan umpan balik ditampilkan dalam contoh kode berikut:

[
  {
    "originalMessageId": "0987654321",
    "enqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
    "statusCode": "Success",
    "description": "Success",
    "deviceId": "123",
    "deviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
  },
  {
    ...
  },
  ...
]

Tanggapan tertunda untuk perangkat yang dihapus

Saat perangkat dihapus, tanggapan yang tertunda juga akan dihapus. Tanggapan perangkat dikirim dalam batch. Jendela sempit, sering kali kurang dari satu detik, dapat terjadi antara ketika perangkat mengonfirmasi tanda terima pesan dan kapan batch umpan balik berikutnya disiapkan. Jika perangkat dihapus di jendela sempit tersebut, umpan balik tidak terjadi.

Anda dapat mengatasi perilaku ini dengan menunggu beberapa saat hingga tanggapan yang tertunda tiba sebelum menghapus perangkat Anda. Tanggapan pesan terkait harus dianggap hilang setelah perangkat dihapus.

Opsi konfigurasi cloud-ke-perangkat

Setiap hub IoT menampilkan opsi konfigurasi berikut untuk pengiriman pesan cloud-ke-perangkat:

Anda dapat mengatur opsi konfigurasi di portal Azure atau Azure CLI:

• Portal Microsoft Azure: Di bagian Setelan hub di hub IoT Anda, pilih Titik akhir bawaan dan buka Olahpesan cloud ke perangkat. (Menyetel properti feedback.maxDeliveryCount dan feedback.lockDurationAsIso8601 saat ini tidak didukung di portal Microsoft Azure.)

  

• Azure CLI: Gunakan perintah az iot hub update:

  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.defaultTtlAsIso8601=PT1H0M0S
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.maxDeliveryCount=10
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.feedback.ttlAsIso8601=PT1H0M0S
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.feedback.maxDeliveryCount=10
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.feedback.lockDurationAsIso8601=PT0H1M0S
  

Langkah berikutnya

Untuk informasi tentang SDK yang dapat Anda gunakan untuk menangani pesan cloud-ke-perangkat, lihat SDK Azure IoT Hub.

Untuk panduan tentang mengembangkan aplikasi yang menangani pesan cloud-ke-perangkat, lihat Mengirim dan menerima pesan cloud-to-device.