Megosztás a következőn keresztül:

IoT Hub-lekérdezési nyelv az ikereszközökhöz - és modulokhoz, feladatokhoz, valamint az üzenetirányításhoz

  • Cikk

Az IoT Hub hatékony SQL-szerű nyelvet biztosít az ikereszközökkel, modulikonokkal, feladatokkal és üzenet-útválasztással kapcsolatos információk lekéréséhez. Ez a cikk a következőt ismerteti:

  • Bevezetés az IoT Hub lekérdezési nyelvének főbb funkcióiba és
  • A nyelv részletes leírása. Az üzenet-útválasztás lekérdezési nyelvének részleteiért tekintse meg az üzenet-útválasztás lekérdezését.

Konkrét példákért tekintse meg az eszköz- és modul-ikereszközök lekérdezései vagy a feladatok lekérdezései című témakört.

Feljegyzés

A cikkben említett egyes funkciók, például a felhő–eszköz irányú üzenetküldés, az ikereszközök és az eszközfelügyelet csak a standard szintű IoT Hubon érhető el. Az alapszintű és standard/ingyenes IoT Hub-szintekről további információt a megoldáshoz megfelelő IoT Hub-szint kiválasztása című témakörben talál.

IoT Hub-lekérdezések futtatása

Lekérdezéseket futtathat az IoT Hubon közvetlenül az Azure Portalon.

  1. Jelentkezzen be az Azure Portalra , és lépjen az IoT Hubra.
  2. A navigációs menü Eszközkezelés szakaszában válassza a Lekérdezéseklehetőséget.
  3. Írja be a lekérdezést a szövegmezőbe, és válassza a Lekérdezés futtatása lehetőséget.

Lekérdezéseket is futtathat az alkalmazásokban az Azure IoT szolgáltatás SDK-kkal és szolgáltatás API-kkal.

Az IoT Hub-lekérdezéseket implementáló kód például a szolgáltatás SDK-k szakaszában található lekérdezési példákat tekintheti meg.

Az SDK referenciaoldalaira és mintáira mutató hivatkozásokat az Azure IoT SDK-kban találhatja meg.

Az IoT Hub-lekérdezések alapjai

Minden IoT Hub-lekérdezés SELECT és FROM záradékokból áll, választható WHERE és GROUP BY záradékokkal.

A lekérdezések JSON-dokumentumok gyűjteményén futnak, például ikereszközön. A FROM záradék azt a dokumentumgyűjteményt jelzi, amely az eszközön, az devices.moduleson vagy a devices.jobs.

Ezután a WHERE záradék szűrője lesz alkalmazva. Összesítések esetén a lépés eredményei a GROUP BY záradékban megadottak szerint vannak csoportosítva. Minden csoporthoz létrejön egy sor a SELECT záradékban megadott módon.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

SELECT záradék

A SELECT <select_list> záradék minden IoT Hub-lekérdezésben kötelező. Megadja, hogy milyen értékek legyenek lekérve a lekérdezésből. Megadja az új JSON-objektumok létrehozásához használandó JSON-értékeket. A FROM gyűjtemény szűrt (és opcionálisan csoportosított) részhalmazának minden eleme esetében a vetítési fázis létrehoz egy új JSON-objektumot. Ez az objektum a SELECT záradékban megadott értékekkel jön létre.

Példa:

  • Az összes érték visszaadva

    SELECT *

  • Adott tulajdonságok visszaadva

    SELECT DeviceID, LastActivityTime

  • Lekérdezés eredményeinek összesítése a darabszám visszaadásához

    SELECT COUNT() as TotalNumber

Jelenleg a SELECT-hez hasonló kijelölési záradékok csak az ikereszközök összesített lekérdezéseiben támogatottak.

A SELECT záradék nyelvhelyessége a következő szintaxis:

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 a FROM gyűjtemény JSON-dokumentumának bármely tulajdonságára hivatkozik.

FROM záradék

A FROM <from_specification> záradék minden ioT Hub-lekérdezésben kötelező. A három érték egyikének kell lennie:

  • eszközök az ikereszközök lekérdezéséhez
  • devices.modules to query module twins
  • devices.jobs a feladat eszközenkénti adatainak lekérdezéséhez

Példa:

  • Az összes ikereszköz lekérése

    SELECT * FROM devices

WHERE záradék

A WHERE <filter_condition> záradék nem kötelező. Egy vagy több feltételt határoz meg, amelyet a FROM gyűjtemény JSON-dokumentumainak teljesíteniük kell ahhoz, hogy az eredmény részeként szerepeljenek. Minden JSON-dokumentumnak "true" értékre kell értékelnie a megadott feltételeket, hogy szerepeljenek az eredményben.

Példa:

  • Az adott eszközt megcélzott összes feladat lekérése

    SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Az engedélyezett feltételeket a kifejezések és a feltételek szakasz ismerteti.

GROUP BY záradék

A GROUP BY <group_specification> záradék nem kötelező. Ez a záradék a WHERE záradékban megadott szűrő után és a SELECT-ben megadott kivetítés előtt fut. Egy attribútum értéke alapján csoportosítja a dokumentumokat. Ezek a csoportok a SELECT záradékban megadott összesített értékek létrehozására szolgálnak.

Példa:

  • Az egyes telemetriai konfigurációs állapotokat jelentéssel rendelkező eszközök számának visszaadása

    SELECT properties.reported.telemetryConfig.status AS status,
  COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

A GROUP BY záradék jelenleg csak az ikereszközök lekérdezésekor támogatott.

Figyelemfelhívás

A kifejezés group jelenleg speciális kulcsszóként van kezelve a lekérdezésekben. Ha a tulajdonságnévként használja group , érdemes lehet két zárójelben körbevenni, hogy elkerülje a hibákat, például SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

A GROUP BY formális szintaxisa a következő:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name a FROM gyűjtemény JSON-dokumentumának bármely tulajdonságára hivatkozik.

Lekérdezési eredmények lapozása

A lekérdezésobjektumok példányosítása 100 rekordnál kisebb vagy egyenlő maximális oldalmérettel történik. Több oldal beszerzéséhez hívja meg többször a következőAsTwint Node.js SDK-n vagy a GetNextAsTwinAsync metóduson a .Net SDK metóduson. A lekérdezésobjektumok a lekérdezés által igényelt deszerializálási beállítástól függően több Next értéket is elérhetővé tehetnek. A lekérdezési objektumok például iker- vagy feladatobjektumokat, illetve egyszerű JSON-objektumokat adhatnak vissza kivetítések használatakor.

Kifejezések és feltételek

Magas szinten egy kifejezés:

  • JSON-típus (például logikai, szám, sztring, tömb vagy objektum) egy példányára értékeli ki.
  • Az eszköz JSON-dokumentumából és állandóiból származó adatok beépített operátorok és függvények használatával történő módosításával van definiálva.

A feltételek logikai értékre kiértékelt kifejezések. A logikai igaztól eltérő állandók hamisnak minősülnek. Ez a szabály magában foglalja a null, a nem definiált, az objektum- vagy tömbpéldányokat, a sztringeket és a logikai hamisokat.

A kifejezések szintaxisa a következő:

<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>]+ ']'

A kifejezések szintaxisában szereplő szimbólumok értelmezéséhez tekintse meg az alábbi táblázatot:

Szimbólum Definíció
attribute_name A JSON-dokumentum bármely tulajdonsága a FROM gyűjteményben.
binary_operator Az Operátorok szakaszban felsorolt bináris operátorok .
function_name A Függvények szakaszban felsorolt függvények .
decimal_literal A decimális jelölésben kifejezett lebegőpontos szám.
hexadecimal_literal A "0x" sztring által kifejezett szám, amelyet hexadecimális számjegyek sztringje követ.
string_literal Unicode-sztringek, amelyeket nulla vagy több Unicode-karakterből vagy feloldósorozatból álló sorozat jelöl. A sztringkonstansok egy vagy két idézőjelbe vannak zárva. Engedélyezett feloldások: \', \", \\a \uXXXX négy hexadecimális számjegy által definiált Unicode-karakterekhez.

Operátorok

A következő operátorok támogatottak:

Család Operátorok
Aritmetikai +, -, *, /, %
Logikai ÉS, VAGY NEM
Összehasonlítás =, !=, <, >, <=, >=, <>

Functions

Ikerpéldányok és feladatok lekérdezésekor az egyetlen támogatott függvény a következő:

Függvény Leírás
IS_DEFINED(tulajdonság) Logikai értéket ad vissza, amely azt jelzi, hogy a tulajdonsághoz érték van-e hozzárendelve (beleértve az értéket is null).

Útvonalfeltételek esetén a következő matematikai függvények támogatottak:

