Bagikan melalui

Membuat dan membaca pesan IoT Hub

Untuk mendukung interoperabilitas di seluruh protokol, IoT Hub menentukan serangkaian fitur olahpesan umum yang tersedia di semua protokol yang menghadap perangkat. Fitur-fitur ini dapat digunakan dalam 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 dan ukuran IoT Hub yang tepat untuk solusi Anda.

IoT Hub menerapkan olahpesan perangkat ke cloud menggunakan pola olah pesan streaming. Pesan perangkat-ke-cloud IoT Hub lebih menyerupai peristiwa Azure Event Hubs daripada pesan Azure Service Bus, di mana banyak peristiwa melewati layanan yang dapat dibaca oleh beberapa pembaca.

Pesan dari Azure IoT Hub terdiri dari:

  • Sekumpulan properti sistem yang telah ditentukan sebelumnya seperti yang dijelaskan nanti di artikel 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. Untuk informasi selengkapnya, lihat Berkomunikasi dengan hub IoT menggunakan protokol MQTT dan Berkomunikasi dengan hub IoT Anda dengan menggunakan Protokol AMQP.

Saat Anda mengirim pesan perangkat ke cloud menggunakan protokol HTTPS atau mengirim pesan cloud-ke-perangkat, nama dan nilai properti hanya dapat berisi karakter alfanumerik ASCII, ditambah ! # $ % & ' * + - . ^ _ ` | ~ .

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.

  • Pesan perangkat ke cloud dapat mencapai maksimal 256 KB dan dapat dikelompokkan dalam batch untuk mengoptimalkan pengiriman. Batch maksimum bisa mencapai 256 KB.

  • IoT Hub tidak mengizinkan pemartisian arbitrer. Pesan perangkat ke cloud dipartisi berdasarkan deviceId asalnya.

  • Seperti yang dijelaskan dalam Mengontrol akses ke IoT Hub dengan menggunakan MICROSOFT Entra ID, 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 pesan perangkat ke cloud IoT Hub.

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), berikan jenis konten dan set karakter yang sesuai untuk pesan tersebut.

Untuk menggunakan isi pesan Anda dalam kueri perutean IoT Hub, berikan objek JSON yang valid untuk pesan dan atur properti tipe konten pesan ke application/json;charset=utf-8.

Contoh berikut menunjukkan isi pesan yang valid dan dapat dirutekan:

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

Properti sistem pesan dari perangkat ke cloud

Properti Deskripsi Dapat Diatur oleh Pengguna? Kata kunci untuk
kueri perutean
ID pesan ID yang dapat diatur pengguna untuk pesan yang digunakan untuk pola balasan permintaan. Format: String peka terhadap huruf besar/kecil (panjang hingga 128 karakter) menggunakan karakter alfanumerik ASCII 7-bit ditambah - : . + % _ # * ? ! ( ) , = @ ; $ '. Ya ID Pesan
iothub-enqueuedtime Tanggal dan waktu IoT Hub menerima pesan perangkat ke cloud . Tidak enqueuedTime
user_id ID yang digunakan untuk menentukan asal pesan. Ya userId
device-id-koneksi-iothub ID yang diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi deviceId perangkat yang mengirim pesan. Tidak ID Perangkat Koneksi
iothub-koneksi-id modul ID yang diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi moduleId perangkat yang mengirim pesan. Tidak connectionModuleId
iothub-koneksi-otorisasi-id-generasi ID yang diatur oleh IoT Hub pada pesan perangkat ke cloud. Ini berisi connectionDeviceGenerationId (sesuai Properti identitas perangkat) dari perangkat yang mengirim pesan. Tidak IDGenerasiPerangkatKoneksi
metode-otorisasi-koneksi-iothub 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. Tidak connectionAuthMethod
iothub-aplikasi-iothub-waktu-pembuatan-utc Mengizinkan perangkat mengirim waktu pembuatan peristiwa saat mengirim data dalam batch. Ya waktu-pembuatan-UTC
waktu-pembuatan-iothub-utc Mengizinkan perangkat mengirim waktu pembuatan peristiwa saat mengirim satu pesan dalam satu waktu. Ya waktu-pembuatan-UTC
dt-dataschema Hub IoT menetapkan nilai ini pada pesan perangkat ke cloud. Ini berisi ID model perangkat yang disetel dalam koneksi perangkat. Tidak $dt-dataschema
dt-subject Nama komponen yang mengirim pesan perangkat ke cloud. Ya subjek-$dt

Properti aplikasi pesan dari perangkat ke cloud

Penggunaan umum properti aplikasi adalah mengirim tanda waktu dari perangkat menggunakan iothub-creation-time-utc properti untuk merekam saat perangkat mengirim pesan. Format tanda waktu ini harus UTC tanpa informasi zona waktu. Misalnya, 2021-04-21T11:30:16Z valid, tetapi 2021-04-21T11:30:16-07:00 tidak valid.

{
  "applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
  "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 awan-ke-perangkat

Properti Deskripsi Dapat Diatur oleh Pengguna?
ID pesan ID yang dapat diatur pengguna untuk pesan yang digunakan untuk pola balasan permintaan. Format: String peka terhadap huruf besar/kecil (panjang hingga 128 karakter) menggunakan karakter alfanumerik ASCII 7-bit ditambah - : . + % _ # * ? ! ( ) , = @ ; $ '. Ya
nomor urut Nomor (unik per antrian perangkat) yang ditetapkan oleh IoT Hub untuk setiap pesan dari cloud ke perangkat. Tidak
ke Tujuan yang ditentukan dalam pesan cloud-ke-perangkat . Tidak
waktu kedaluwarsa absolut Tanggal dan waktu kedaluwarsa pesan. Ya
id korelasi Properti string dalam pesan respons yang biasanya berisi MessageId dari permintaan, dalam pola permintaan-balas. Ya
user_id ID yang digunakan untuk menentukan asal pesan. Saat IoT Hub menghasilkan pesan, ID pengguna adalah nama hub IoT. 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.

Nama properti sistem Pusat Aktivitas Azure Storage Bus Layanan Event Grid
ID Pesan ID pesan ID Pesan ID Pesan ID pesan
ID pengguna user_id userId UserId user_id
ID perangkat koneksi device-id-koneksi-iothub ID Perangkat Koneksi device-id-koneksi-iothub device-id-koneksi-iothub
Modul koneksi ID iothub-koneksi-id modul connectionModuleId iothub-koneksi-id modul iothub-koneksi-id modul
Pembuatan id autentikasi koneksi iothub-koneksi-otorisasi-id-generasi IDGenerasiPerangkatKoneksi iothub-koneksi-otorisasi-id-generasi iothub-koneksi-otorisasi-id-generasi
Metode autentikasi koneksi metode-otorisasi-koneksi-iothub connectionAuthMethod metode-otorisasi-koneksi-iothub metode-otorisasi-koneksi-iothub
jenis konten jenis konten jenis konten JenisKonten iothub-content-type
pengodeanKonten pengkodean konten pengodeanKonten PengkodeanKonten pengkodean-konten-iothub
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime Tidak Berlaku iothub-enqueuedtime
CorrelationId id korelasi korelasiId CorrelationId id korelasi
dt-dataschema dt-dataschema dt-dataschema dt-dataschema dt-dataschema
dt-subject dt-subjek 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 badan dalam byte.
  • Ukuran dalam byte dari 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-pemalsuan

Untuk menghindari spoofing perangkat dalam pesan perangkat ke cloud, IoT Hub menambahkan cap pada semua pesan dengan properti berikut:

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • metode 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

  • Last updated on