Membuat dan membaca pesan IoT Hub
Untuk mendukung interoperabilitas yang mulus di seluruh protokol, IoT Hub mendefinisikan serangkaian fitur olahpesan umum yang tersedia di semua protokol yang menghadap perangkat. Ini dapat digunakan di perutean pesan perangkat-ke-cloud dan pesan cloud-ke-perangkat.
Catatan
Beberapa fitur yang disebutkan dalam artikel ini, seperti pesan cloud-ke-perangkat, kembar perangkat, dan manajemen perangkat, 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.
IoT Hub menerapkan olahpesan perangkat ke cloud menggunakan pola olah pesan streaming. Pesan device-to-cloud IoT Hub lebih mirip peristiwa Azure Event Hubs daripada pesan Azure Service Bus karena terdapat volume tinggi peristiwa yang melewati layanan yang dapat dibaca oleh banyak pembaca.
Pesan Azure IoT Hub terdiri dari:
Sekumpulan properti sistem yang telah ditentukan seperti yang tercantum di bawah ini.
Sekumpulan properti aplikasi. Kamus properti string yang dapat didefinisikan dan diakses aplikasi, tanpa perlu mendeserialisasi isi pesan. IoT Hub tidak pernah mengubah properti ini.
Isi pesan, yang dapat berupa semua jenis data.
Setiap protokol perangkat menerapkan properti pengaturan dengan cara yang berbeda. Silakan lihat panduan pengembang MQTT dan AMQP terkait untuk detailnya.
Nama dan nilai properti hanya dapat berisi karakter alfanumerik ASCII, plus {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} saat Anda mengirim pesan perangkat ke cloud menggunakan protokol HTTPS atau mengirim pesan cloud ke perangkat.
Olahpesan perangkat ke cloud dengan IoT Hub memiliki karakteristik berikut:
Pesan perangkat ke cloud tahan lama dan dipertahankan di titik akhir pesan/peristiwa default hub IoT selama maksimal tujuh hari.
Ukuran pesan perangkat ke cloud maksimal 256 KB, dan dapat dikelompokkan dalam batch guna mengoptimalkan pengiriman. Batch maksimum bisa mencapai 256 KB.
IoT Hub tidak mengizinkan pemartisian arbiter. Pesan perangkat ke cloud dipartisi berdasarkan deviceId asalnya.
Seperti yang dijelaskan dalam Akses kontrol IoT Hub, IoT Hub memungkinkan autentikasi per perangkat dan kontrol akses.
Anda dapat memberi stempel pesan dengan informasi yang masuk ke dalam properti aplikasi. Untuk informasi selengkapnya, lihat pengayaan pesan.
Untuk informasi selengkapnya tentang cara mengodekan dan mendekode pesan yang dikirim menggunakan protokol berbeda, lihat Azure IoT SDK.
Catatan
Setiap protokol IoT Hub menyediakan properti jenis konten pesan yang dihormati saat merutekan data ke titik akhir kustom. Agar data Anda ditangani dengan benar di tujuan (misalnya, JSON diperlakukan sebagai string yang dapat diurai alih-alih data biner yang dikodekan Base64), Anda harus memberikan jenis konten dan set karakter yang sesuai untuk pesan tersebut.
Untuk menggunakan isi pesan Anda dalam kueri perutean IoT Hub, Anda harus menyediakan objek JSON yang valid untuk pesan dan mengatur properti jenis konten pesan ke application/json;charset=utf-8.
Isi pesan yang valid dan dapat dirutekan mungkin terlihat seperti berikut ini:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Properti sistem pesan IoT Hub D2C
| Properti | Deskripsi | Dapat Diatur Pengguna? | Kata kunci untuk kueri routeran |
|---|---|---|---|
| message-id | ID yang dapat diatur pengguna untuk pesan yang digunakan untuk pola balasan permintaan. Format: String peka huruf besar/kecil (panjang maksimal 128 karakter) karakter alfanumerik 7-bit ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Ya | messageId |
| iothub-enqueuedtime | Tanggal dan waktu pesan Perangkat ke Cloud diterima oleh IoT Hub. | No | enqueuedTime |
| user_id | ID yang digunakan untuk menentukan asal pesan. Saat pesan dibuat oleh IoT Hub, pesan diatur ke {iot hub name}. |
Ya | userId |
| iothub-connection-device-id | ID yang diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi deviceId perangkat yang mengirim pesan. | No | connectionDeviceId |
| iothub-connection-module-id | ID yang diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi moduleId perangkat yang mengirim pesan. | No | connectionModuleId |
| iothub-connection-auth-generation-id | ID yang diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi connectionDeviceGenerationId (sesuai Properti identitas perangkat) dari perangkat yang mengirim pesan. | No | connectionDeviceGenerationId |
| iothub-connection-auth-method | Metode autentikasi yang ditetapkan oleh IoT Hub pada pesan perangkat ke cloud. Properti ini berisi informasi tentang metode otentikasi yang digunakan untuk mengautentikasi perangkat yang mengirim pesan. | No | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Mengizinkan perangkat mengirim waktu pembuatan peristiwa saat mengirim data dalam batch. | Ya | creation-time-utc |
| iothub-creation-time-utc | Mengizinkan perangkat mengirim waktu pembuatan peristiwa saat mengirim satu pesan dalam satu waktu. | Ya | creation-time-utc |
| dt-dataschema | Nilai ini diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi ID model perangkat yang diatur dalam koneksi perangkat. | No | $dt-dataschema |
| dt-subject | Nama komponen yang mengirim pesan perangkat ke cloud. | Ya | $dt-subject |
Properti Aplikasi pesan IoT Hub D2C
Penggunaan umum properti aplikasi adalah mengirim tanda waktu dari perangkat menggunakan properti iothub-creation-time-utc yang akan direkam merekam saat pesan dikirim oleh perangkat. Format tanda waktu ini harus UTC tanpa informasi zona waktu. Misalnya, 2021-04-21T11:30:16Z valid, 2021-04-21T11:30:16-07:00 tidak valid:
{
"applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
Properti sistem pesan IoT Hub C2D
| Properti | Deskripsi | Dapat Diatur Pengguna? |
|---|---|---|
| message-id | ID yang dapat diatur pengguna untuk pesan yang digunakan untuk pola balasan permintaan. Format: String peka huruf besar/kecil (panjang maksimal 128 karakter) karakter alfanumerik 7-bit ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Ya |
| sequence-number | Nomor (unik per perangkat) yang ditetapkan oleh IoT Hub untuk setiap pesan cloud ke perangkat. | No |
| ke | Tujuan yang ditentukan dalam pesan Cloud ke Perangkat. | No |
| absolute-expiry-time | Tanggal dan waktu kedaluwarsa pesan. | Ya |
| correlation-id | Properti string dalam pesan respons yang biasanya berisi MessageId permintaan, dalam pola balasan permintaan. | Ya |
| user_id | ID yang digunakan untuk menentukan asal pesan. Saat pesan dibuat oleh IoT Hub, pesan diatur ke {iot hub name}. |
Ya |
| iothub-ack | Generator pesan umpan balik. Properti ini digunakan dalam pesan cloud ke perangkat untuk meminta IoT Hub menghasilkan pesan umpan balik sebagai akibat dari penggunaan pesan oleh perangkat. Kemungkinan nilai: tidak ada (default): tidak ada pesan umpan balik yang dihasilkan, positif: menerima pesan umpan balik jika pesan selesai, negatif: menerima pesan umpan balik jika pesan kedaluwarsa (atau jumlah pengiriman maksimum tercapai) tanpa diselesaikan oleh perangkat, atau penuh: positif dan negatif. | Ya |
Nama Properti Sistem
Nama properti sistem bervariasi berdasarkan titik akhir tempat tujuan pesan dirutekan. Lihat tabel di berikut untuk mengetahui detail tentang nama-nama ini.
| Nama properti sistem | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| ID Pesan | message-id | messageId | MessageId | message-id |
| ID pengguna | user_id | userId | UserId | user_id |
| ID perangkat koneksi | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| ID modul koneksi | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| ID pembuatan autentikasi koneksi | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Metode autentikasi koneksi | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | tipekonten | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | T/A | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Ukuran pesan
IoT Hub mengukur ukuran pesan dengan cara agnostik protokol, dengan mempertimbangkan payload aktual saja. Ukuran dalam byte dihitung sebagai jumlah dari nilai berikut:
- Ukuran isi dalam byte.
- Ukuran dalam byte untuk semua nilai properti sistem pesan.
- Ukuran dalam byte untuk semua nama dan nilai properti pengguna.
Nama dan nilai properti terbatas pada karakter ASCII, sehingga panjang string sama dengan ukuran dalam byte.
Properti anti-spoofing
Untuk menghindari spoofing perangkat dalam pesan perangkat ke cloud, IoT Hub memberi stempel pada semua pesan dengan properti berikut:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
Dua properti pertama berisi deviceId dan generationId dari perangkat asal, sesuai Properti identitas perangkat.
Properti iothub-connection-auth-method berisi objek seri JSON, dengan properti berikut:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Langkah berikutnya
- Untuk informasi tentang batas ukuran pesan di IoT Hub, lihat kuota dan pembatasan IoT Hub.
- Untuk mempelajari cara membuat dan membaca pesan IoT Hub dalam berbagai bahasa pemrograman, lihat Mulai cepat.
- Untuk mempelajari tentang struktur peristiwa non-telemetri yang dihasilkan oleh IoT Hub, lihat skema peristiwa non-telemetri IoT Hub.