Függvény Leírás
ABS(x) A megadott numerikus kifejezés abszolút (pozitív) értékét adja vissza.
EXP(x) A megadott numerikus kifejezés (e^x) exponenciális értékét adja vissza.
POWER(x;y) A megadott kifejezés értékét adja vissza a megadott hatványnak (x^y).
NÉGYZET(x) A megadott numerikus érték négyzetét adja vissza.
PLAFON(x) A megadott numerikus kifejezésnél nagyobb vagy egyenlő legkisebb egész számot adja vissza.
PADLÓ(x) A megadott numerikus kifejezésnél kisebb vagy egyenlő legnagyobb egész számot adja vissza.
SIGN(x) A megadott numerikus kifejezés pozitív (+1), nulla (0) vagy negatív (-1) előjelét adja vissza.
SQRT(x) A megadott numerikus érték négyzetgyökét adja vissza.

Útvonal-feltételek esetén a következő típusellenőrzési és öntési függvények támogatottak:

Függvény Leírás
AS_NUMBER Számmá alakítja a bemeneti sztringet. noop ha a bemenet szám; Undefined ha a sztring nem jelent számot.
IS_ARRAY Logikai értéket ad vissza, amely jelzi, hogy a megadott kifejezés típusa tömb-e.
IS_BOOL Logikai értéket ad vissza, amely jelzi, hogy a megadott kifejezés típusa logikai-e.
IS_DEFINED Logikai értéket ad vissza, amely jelzi, hogy a tulajdonsághoz érték van-e rendelve. Ez a függvény csak akkor támogatott, ha az érték egy primitív típus. A primitív típusok közé tartozik a sztring, a logikai, a numerikus vagy nulla . A DateTime, az objektumtípusok és a tömbök nem támogatottak.
IS_NULL Logikai értéket ad vissza, amely azt jelzi, hogy a megadott kifejezés típusa null.
IS_NUMBER Logikai értéket ad vissza, amely azt jelzi, hogy a megadott kifejezés típusa szám-e.
IS_OBJECT Logikai értéket ad vissza, amely jelzi, hogy a megadott kifejezés típusa JSON-objektum-e.
IS_PRIMITIVE Logikai értéket ad vissza, amely azt jelzi, hogy a megadott kifejezés típusa primitív (sztring, logikai, numerikus vagy null).
IS_STRING Logikai értéket ad vissza, amely azt jelzi, hogy a megadott kifejezés típusa sztring-e.

Útvonalfeltételek esetén a következő sztringfüggvények támogatottak:

Függvény Leírás
CONCAT(x, y, ...) Egy sztringet ad vissza, amely két vagy több sztringérték összefűzésének eredménye.
HOSSZ(x) A megadott sztringkifejezés karaktereinek számát adja vissza.
LOWER(x) Sztringkifejezést ad vissza a nagybetűs karakteradatok kisbetűssé alakítása után.
UPPER(x) Sztringkifejezést ad vissza a kisbetűs adatok nagybetűssé alakítása után.
SUBSTRING(sztring; kezdő [; hossz]) Egy sztringkifejezés egy részét adja vissza, amely a megadott karakter nulla-alapú pozíciójától kezdve a megadott hosszig vagy a sztring végéig tart.
INDEX_OF(sztring, töredék) A második sztringkifejezés első előfordulásának kezdőpozícióját adja vissza az első megadott sztringkifejezésen belül, vagy -1 értéket, ha a sztring nem található.
STARTSWITH(x, y) Logikai értéket ad vissza, amely jelzi, hogy az első sztringkifejezés a másodikkal kezdődik-e.
ENDSWITH(x; y) Logikai értéket ad vissza, amely jelzi, hogy az első sztringkifejezés a másodikkal végződik-e.
CONTAINS(x;y) Logikai értéket ad vissza, amely azt jelzi, hogy az első sztringkifejezés tartalmazza-e a másodikat.

Példák lekérdezése a szolgáltatás SDK-kkal

C# példa

A lekérdezési funkciót a C# szolgáltatás SDK a RegistryManager osztályban teszi elérhetővé.

Íme egy példa egy egyszerű lekérdezésre:

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

A lekérdezési objektum példányosítása a lekérdezési eredmények lapozási szakaszában említett paraméterekkel történik. Több lap lekérése a GetNextAsTwinAsync metódus többszöri meghívásával.

Node.js példa

A lekérdezési funkciót az Azure IoT service SDK teszi elérhetővé Node.js a Beállításjegyzék-objektumban .

Íme egy példa egy egyszerű lekérdezésre:

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);

A lekérdezési objektum példányosítása a lekérdezési eredmények lapozási szakaszában említett paraméterekkel történik. Több oldal lekérése a nextAsTwin metódus többszöri meghívásával.

Következő lépések