Sintaks kueri perutean pesan Azure IoT Hub

Artikel
03/18/2023

Perutean pesan memungkinkan pengguna untuk 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 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 informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat 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 dapat merutekan pesan, tetapi kueri tidak dapat 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 mengevaluasi ke nilai null atau tidak terdefinisi, ekspresi diperlakukan sebagai nilai palsu Boolean, dan menghasilkan kesalahan dalam IoT Hub merutekan log sumber daya. Sintaks kueri harus benar agar rute disimpan dan dievaluasi.

Kueri berdasarkan properti pesan

IoT Hub mendefinisikan format umum untuk semua olahpesan perangkat ke cloud untuk interoperabilitas di seluruh protokol. IoT Hub mengasumsikan representasi JSON pesan berikut. 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 IoT Hub pesan perangkat ke cloud 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, beberapa di antaranya dijelaskan dalam tabel berikut:

Properti	Jenis	Deskripsi
contentType	string	Pengguna menentukan tipe konten pesan. Untuk mengizinkan kueri pada isi pesan, nilai ini harus diatur ke `application/JSON`.
contentEncoding	string	Pengguna menentukan tipe pengkodean pesan. Jika properti contentType diatur ke `application/JSON`, maka nilai yang diizinkan adalah `UTF-8`, `UTF-16`, dan `UTF-32`.
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 ditetapkan oleh 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`.

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 akan mencarinya di properti aplikasi. Contoh berikut menunjukkan cara mengkueri properti sistem dan properti aplikasi.

Untuk mengkueri pada properti sistem contentEncoding:

$contentEncoding = 'UTF-8'

Untuk mengkueri 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 IoT Hub bahasa kueri 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 akan 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 di badan pesan. Misalnya, untuk memfilter saat 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

Perutean pesan memungkinkan Anda mengkueri pada perangkat kembar atau modul tag dan properti kembar , 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 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 kembar perangkat yang sesuai.

Ekspresi kueri kembar

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, , body$twin, 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.