Bagikan melalui

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

IoT Hub menyediakan bahasa yang kuat mirip SQL untuk mengambil informasi mengenai device twins, module twins, tugas, dan perutean pesan. Artikel ini menyajikan:

  • Pengenalan fitur utama bahasa kueri IoT Hub, dan
  • Deskripsi terperinci tentang bahasa tersebut. Untuk informasi selengkapnya tentang bahasa kueri untuk perutean pesan, lihat Sintaks kueri perutean pesan IoT Hub.

Untuk contoh tertentu, lihat Kueri untuk perangkat IoT Hub dan modul kembar atau Kueri untuk pekerjaan IoT Hub.

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.

Menjalankan kueri IoT Hub

Anda dapat menjalankan kueri terhadap hub IoT Anda langsung di portal Azure.

  1. Masuk ke portal Azure dan navigasikan ke IoT hub Anda.
  2. Pilih Kueri dari bagian Manajemen perangkat pada menu navigasi.
  3. 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, untuk kode yang menerapkan kueri IoT Hub, lihat bagian Contoh kueri dengan SDK layanan.

Untuk tautan ke halaman referensi dan sampel SDK, lihat SDK Azure IoT Hub.

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 perangkat kembar. Klausa FROM menunjukkan koleksi dokumen yang akan diiterasi (baik devices, 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, 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 mengakses kembar perangkat
  • devices.modules untuk mengakses modul kembar
  • devices.jobs untuk menanyakan 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 dipenuhi oleh dokumen JSON dalam koleksi FROM agar dapat dimasukkan sebagai bagian dari hasil. Setiap dokumen JSON harus mengevaluasi kondisi yang ditentukan menjadi "true" untuk disertakan dalam hasilnya.

Contohnya:

  • Memperoleh 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 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, seperti yang ditunjukkan dalam contoh ini: 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 catatan. 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 menghasilkan nilai 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 apa pun dari dokumen JSON dalam koleksi FROM.
binary_operator Setiap operator biner yang tercantum dalam bagian Operator.
function_name Setiap fungsi yang tercantum di bagian Fungsi.
decimal_literal Sebuah pelampung yang dinyatakan dalam notasi desimal.
literal heksadesimal 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 oleh 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 DAN, ATAU, TIDAK
Perbandingan =, !=, <, >, <=, >=, <>

Fungsi

Saat mengkueri kembar dan pekerjaan, satu-satunya fungsi yang didukung adalah:

Fungsi Deskripsi
IS_DEFINED (properti) Mengembalikan Boolean yang menunjukkan apakah properti 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) Mengembalikan nilai eksponensial dari ekspresi numerik yang ditentukan (e^x).
POWER(x,y) Mengembalikan nilai dari ekspresi yang ditentukan ke pangkat yang ditentukan (x^y).
SQUARE(x) Mengembalikan 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.
FUNGSI TANDA(x) Mengembalikan tanda positif (+1), nol (0), atau negatif (-1) dari tanda ekspresi numerik yang ditentukan.
SQRT(x) Mengembalikan 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 Mengembalikan nilai Boolean yang menunjukkan apakah jenis ekspresi yang ditentukan adalah sebuah array.
IS_BOOL Mengembalikan nilai Boolean yang menunjukkan apakah jenis dari ekspresi yang ditentukan adalah Boolean.
TERDEFINISI Mengembalikan Boolean yang menunjukkan apakah properti adalah 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 Mengembalikan nilai Boolean yang menunjukkan apakah tipe ekspresi yang ditentukan adalah string.

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) Mengembalikan ekspresi string setelah mengubah data karakter huruf besar menjadi huruf kecil.
UPPER(x) Mengembalikan ekspresi string setelah mengonversi data karakter huruf kecil menjadi huruf besar.
SUBSTRING(string, mulai [, panjang]) Mengembalikan bagian dari ekspresi string yang dimulai pada indeks karakter berdasarkan nol yang ditentukan, dan berlanjut ke panjang yang ditentukan, atau sampai akhir string.
INDEX_OF(string, fragmen) Mengembalikan posisi awal kemunculan pertama ekspresi string kedua dalam ekspresi string pertama yang ditentukan, atau -1 jika string tidak ditemukan.
MULAI_DENGAN(x, y) Menampilkan Boolean yang menunjukkan apakah ekspresi string pertama dimulai dengan yang kedua.
ENDS_WITH(x, y) — Memeriksa apakah x berakhir dengan y Mengembalikan Boolean yang menunjukkan apakah ekspresi string pertama berakhir dengan ekspresi string kedua.
BERISI(x,y) Mengembalikan Boolean yang menunjukkan apakah ekspresi string pertama berisi yang kedua.

Contoh kueri dengan SDK layanan

Contoh C#

Fungsionalitas kueri diekspos oleh SDK layanan Azure IoT Hub untuk .NET 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 Hub 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 beberapa kali memanggil metode nextAsTwin.

Langkah berikutnya