Bahasa kueri Hub IoT untuk perangkat dan modul kembar, pekerjaan, dan perutean pesan

Artikel
06/01/2023

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 Microsoft Azure dan menavigasikan ke Azure 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>]

PILIH klausa

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, LastActivityTime
```
Mengagregasi 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 perangkat kembar
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 maksimum kurang dari atau sama dengan 100 rekaman. Untuk mendapatkan beberapa halaman, panggil nextAsTwin di Node.js SDK 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.
Nama fungsi	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 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	+, -, *, /, %
Logis	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)	Menjalankan nilai bilangan bulat terkecil yang lebih besar dari, atau sama dengan ekspresi numerik yang ditentukan.
FLOOR(x)	Menjalankan 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	Menjalankan Boolean yang menunjukkan apakah properti telah diberi nilai. Fungsi ini hanya didukung ketika nilainya adalah jenis primitif. Jenis primitif termasuk string, 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	Menjalankan nilai Boolean yang mengindikasikan jenis ekspresi yang ditentukan merupakan angka.
IS_OBJECT	Menjalankan 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, …)	Menjalankan string yang merupakan hasil penggabungan dua atau beberapa nilai string.
PANJANG(x)	Menjalankan 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])	Menjalankan 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)	Menjalankan Boolean yang menunjukkan apakah ekspresi string pertama dimulai dengan yang kedua.
ENDSWITH(x, y)	Menjalankan Boolean yang menunjukkan apakah ekspresi untai (karakter) pertama berakhir dengan yang kedua.
CONTAINS(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.

Bahasa kueri Hub IoT untuk perangkat dan modul kembar, pekerjaan, dan perutean pesan

Menjalankan kueri IoT Hub

Dasar-dasar kueri IoT Hub

PILIH klausa

Klausul FROM

Klausul WHERE

klausa GROUP BY

Penomoran halaman hasil kueri

Ekspresi dan kondisi

Operator

Fungsi

Contoh kueri dengan SDK layanan

C# contoh

Node.js contoh

Langkah berikutnya

Sumber Daya Tambahan: