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 informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.
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. Terjadi kesalahan jika Anda mencoba mengirim lebih banyak pesan ke perangkat yang sama.
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 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 tersambung 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 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 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 selengkapnya, lihat Kedaluwarsa pesan (waktu hidup).
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. 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-ke-perangkat yang dikirim ke salah satu dari empat nilai berikut:
| Nilai properti ack | Perilaku |
|---|---|
| tidak ada | Default. Hub IoT tidak menghasilkan pesan umpan balik. |
| 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 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:
| Properti | Deskripsi |
|---|---|
| EnqueuedTime | Tanda waktu yang menunjukkan kapan pesan umpan balik diterima oleh hub. |
| UserId | {iot hub name} |
| ContentType | application/vnd.microsoft.iothub.feedback.json |
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:
| Properti | Deskripsi |
|---|---|
| enqueuedTimeUtc | Tanda waktu yang menunjukkan kapan hasil pesan terjadi. Misalnya, tanda waktu yang menunjukkan kapan hub menerima pesan umpan balik atau pesan asli kedaluwarsa. |
| originalMessageId | MessageId dari pesan cloud-ke-perangkat yang terkait dengan informasi umpan balik ini. |
| statusCode | Untai (karakter) yang diperlukan, digunakan dalam pesan tanggapan yang dihasilkan oleh hub IoT: Berhasil Kedaluwarsa DeliveryCountExceeded Ditolak Dihapus |
| deskripsi | Nilai string untuk StatusCode. |
| deviceId | DeviceId dari perangkat target pesan cloud-ke-perangkat yang terkait dengan umpan balik ini. |
| deviceGenerationId | DeviceGenerationId dari perangkat target pesan cloud-ke-perangkat yang terkait dengan umpan balik ini. |
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 penerimaan 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:
| Properti | Deskripsi | Rentang dan default |
|---|---|---|
| defaultTtlAsIso8601 | TTL default untuk pesan cloud-ke-perangkat | ISO_8601 interval hingga dua hari (minimal satu menit); default: satu 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 | ISO_8601 interval hingga dua hari (minimal satu menit); default: satu 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 lima 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.)
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 Azure IoT Hub SDK.
Untuk mencoba menerima pesan dari cloud ke perangkat, lihat tutorial Kirim dari cloud ke perangkat.