Sintaks kueri perutean pesan Azure IoT Hub

Artikel
05/06/2022
6 menit untuk membaca

Perutean pesan memungkinkan pengguna untuk merutekan berbagai jenis data yaitu, pesan telemetri perangkat, peristiwa siklus hidup perangkat, dan peristiwa perubahan perangkat kembar ke berbagai titik akhir. Anda juga dapat menerapkan kueri kaya ke data ini sebelum merutekannya untuk menerima data yang penting bagi Anda. Artikel ini menguraikan bahasa kueri perutean pesan Azure IoT Hub, dan menyediakan beberapa pola kueri umum.

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 mengetahui informasi selengkapnya tentang tingkat IoT Hub standar dan dasar, lihat Cara memilih tingkat IoT Hub yang tepat.

Perutean pesan memungkinkan Anda untuk menanyakan properti pesan dan isi pesan serta tag kembar perangkat dan properti kembar perangkat. Jika isi pesan bukan JSON, perutean pesan masih dapat merutekan pesan, tetapi kueri tidak dapat diterapkan ke isi pesan. Kueri digambarkan sebagai ekspresi Boolean di mana Boolean asli membuat kueri berhasil yang merutekan semua data yang masuk, dan Boolean palsu gagal dalam kueri dan tidak ada data yang dirutekan. Jika ekspresi mengevaluasi ke null atau tidak terdefinisi, ekspresi tersebut diperlakukan sebagai palsu dan kesalahan akan dihasilkan di Azure IoT Hub merutekan log sumber daya jika terjadi kegagalan. Sintaks kueri harus benar agar rute disimpan dan dievaluasi.

Kueri perutean pesan berdasarkan properti pesan

Azure IoT Hub mendefinisikan format umum untuk semua olahpesan perangkat ke cloud untuk interoperabilitas lintas protokol. Pesan Azure IoT Hub mengasumsikan representasi JSON berikut dari pesan tersebut. Properti sistem ditambahkan untuk semua pengguna dan mengidentifikasi konten pesan. Pengguna dapat secara selektif menambahkan properti aplikasi ke pesan. Sebaiknya gunakan nama properti unik karena pesan perangkat ke cloud Azure IoT Hub tidak peka huruf besar/kecil. Misalnya, jika Anda memiliki beberapa properti dengan nama yang sama, Azure IoT Hub hanya akan mengirim salah satu properti.

{ 
  "message": { 
    "systemProperties": { 
      "contentType": "application/json", 
      "contentEncoding": "UTF-8", 
      "iothub-message-source": "deviceMessages", 
      "iothub-enqueuedtime": "2017-05-08T18:55:31.8514657Z" 
    }, 
    "appProperties": { 
      "processingPath": "{cold | warm | hot}", 
      "verbose": "{true, false}", 
      "severity": 1-5, 
      "testDevice": "{true | false}" 
    }, 
    "body": "{\"Weather\":{\"Temperature\":50}}" 
  } 
}

Properti sistem

Properti sistem membantu mengidentifikasi konten dan sumber pesan.

Properti	Jenis	Deskripsi
contentType	string	Pengguna menentukan tipe konten pesan. Untuk memperbolehkan kueri pada isi pesan, nilai ini harus diatur aplikasi/JSON.
contentEncoding	string	Pengguna menentukan tipe pengkodean pesan. Nilai yang diizinkan adalah UTF-8, UTF-16, UTF-32 jika contentType disetel ke application/JSON.
iothub-connection-device-id	string	Nilai ini ditetapkan oleh Azure IoT Hub dan mengidentifikasi ID perangkat. Untuk membuat kueri, gunakan `$connectionDeviceId`.
iothub-connection-module-id	string	Nilai ini ditetapkan oleh Azure IoT Hub dan mengidentifikasi ID modul tepi. Untuk membuat kueri, gunakan `$connectionModuleId`.
iothub-enqueuedtime	string	Nilai ini ditetapkan oleh Azure IoT Hub dan mewakili waktu aktual untuk mengantri pesan di UTC. Untuk membuat kueri, gunakan `enqueuedTime`.
dt-dataschema	string	Nilai ini diatur oleh Azure IoT Hub pada pesan perangkat ke cloud. Ini berisi ID model perangkat yang diatur dalam sambungan perangkat. Untuk membuat kueri, gunakan `$dt-dataschema`.
dt-subjek	string	Nama komponen yang mengirim pesan perangkat ke cloud. Untuk membuat kueri, gunakan `$dt-subject`.

Seperti yang dijelaskan dalam Pesan Azure IoT Hub, ada properti sistem tambahan dalam pesan. Selain properti di atas pada tabel sebelumnya, Anda juga dapat membuat kueri connectionDeviceId, connectionModuleId.

Properti aplikasi

Properti aplikasi adalah untai (karakter) yang ditentukan pengguna yang dapat ditambahkan ke pesan. Bidang-bidang ini bersifat opsional.

Ekspresi kueri

Kueri pada properti sistem pesan harus diawali dengan simbol $. Kueri pada properti aplikasi diakses dengan namanya dan tidak boleh diawali dengan simbol $. Jika nama properti aplikasi dimulai dengan $, maka Azure IoT Hub akan mencarinya di properti sistem, dan tidak ditemukan, maka itu akan terlihat di properti aplikasi. Contohnya:

Untuk menanyakan konten properti sistemEncoding

$contentEncoding = 'UTF-8'

Untuk melakukan kueri pada pemrosesan properti aplikasiPath:

processingPath = 'hot'

Untuk menggabungkan kueri ini, Anda dapat menggunakan ekspresi dan fungsi Boolean:

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

Daftar lengkap operator dan fungsi yang didukung diperlihatkan dalam Ekspresi dan kondisi.

