Mengirim pesan cloud-ke-perangkat dari hub IoT

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

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk mengetahui informasi selengkapnya tentang IoT Hub tingkat standar dan dasar, lihat Cara memilih tingkat IoT Hub yang tepat.

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. Mencoba mengirim lebih banyak pesan ke perangkat yang sama akan menghasilkan kesalahan.

Siklus hidup pesan cloud-ke-perangkat

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

Grafik status siklus hidup ditampilkan dalam diagram berikut:

Cloud-to-device message life cycle

Saat layanan hub IoT mengirim pesan ke perangkat, layanan mengatur status pesan ke Masuk Antrean. Saat perangkat ingin menerima pesan, hub IoT mengunci pesan dengan mengatur status ke Tak 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. Perangkat yang terhubung melalui Protokol Message Queuing Telemetry Transport (MQTT) tidak dapat menolak pesan cloud-ke-perangkat.

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

Utas dapat gagal memproses pesan tanpa memberi tahu hub IoT. Dalam hal ini, pesan secara otomatis beralih dari status Tak Terlihat kembali ke status Masuk Antrean setelah waktu habis visibilitas (atau waktu habis mengunci). Nilai 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. Untuk informasi lebih lanjut, lihat Waktu untuk aktif.

Artikel Cara mengirim pesan cloud-ke-perangkat dengan IoT Hub menunjukkan cara mengirim pesan cloud-ke-perangkat dari cloud dan menerimanya di perangkat.

Perangkat biasanya menyelesaikan pesan cloud-ke-perangkat ketika hilangnya pesan tidak memengaruhi logika aplikasi. Contohnya mungkin ketika perangkat 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. Waktu ini diatur oleh salah satu dari berikut ini:

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

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 melakukannya dengan menyetel properti aplikasi iothub-ack di pesan cloud-ke-perangkat yang dikirim ke salah satu dari empat nilai berikut:

Nilai properti ack Perilaku
tidak ada Hub IoT tidak menghasilkan pesan tanggapan (perilaku default).
positif Jika pesan cloud-ke-perangkat mencapai status Selesai, hub IoT akan membuat pesan tanggapan.
negatif Jika pesan cloud-ke-perangkat mencapai status Pengiriman dihentikan, hub IoT akan membuat pesan tanggapan.
penuh Hub IoT menghasilkan pesan tanggapan dalam kedua kasus tersebut.

Jika nilai Ack adalah penuh, dan Anda tidak menerima pesan tanggapan, itu berarti pesan tanggapan 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:

Properti Deskripsi
EnqueuedTime Tanda waktu yang menunjukkan kapan pesan tanggapan diterima oleh hub
UserId {iot hub name}
ContentType application/vnd.microsoft.iothub.feedback.json

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

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

Properti Deskripsi
enqueuedTimeUtc Tanda waktu yang menunjukkan kapan hasil pesan terjadi (misalnya, hub menerima pesan tanggapan atau pesan asli kedaluwarsa)
originalMessageId MessageId dari pesan cloud-ke-perangkat yang terkait dengan informasi tanggapan ini
statusCode Untai (karakter) yang diperlukan, digunakan dalam pesan tanggapan yang dihasilkan oleh hub IoT:
Berhasil
Kedaluwarsa
DeliveryCountExceeded
Ditolak
Dihapus
deskripsi Nilai untai (karakter) untuk StatusCode
deviceId DeviceId perangkat target dari pesan cloud-ke-perangkat yang terkait dengan tanggapan ini
deviceGenerationId DeviceGenerationId perangkat target dari pesan cloud-ke-perangkat yang terkait dengan tanggapan ini

Agar pesan cloud-ke-perangkat dapat menghubungkan tanggapannya dengan pesan asli, layanan harus menentukan MessageId.

Isi pesan tanggapan ditampilkan dalam 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. Jika perangkat dihapus di periode singkat (seringkali kurang dari 1 detik) antara saat perangkat mengonfirmasi penerimaan pesan dan saat kumpulan tanggapan berikutnya disiapkan, tanggapan tidak akan 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:

Properti Deskripsi Rentang dan default
defaultTtlAsIso8601 TTL default untuk pesan cloud-ke-perangkat Interval ISO_8601 hingga 2 hari (minimal 1 menit); default: 1 jam
maxDeliveryCount Jumlah pengiriman maksimum untuk antrean cloud-ke-perangkat per-perangkat 1 sampai 100; default: 10
feedback.ttlAsIso8601 Retensi untuk pesan tanggapan terikat layanan Interval ISO_8601 hingga 2 hari (minimal 1 menit); default: 1 jam
feedback.maxDeliveryCount Jumlah pengiriman maksimum untuk antrean tanggapan 1 sampai 100; default: 10
feedback.lockDurationAsIso8601 Kunci durasi untuk antrean umpan balik Interval ISO_8601 dari 5 hingga 300 detik (minimal 5 detik); default: 60 detik.

Anda dapat mengatur opsi konfigurasi dengan salah satu cara berikut:

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

Set configuration options for cloud-to-device messaging in the portal

  • 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 menerima pesan cloud-ke-perangkat, lihat SDK Azure IoT.

Untuk mencoba menerima pesan dari cloud ke perangkat, lihat tutorial Kirim dari cloud ke perangkat.