Bagikan melalui


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.

  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 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, 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 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