Kueri perutean pesan berdasarkan isi pesan

Untuk mengaktifkan kueri pada isi pesan, pesan harus dalam JSON yang dikodekan dalam UTF-8, UTF-16 atau UTF-32. contentType harus disetel ke application/JSON dan contentEncoding ke salah satu pengkodean UTF yang didukung di properti sistem. Jika properti ini tidak ditentukan, Azure IoT Hub tidak akan mengevaluasi ekspresi kueri pada isi pesan.

Contoh berikut menunjukkan cara membuat pesan dengan badan JSON yang dibentuk dan dikodekan dengan benar:

var messageBody = JSON.stringify(Object.assign({}, {
    "Weather": {
        "Temperature": 50,
        "Time": "2017-03-09T00:00:00.000Z",
        "PrevTemperatures": [
            20,
            30,
            40
        ],
        "IsEnabled": true,
        "Location": {
            "Street": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA"
        },
        "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            },
            {
                "Month": "Jan",
                "Temperature": 30
            }
        ]
    }
}));

// Encode message body using UTF-8  
var messageBytes = Buffer.from(messageBody, "utf8");

var message = new Message(messageBytes);

// Set message body type and content encoding 
message.contentEncoding = "utf-8";
message.contentType = "application/json";

// Add other custom application properties   
message.properties.add("Status", "Active");

deviceClient.sendEvent(message, (err, res) => {
    if (err) console.log('error: ' + err.toString());
    if (res) console.log('status: ' + res.constructor.name);
});

Catatan

Contoh ini menunjukkan cara menangani pengkodean isi dalam javascript. Jika Anda ingin melihat sampel di C#, unduh Sampel Azure IoT C#. Buka file zip master.zip. File Program.cs solusi Visual Studio SimulatedDevice menunjukkan cara menyandikan dan mengirimkan pesan ke Azure IoT Hub. Ini adalah sampel yang sama yang digunakan untuk menguji perutean pesan, seperti yang dijelaskan dalam tutorial Perutean Pesan. Di bagian bawah Program.cs, terdapat juga metode untuk membaca di salah satu file yang dikodekan, mendekodekannya, dan menulisnya kembali sebagai ASCII sehingga Anda dapat membacanya.

Ekspresi kueri

Kueri pada isi pesan perlu dia awali dengan $body. Anda bisa menggunakan referensi isi, referensi susunan isi, atau beberapa referensi isi dalam ekspresi kueri. Ekspresi kueri Anda juga bisa menggabungkan referensi isi dengan properti sistem pesan, dan referensi properti aplikasi pesan. Misalnya, berikut ini adalah semua ekspresi kueri yang valid:

$body.Weather.HistoricalData[0].Month = 'Feb'

$body.Weather.Temperature = 50 AND $body.Weather.IsEnabled

length($body.Weather.Location.State) = 2

$body.Weather.Temperature = 50 AND processingPath = 'hot'

Catatan

Untuk memfilter payload pemberitahuan kembar berdasarkan apa yang berubah, jalankan kueri Anda di badan pesan. Misalnya, untuk memfilter ketika ada perubahan sendFrequency properti yang diinginkan dan nilainya lebih besar dari 10:

$body.properties.desired.telemetryConfig.sendFrequency > 10

Untuk memfilter pesan yang berisi perubahan properti, apa pun nilai properti, Anda dapat menggunakan is_defined() fungsi (saat nilainya adalah tipe primitif):

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

Catatan

Anda dapat menjalankan kueri dan fungsi hanya pada properti dalam referensi isi. Anda tidak dapat menjalankan kueri atau fungsi pada seluruh referensi isi. Misalnya, kueri berikut tidak didukung dan akan kembali undefined:

$body[0] = 'Feb'

Kueri perutean pesan berdasarkan perangkat kembar

Perutean pesan memungkinkan Anda untuk membuat kueri pada tag dan properti Perangkat Kembar, yang merupakan objek JSON. Kueri pada modul twin juga didukung. Sampel tag dan properti Perangkat Kembar diperlihatkan di bawah ini.

{
    "tags": { 
        "deploymentLocation": { 
            "building": "43", 
            "floor": "1" 
        } 
    }, 
    "properties": { 
        "desired": { 
            "telemetryConfig": { 
                "sendFrequency": "5m" 
            }, 
            "$metadata" : {...}, 
            "$version": 1 
        }, 
        "reported": { 
            "telemetryConfig": { 
                "sendFrequency": "5m", 
                "status": "success" 
            },
            "batteryLevel": 55, 
            "$metadata" : {...}, 
            "$version": 4 
        } 
    } 
}

Catatan

Modul tidak mewarisi tag kembar dari perangkat yang sesuai. Kueri kembar untuk pesan yang berasal dari modul perangkat (misalnya dari modul IoT Edge) kueri terhadap modul kembar dan bukan kembaran perangkat yang sesuai.

Ekspresi kueri

Kueri pada perangkat atau modul kembar harus diawali dengan $twin. Ekspresi kueri Anda juga bisa menggabungkan tag kembar atau referensi properti dengan referensi isi, properti sistem pesan, dan/atau referensi properti aplikasi pesan. Sebaiknya gunakan nama unik dalam tag dan properti karena kueri tidak peka huruf besar/kecil. Ini berlaku untuk perangkat dan modul yang kembar. Juga jangan menggunakan twin, $twin, body, atau $body, sebagai nama properti. Misalnya, berikut ini adalah semua ekspresi kueri yang valid:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Batasan

Kueri perutean tidak mendukung penggunaan spasi putih atau salah satu karakter berikut dalam nama properti, jalur isi pesan, atau jalur kembar perangkat/modul: ()<>@,;:\"/?={}.

Langkah berikutnya

Pelajari tentang perutean pesan.
Coba tutorial perutean pesan.