Bahasa kueri Hub IoT untuk perangkat dan modul kembar, pekerjaan, dan perutean pesan
IoT Hub menyediakan bahasa seperti SQL yang kuat untuk mengambil informasi mengenai devive twins, module twins, tugas, dan perutean pesan. Artikel ini menyajikan:
- Pengenalan fitur utama bahasa kueri IoT Hub, dan
- Deskripsi terperinci tentang bahasa tersebut. Detail tentang bahasa kueri untuk perutean pesan, lihat kueri dalam perutean pesan.
Untuk contoh tertentu, lihat Kueri untuk perangkat dan modul kembar atau Kueri untuk pekerjaan.
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.
Menjalankan kueri IoT Hub
Anda dapat menjalankan kueri terhadap hub IoT Anda langsung di portal Azure.
- Masuk ke portal Azure dan navigasikan ke IoT hub Anda.
- Pilih Kueri dari bagian Manajemen perangkat pada menu navigasi.
- Masukkan kueri Anda di kotak teks dan pilih Jalankan kueri.
Anda juga dapat menjalankan kueri dalam aplikasi Anda menggunakan SDK layanan Azure IoT dan API layanan.
Misalnya kode yang menerapkan kueri IoT Hub, lihat bagian Contoh kueri dengan SDK layanan.
Untuk tautan ke halaman referensi dan sampel SDK, lihat Azure IoT SDK.
Dasar-dasar kueri IoT Hub
Setiap kueri IoT Hub terdiri dari klausa SELECT dan FROM, dengan klausa WHERE dan GROUP BY opsional.
Kueri dijalankan pada kumpulan dokumen JSON, misalnya kembar perangkat. Klausa FROM menunjukkan koleksi dokumen yang akan diulang pada (baik perangkat, devices.modules, atau devices.jobs).
Kemudian, filter dalam klausa WHERE diterapkan. Dengan agregasi, hasil langkah ini dikelompokkan seperti yang ditentukan dalam klausa GROUP BY. Untuk setiap grup, baris dihasilkan seperti yang ditentukan dalam klausa SELECT.
SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]
Klausul SELECT
Klausa SELECT <select_list> diperlukan di setiap kueri IoT Hub. Ini menentukan nilai apa yang diambil dari kueri. Ini menentukan nilai JSON yang akan digunakan untuk menghasilkan objek JSON baru. Untuk setiap elemen subset yang difilter (dan dikelompokkan secara opsional) dari koleksi FROM, fase proyeksi menghasilkan objek JSON baru. Objek ini dibuat dengan nilai yang ditentukan dalam klausa SELECT.
Contohnya:
Mengembalikan semua nilai
SELECT *Mengembalikan properti tertentu
SELECT DeviceID, LastActivityTimeMengagregasi hasil kueri untuk mengembalikan hitungan
SELECT COUNT() as TotalNumber
Saat ini, klausa pemilihan yang berbeda dari SELECT hanya didukung dalam kueri agregat pada kembar perangkat.
Sintaks berikut adalah tata bahasa klausa SELECT:
SELECT [TOP <max number>] <projection list>
<projection_list> ::=
'*'
| <projection_element> AS alias [, <projection_element> AS alias]+
<projection_element> :==
attribute_name
| <projection_element> '.' attribute_name
| <aggregate>
<aggregate> :==
count()
| avg(<projection_element>)
| sum(<projection_element>)
| min(<projection_element>)
| max(<projection_element>)
Attribute_name mengacu pada properti dokumen JSON apa pun dalam koleksi FROM.
Klausul FROM
Klausa FROM <from_specification> diperlukan di setiap kueri ioT Hub. Ini harus menjadi salah satu dari tiga nilai:
- perangkat untuk mengkueri kembar perangkat
- devices.modules untuk mengkueri modul kembar
- devices.jobs untuk mengkueri detail pekerjaan per perangkat
Contohnya:
Mengambil semua perangkat kembar
SELECT * FROM devices
Klausul WHERE
Klausa WHERE <filter_condition> bersifat opsional. Ini menentukan satu atau beberapa kondisi yang harus disertakan oleh dokumen JSON dalam koleksi FROM untuk dimasukkan sebagai bagian dari hasil. Setiap dokumen JSON harus mengevaluasi kondisi yang ditentukan menjadi "true" untuk disertakan dalam hasilnya.
Contohnya:
Mengambil semua pekerjaan yang menargetkan perangkat tertentu
SELECT * FROM devices.jobs WHERE devices.jobs.deviceId = 'myDeviceId'
Kondisi yang diizinkan dijelaskan di bagian ekspresi dan kondisi .
klausa GROUP BY
Klausa GROUP BY <group_specification> bersifat opsional. Klausa ini dijalankan setelah filter yang ditentukan dalam klausa WHERE, dan sebelum proyeksi yang ditentukan dalam SELECT. Ini mendokumentasikan dokumen berdasarkan nilai atribut. Grup ini digunakan untuk menghasilkan nilai agregat seperti yang ditentukan dalam klausa SELECT.
Contohnya:
Mengembalikan jumlah perangkat yang melaporkan setiap status konfigurasi telemetri
SELECT properties.reported.telemetryConfig.status AS status, COUNT() AS numberOfDevices FROM devices GROUP BY properties.reported.telemetryConfig.status
Saat ini, klausa GROUP BY hanya didukung saat mengkueri kembar perangkat.
Perhatian
Istilah ini group saat ini diperlakukan sebagai kata kunci khusus dalam kueri. Jika, Anda menggunakan group sebagai nama properti Anda, pertimbangkan untuk mengelilinginya dengan tanda kurung ganda untuk menghindari kesalahan, misalnya, SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.
Sintaks formal untuk GROUP BY adalah:
GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name
Attribute_name mengacu pada properti dokumen JSON apa pun dalam koleksi FROM.
Penomoran halaman hasil kueri
Objek kueri dibuat dengan ukuran halaman maks kurang dari atau sama dengan 100 rekaman. Untuk mendapatkan beberapa halaman, panggil nextAsTwin di SDK Node.js atau GetNextAsTwinAsync pada metode .Net SDK beberapa kali. Objek kueri dapat mengekspos beberapa nilai Berikutnya, bergantung pada opsi deserialisasi yang diperlukan oleh kueri. Misalnya, objek kueri dapat mengembalikan perangkat kembar atau objek pekerjaan, atau JSON biasa saat menggunakan proyeksi.
Ekspresi dan kondisi
Pada tingkat tinggi, ekspresi:
- Mengevaluasi ke contoh tipe JSON (seperti Boolean, angka, string, array, atau objek).
- Didefinisikan dengan memanipulasi data yang berasal dari perangkat dokumen dan konstanta JSON menggunakan operator dan fungsi bawaan.
Kondisi adalah ekspresi yang mengevaluasi ke Boolean. Setiap konstanta yang berbeda dari Boolean benar dianggap sebagai palsu. Aturan ini mencakup null, tidak terdefinisi, objek atau instans array apa pun, string apa pun, dan Boolean palsu.
Sintaks untuk ekspresi adalah:
<expression> ::=
<constant> |
attribute_name |
<function_call> |
<expression> binary_operator <expression> |
<create_array_expression> |
'(' <expression> ')'
<function_call> ::=
<function_name> '(' expression ')'
<constant> ::=
<undefined_constant>
| <null_constant>
| <number_constant>
| <string_constant>
| <array_constant>
<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'
Untuk memahami apa yang menjadi kepanjangan dari setiap simbol dalam sintaks ekspresi, lihat tabel berikut:
| Simbol | Definisi |
|---|---|
| Nama atribut | Properti dokumen JSON apa pun dalam koleksi FROM. |
| binary_operator | Setiap operator biner yang tercantum di bagian Operator. |
| function_name | Setiap fungsi yang tercantum di bagian Fungsi. |
| decimal_literal | Sebuah pelampung yang dinyatakan dalam notasi desimal. |
| hexadecimal_literal | Angka yang dinyatakan oleh string '0x' diikuti oleh serangkaian digit heksadesimal. |
| string_literal | Untai (karakter) Unicode yang diwakili oleh urutan nol atau lebih karakter Unicode atau urutan escape. Literal string diapit dalam tanda kutip tunggal atau tanda kutip ganda. Escape yang diizinkan: \', \", \\, \uXXXX untuk karakter Unicode yang ditentukan oleh empat digit heksadesimal. |
Operator
Operator berikut didukung:
| Keluarga | Operator |
|---|---|
| Aritmatika | +, -, *, /, % |
| Logika | AND, OR, NOT |
| Perbandingan | =, !=, <, >, <=, >=, <> |
Fungsi
Saat mengkueri kembar dan pekerjaan, satu-satunya fungsi yang didukung adalah:
| Fungsi | Deskripsi |
|---|---|
| IS_DEFINED (properti) | Menjalankan Boolean yang menunjukkan apakah properti telah diberi nilai (termasuk null). |
Dalam kondisi rute, fungsi matematika berikut didukung:
| Fungsi | Deskripsi |
|---|---|
| ABS(x) | Mengembalikan nilai absolut (positif) dari ekspresi numerik yang ditentukan. |
| EXP(x) | Menjalankan nilai eksponensial dari ekspresi numerik yang ditentukan (e^x). |
| POWER(x,y) | Menjalankan nilai ekspresi yang ditentukan ke daya yang ditentukan (x^y). |
| SQUARE(x) | Menjalankan kuadrat dari nilai numerik yang ditentukan. |
| CEILING(x) | Mengembalikan nilai bilangan bulat terkecil yang lebih besar dari, atau sama dengan ekspresi numerik yang ditentukan. |
| FLOOR(x) | Menampilkan bilangan bulat terbesar yang kurang dari atau sama dengan ekspresi numerik yang ditentukan. |
| TANDA(x) | Menjalankan tanda positif (+1), nol (0), atau negatif (-1) dari ekspresi numerik yang ditentukan. |
| SQRT(x) | Menjalankan akar kuadrat dari nilai numerik yang ditentukan. |
Dalam kondisi rute, fungsi pemeriksaan dan pengecoran tipe berikut didukung:
| Fungsi | Deskripsi |
|---|---|
| NOMOR AS | Mengonversi string input menjadi angka. noop jika input adalah angka; Undefined jika string tidak mewakili angka. |
| IS_ARRAY | Menjalankan nilai Boolean yang menunjukkan jika jenis ekspresi yang ditentukan adalah array. |
| IS_BOOL | Menjalankan nilai Boolean yang menunjukkan jika jenis ekspresi yang ditentukan adalah Boolean. |
| IS_DEFINED | Mengembalikan Boolean yang menunjukkan apakah properti telah diberi nilai. Fungsi ini hanya didukung ketika nilainya adalah jenis primitif. Jenis primitif termasuk untai (karakter), Boolean, numerik, atau null. DateTime, jenis objek, dan array tidak didukung. |
| IS_NULL | Mengembalikan nilai Boolean yang menunjukkan jika jenis ekspresi yang ditentukan adalah nol. |
| IS_NUMBER | Menampilkan nilai Boolean yang mengindikasikan jenis ekspresi yang ditentukan merupakan angka. |
| IS_OBJECT | Mengembalikan nilai Boolean yang mengindikasikan jika jenis ekspresi yang ditentukan adalah objek JSON. |
| IS_PRIMITIVE | Menjalankan nilai Boolean yang menunjukkan apakah tipe ekspresi yang ditentukan adalah primitif (string, Boolean, numerik, atau null ). |
| IS_STRING | Menjalankan nilai Boolean yang mengindikasikan apakah jenis ekspresi yang ditentukan merupakan suatu untai (karakter). |
Dalam kondisi rute, fungsi string berikut didukung:
| Fungsi | Deskripsi |
|---|---|
| CONCAT(x, y, …) | Mengembalikan string yang merupakan hasil penggabungan dua atau beberapa nilai string. |
| PANJANG(x) | Menampilkan jumlah karakter dari ekspresi string yang ditentukan. |
| LEBIH RENDAH(x) | Menjalankan ekspresi string setelah mengonversi data karakter huruf kecil menjadi huruf besar. |
| UPPER(x) | Mengembalikan ekspresi string setelah mengonversi data karakter huruf kecil menjadi huruf besar. |
| SUBSTRING(string, mulai [, panjang]) | Mengembalikan bagian dari ekspresi untai yang dimulai pada posisi berbasis nol karakter yang ditentukan, dan berlanjut ke panjang yang ditentukan, atau ke akhir untai. |
| INDEX_OF(string, fragmen) | Mengembalikan posisi awal kemunculan pertama ekspresi string kedua dalam ekspresi string pertama yang ditentukan, atau -1 jika string tidak ditemukan. |
| STARTSWITH(x, y) | Menampilkan Boolean yang menunjukkan apakah ekspresi string pertama dimulai dengan yang kedua. |
| ENDSWITH(x, y) | Menampilkan Boolean yang menunjukkan apakah ekspresi untai (karakter) pertama berakhir dengan yang kedua. |
| BERISI(x,y) | Mengembalikan Boolean yang menunjukkan apakah ekspresi string pertama berisi yang kedua. |
Contoh kueri dengan SDK layanan
C# contoh
Fungsionalitas kueri diekspos oleh SDK layanan C# di kelas RegistryManager.
Berikut adalah contoh kueri sederhana:
var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
var page = await query.GetNextAsTwinAsync();
foreach (var twin in page)
{
// do work on twin object
}
}
Objek kueri dibuat dengan parameter yang disebutkan di bagian penomoran halaman hasil kueri. Beberapa halaman diambil dengan memanggil metode GetNextAsTwinAsync beberapa kali.
Node.js contoh
Fungsionalitas kueri diekspos oleh SDK layanan Azure IoT untuk Node.js di objek Registri.
Berikut adalah contoh kueri sederhana:
var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
// Do something with the results
results.forEach(function(twin) {
console.log(twin.deviceId);
});
if (query.hasMoreResults) {
query.nextAsTwin(onResults);
}
}
};
query.nextAsTwin(onResults);
Objek kueri dibuat dengan parameter yang disebutkan di bagian penomoran halaman hasil kueri. Beberapa halaman diambil dengan memanggil metode nextAsTwin beberapa kali.
Langkah berikutnya
- Pelajari tentang merutekan pesan berdasarkan properti pesan atau isi pesan dengan sintaks kueri perutean pesan IoT Hub.
- Dapatkan contoh spesifik Kueri untuk perangkat dan modul kembar atau Kueri untuk pekerjaan.