Bagikan melalui

Pengayaan pesan untuk pesan Hub IoT perangkat-ke-cloud

  • Artikel

Pengayaan pesan adalah kemampuan IoT hub untuk menstempel pesan dengan informasi tambahan sebelum pesan dikirim ke titik akhir yang ditentukan. Salah satu alasan untuk menggunakan pengayaan pesan adalah dengan menyertakan data yang dapat digunakan untuk menyederhanakan pemrosesan hilirisasi. Misalnya, memperkaya pesan telemetri perangkat dengan tag kembar perangkat dapat mengurangi beban pada pelanggan untuk melakukan panggilan API kembar perangkat untuk informasi ini.

Alur pengayaan pesan

Pengayaan pesan memiliki tiga elemen utama:

  • Nama atau kunci pengayaan

  • Nilai

  • Satu atau lebih titik akhir di mana pengayaan harus diterapkan.

Kunci berupa string. Kunci hanya dapat berisi karakter alfanumerik atau karakter khusus ini: tanda hubung (-), garis bawah (_), dan titik (.).

Nilai bisa berupa salah satu contoh berikut:

  • String statis apa pun. Nilai dinamis seperti kondisi, logika, operasi, dan fungsi tidak diperbolehkan. Contohnya, jika Anda mengembangkan aplikasi SaaS yang digunakan oleh beberapa konsumen, Anda dapat menetapkan pengidentifikasi kepada setiap konsumen dan membuat pengidentifikasi tersedia dalam aplikasi. Ketika aplikasi berjalan, IoT Hub akan menstempel pesan telemetri perangkat dengan pengidentifikasi konsumen, sehingga memungkinkan untuk memproses pesan secara berbeda untuk setiap konsumen.

  • Nama hub IoT yang mengirim pesan. Nilainya adalah $iothubname.

  • Informasi dari kembaran perangkat, seperti jalurnya. Contohnya adalah $twin.tags.field dan $twin.tags.latitude.

    Catatan

    Saat ini, hanya variabel $iothubname, $twin.tags, $twin.properties.desired, dan $twin.properties.reported yang didukung untuk pengayaan pesan. Selain itu, hanya jenis primitif yang didukung untuk pengayaan. Pesan tidak dapat diperkaya dengan jenis objek.

Pengayaan Pesan ditambahkan sebagai properti aplikasi ke pesan yang dikirim ke titik akhir yang dipilih.

Penerapan pengayaan

Pesan dapat berasal dari sumber data apa pun yang didukung oleh perutean pesan IoT Hub, termasuk contoh berikut:

  • telemetri perangkat, seperti suhu atau tekanan
  • notifikasi perubahan kembaran perangkat -- perubahan pada kembaran perangkat
  • peristiwa siklus hidup perangkat, seperti saat perangkat dibuat atau dihapus

Anda dapat menambahkan pengayaan ke pesan yang masuk ke titik akhir bawaan IoT hub, atau ke pesan yang dirutekan ke titik akhir kustom seperti penyimpanan Azure Blob, antrean Bus Layanan, atau topik Bus Layanan.

Anda juga dapat menambahkan pengayaan ke pesan yang diterbitkan ke Event Grid dengan terlebih dahulu membuat langganan Event Grid dengan jenis pesan telemetri perangkat. Berdasarkan langganan ini, kami akan membuat rute default di Azure IoT Hub untuk telemetri. Rute tunggal ini dapat menangani semua langganan Event Grid Anda. Anda kemudian dapat mengonfigurasi pengayaan untuk titik akhir dengan menggunakan tab Perkaya pesan di bagian Perutean pesan IoT Hub. Untuk informasi tentang bereaksi terhadap peristiwa dengan menggunakan Event Grid, lihat Iot Hub dan Event Grid.

Pengayaan diterapkan per titik akhir. Jika Anda menentukan lima pengayaan yang akan distempel untuk titik akhir tertentu, semua pesan yang masuk ke titik akhir tersebut distempel dengan lima pengayaan yang sama.

Pengayaan dapat dikonfigurasi menggunakan metode berikut:

Metode Perintah
Portal Portal Microsoft Azure Lihat tutorial pengayaan pesan
Azure CLI az iot hub message-enrichment
Azure PowerShell Add-AzIotHubMessageEnrichment

Penambahan pengayaan pesan tidak menambahkan latensi ke perutean pesan.

Untuk mencoba pengayaan pesan, lihat tutorial pengayaan pesan

Batasan

  • Anda dapat menambahkan hingga 10 pengayaan per IoT hub untuk hub tersebut di tingkat standar atau dasar. Untuk IoT hub di tingkat gratis, Anda dapat menambahkan hingga 2 pengayaan.

  • Dalam beberapa kasus, jika Anda memperkaya pesan dengan nilai yang diatur ke tag atau properti di perangkat kembar, nilai tersebut akan dicap dengan jalur kembar perangkat yang ditentukan. Misalnya, jika nilai pengayaan diatur ke $twin.tags.field, pesan akan dicap dengan string "$twin.tags.field", daripada nilai bidang dari kembarannya. Perilaku ini terjadi dalam kasus berikut:

    • IoT hub Anda berada di tingkat dasar. IoT Hub tingkat dasar tidak mendukung kembaran perangkat.

    • IoT hub Anda berada di tingkat standar, tetapi jalur kembar perangkat yang digunakan untuk nilai pengayaan tidak ada. Contohnya, jika nilai pengayaan diatur ke $twin.tags.location, dan kembaran perangkat tidak memiliki properti lokasi dengan tag, pesan distempel dengan string "$twin.tags.location".

    • IoT hub Anda berada di tingkat standar, tetapi jalur kembar perangkat yang digunakan untuk nilai pengayaan ditetapkan ke objek, bukan properti sederhana. Misalnya, jika nilai pengayaan diatur ke $twin.tags.location, dan properti lokasi di bawah tag adalah objek yang berisi properti turunan seperti {"building": 43, "room": 503}, pesan dicap dengan string "$twin.tags.location".

  • Pembaruan pada kembaran perangkat dapat memakan waktu hingga lima menit agar dicerminkan dalam nilai pengayaan yang sesuai.

  • Total ukuran pesan, termasuk pengayaan, tidak boleh melebihi 256 KB. Jika ukuran pesan melebihi 256 KB, IoT hub akan menghilangkan pesan. Anda dapat menggunakan metrik IoT Hub untuk mengidentifikasi dan men-debug kesalahan saat pesan dihilangkan. Contohnya, Anda dapat memantau metrik pesan telemetri yang tidak kompatibel (d2c.telemetry.egress.invalid) dalam metrik perutean. Untuk mempelajari selengkapnya, lihat Pantau IoT Hub.

  • Pengayaan pesan tidak berlaku untuk peristiwa perubahan kembaran digital.

  • Modul tidak mewarisi tag kembar dari perangkat yang sesuai. Pengayaan untuk pesan yang berasal dari modul perangkat (misalnya dari modul IoT Edge) harus menggunakan tag kembar yang disetel pada modul kembar.

Harga

Pengayaan pesan tersedia tanpa biaya tambahan. Saat ini, Anda akan dikenakan biaya saat mengirim pesan ke IoT hub. Anda hanya ditagih sekali untuk pesan tersebut, meskipun pesan menuju ke beberapa titik akhir.

Langkah berikutnya

Lihat artikel ini untuk informasi selengkapnya tentang merutekan pesan ke IoT hub: