Sintaks kueri perutean pesan IoT Hub

2025-05-27

Perutean pesan memungkinkan pengguna merutekan berbagai jenis data, termasuk pesan telemetri perangkat, peristiwa siklus hidup perangkat, dan peristiwa perubahan kembar perangkat, 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 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 informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat dan ukuran IoT Hub yang tepat untuk solusi Anda.

Perutean pesan memungkinkan Anda untuk menanyakan properti pesan dan isi pesan serta tag kembar perangkat dan properti kembar perangkat. Jika isi pesan tidak dalam format JSON, perutean pesan masih bisa mengalihkan pesan, tetapi kueri tidak bisa diterapkan ke isi pesan. Kueri digambarkan sebagai ekspresi Boolean di mana, jika benar, kueri berhasil dan merutekan semua data masuk; jika tidak, kueri gagal dan data masuk tidak dirutekan. Jika ekspresi dievaluasi menjadi nilai null atau tidak terdefinisi, itu diperlakukan sebagai nilai false dalam Boolean, dan akan menghasilkan kesalahan dalam log sumber daya perutean IoT Hub. Sintaks kueri harus benar agar rute disimpan dan dievaluasi.

Kueri berdasarkan properti pesan

IoT Hub mendefinisikan format umum untuk semua pesan perangkat-ke-cloud untuk interoperabilitas di seluruh protokol. IoT Hub mengasumsikan representasi JSON berikut dari pesan. Properti sistem ditambahkan untuk semua pengguna dan mengidentifikasi konten pesan. Pengguna dapat secara selektif menambahkan properti aplikasi ke pesan. Kami menyarankan untuk menggunakan nama properti yang unik karena pesan dari perangkat ke cloud di IoT Hub tidak membedakan antara huruf besar dan huruf kecil. Misalnya, jika Anda memiliki beberapa properti dengan nama yang sama, IoT Hub hanya 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, beberapa di antaranya dijelaskan dalam tabel berikut:

Harta benda	Tipe	Deskripsi
jenis konten	benang	Pengguna menentukan tipe konten pesan. Untuk mengizinkan kueri pada isi pesan, nilai ini harus diatur ke `application/JSON`.
pengkodeanKonten	benang	Pengguna menentukan tipe pengkodean pesan. Jika properti contentType diatur ke `application/JSON`, maka nilai yang diizinkan adalah `UTF-8`, `UTF-16`, dan `UTF-32`.
device-id-koneksi-iothub	benang	IoT Hub menetapkan nilai ini, yang mengidentifikasi ID perangkat. Untuk membuat kueri, gunakan `$connectionDeviceId`.
iothub-hubungan-modul-id	benang	IoT Hub menetapkan nilai ini, yang mengidentifikasi ID modul edge. Untuk membuat kueri, gunakan `$connectionModuleId`.
iothub-enqueuedtime	benang	IoT Hub menetapkan nilai ini, yang mewakili waktu aktual antrean pesan di UTC. Untuk membuat kueri, gunakan `$enqueuedTime`.
dt-dataschema	benang	IoT Hub menetapkan nilai ini pada pesan perangkat-ke-cloud. Ini berisi ID model perangkat yang disetel dalam koneksi perangkat. Untuk membuat kueri, gunakan `$dt-dataschema`.
dt-subject	benang	Nama komponen yang mengirim pesan perangkat ke cloud. Untuk membuat kueri, gunakan `$dt-subject`.

Untuk informasi selengkapnya tentang properti sistem lain yang tersedia, lihat Membuat dan membaca pesan IoT Hub.

Properti aplikasi

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

Ekspresi kueri properti pesan

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 IoT Hub terlebih dahulu mencarinya di properti sistem, dan jika tidak ditemukan, maka cari di properti aplikasi. Contoh berikut menunjukkan cara mengkueri properti sistem dan properti aplikasi.

Untuk mengkueri konten properti sistemEncoding:

$contentEncoding = 'UTF-8'

Untuk mengajukan kueri pada properti aplikasi processingPath:

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 disediakan di bagian Ekspresi dan kondisi dari bahasa kueri IoT Hub untuk perangkat dan modul kembar, pekerjaan, dan perutean pesan.

Kueri berdasarkan isi pesan

Untuk mengaktifkan kueri pada isi pesan, pesan harus dalam format JSON dan dikodekan dalam UTF-8, UTF-16 atau UTF-32. Properti contentType sistem harus application/JSON. Properti contentEncoding sistem harus menjadi salah satu nilai pengodean UTF yang didukung oleh properti sistem tersebut. Jika properti sistem ini tidak ditentukan, IoT Hub tidak mengevaluasi ekspresi kueri pada isi pesan.

Contoh JavaScript berikut menunjukkan cara membuat pesan dengan isi 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);
});

Untuk sampel pengodean pesan di C#, lihat HubRoutingSample yang disediakan di Microsoft Azure IoT SDK untuk .NET. Sampel ini sama dengan yang digunakan dalam tutorial perutean pesan. File Program.cs juga memiliki metode bernama ReadOneRowFromFile, yang membaca salah satu file yang dikodekan, mendekodenya, dan menulisnya kembali sebagai ASCII sehingga Anda dapat membacanya.

Ekspresi kueri isi pesan

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 dapat menggabungkan referensi isi dengan referensi properti sistem pesan atau referensi properti aplikasi pesan. Misalnya, contoh berikut 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'

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 mengembalikan undefined:

$body[0] = 'Feb'

Untuk memfilter payload pemberitahuan kembar berdasarkan apa yang berubah, jalankan kueri Anda pada isi 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)

Kueri berdasarkan perangkat atau modul kembar

Pengarahan pesan memungkinkan Anda untuk mengkueri tag dan properti dari kembar perangkat atau kembar modul, yang merupakan objek JSON. Sampel berikut mengilustrasikan perangkat kembar dengan tag dan properti:

{
    "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 duplikat dari perangkat yang terkait. Kueri kembar untuk pesan yang berasal dari modul perangkat (misalnya, dari modul IoT Edge) dijalankan pada kembar modul dan bukan pada kembar perangkat yang bersangkutan.

Ekspresi kueri ganda

Kueri pada perangkat kembar atau modul kembar perlu diawali dengan $twin. Ekspresi kueri Anda juga dapat menggabungkan tag kembar atau referensi properti dengan referensi isi, referensi properti sistem pesan, atau referensi properti aplikasi pesan. Sebaiknya gunakan nama unik dalam tag dan properti karena kueri tidak peka huruf besar/kecil. Rekomendasi ini berlaku untuk kembar perangkat dan kembar modul. Kami juga menyarankan agar Anda menghindari penggunaan twin, , $twinbody, atau $body sebagai nama properti. Misalnya, contoh berikut 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.

Bagikan melalui