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

Cikk
08/15/2023

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

Bevezetés a IoT Hub lekérdezési nyelv 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 lásd: lekérdezések az üzenet útválasztásában.

Konkrét példákért lásd: Eszközök és modulok ikerpéldányainak lekérdezései vagy Feladatok lekérdezései.

Megjegyzé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 szintekkel kapcsolatos további információkért lásd: A megoldáshoz megfelelő IoT Hub szint kiválasztása.

IoT Hub lekérdezések futtatása

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

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

Az alkalmazásokban lekérdezéseket is futtathat az Azure IoT szolgáltatás SDK-jai és szolgáltatás API-k használatával.

A IoT Hub lekérdezéseket implementáló kód például a Lekérdezési példák a szolgáltatás SDK-kkal szakaszában található.

Az SDK referenciaoldalaira és mintáira mutató hivatkozásokért lásd: Azure IoT SDK-k.

A 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, például ikereszközök gyűjteményén futnak. A FROM záradék azt jelzi, hogy a dokumentumgyűjteményt ( eszközök, eszközök.modulok vagy devices.jobs) kell-e iterated-ként használni.

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ékra minden IoT Hub lekérdezésben szükség van. Meghatározza, hogy a rendszer milyen értékeket kér le a lekérdezésből. Meghatározza 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éldául:

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-nél eltérő kiválasztási záradékok csak az ikereszközök összesített lekérdezéseiben támogatottak.

Az alábbi szintaxis a SELECT záradék nyelvtana:

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ékra minden ioT Hub-lekérdezésben szükség van. 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éldául:

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, amelyeket 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 szerepeljen az eredményben.

Például:

Egy adott eszközt célzó összes feladat lekérése

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

Az engedélyezett feltételeket a kifejezések és 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 záradékban megadott vetület 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éldául:

Az egyes telemetriakonfigurációs állapotot jelentő 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 szögletes zárójelekkel körülvenni, 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 azzal egyenlő maximális oldalmérettel történik. Több oldal beszerzéséhez hívja meg többször a következőAsTwin metódust Node.js SDK-n vagy GetNextAsTwinAsync a .Net SDK-metóduson. A lekérdezésobjektumok a lekérdezés által igényelt deszerializálási lehetőségtől függően több Next értéket is elérhetővé tehetnek. A lekérdezésobjektumok például ikereszköz- vagy feladatobjektumokat, illetve egyszerű JSON-t adhatnak vissza leképezések használatakor.

Kifejezések és feltételek

Magas szinten egy kifejezés:

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

A feltételek olyan kifejezések, amelyek logikai értékre vannak kiértékelve. A logikai igaztól eltérő állandók hamisnak minősülnek. Ez a szabály null értékű, nem definiált, bármely objektum- vagy tömbpéldányt, bármilyen sztringet és logikai hamis értéket tartalmaz.

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	Decimális jelöléssel kifejezett lebegőpontos.
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 idézőjelek vagy dupla idézőjelek közé vannak zárva. Engedélyezett feloldások: `\'`, `\"`, `\\`, `\uXXXX` a négy hexadecimális számjegy által definiált Unicode-karakterekhez.

Operátorok

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

Family (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)	Egy logikai értéket ad vissza, amely azt jelzi, hogy a tulajdonsághoz érték van-e rendelve (beleértve a é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 eredményül.
EXP(x)	A megadott numerikus kifejezés exponenciális értékét adja vissza (e^x).
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.
MENNYEZET(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 eredményül.
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 azt jelzi, hogy a megadott kifejezés típusa tömb-e.
IS_BOOL	Logikai értéket ad vissza, amely azt jelzi, hogy a megadott kifejezés típusa logikai-e.
IS_DEFINED	Egy logikai értéket ad vissza, amely azt jelzi, hogy a tulajdonsághoz érték van-e rendelve. Ez a függvény csak akkor támogatott, ha az érték primitív típus. A primitív típusok közé tartozik a sztring, a logikai, a numerikus vagy `null`a . A DateTime, az objektumtípusok és a tömbök nem támogatottak.
IS_NULL	Egy logikai értéket ad vissza, amely azt jelzi, hogy a megadott kifejezés típusa null-e.
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 -e (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.
ALSÓ(x)	Sztringkifejezést ad vissza, miután kisbetűssé konvertálta a nagybetűs adatokat.
FELSŐ(x)	Sztringkifejezést ad vissza a kisbetűs adatok nagybetűssé konvertálása után.
SUBSTRING(string, start [, length])	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ésben, vagy -1 értéket, ha a sztring nem található.
STARTSWITH(x, y)	Egy logikai értéket ad vissza, amely azt jelzi, hogy az első sztringkifejezés a másodikkal kezdődik-e.
ENDSWITH(x, y)	Egy logikai értéket ad vissza, amely azt jelzi, hogy az első sztringkifejezés a másodikkal végződik-e.
CONTAINS(x;y)	Egy 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 közzé.

Í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 a lekérdezési eredmények lapozási szakaszában említett paraméterekkel lesz példányosítva. Több oldal lekérése a GetNextAsTwinAsync metódusok többszöri meghívásával.

Node.js példa

A lekérdezési funkciót az Azure IoT service SDK Node.js a beállításjegyzék-objektumban teszi közzé.

Í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 a lekérdezési eredmények lapozási szakaszában említett paraméterekkel lesz példányosítva. Több oldal lekérése a nextAsTwin metódus többszöri meghívásával.

Következő lépések

Ismerje meg, hogyan irányíthatja az üzeneteket az üzenettulajdonságok vagy az üzenettörzs alapján az IoT Hub üzenet-útválasztási lekérdezés szintaxisával.
Konkrét példákat kaphat az eszköz- és modul-ikereszközök lekérdezéseire vagy a feladatok lekérdezéseire.

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

IoT Hub lekérdezések futtatása

A IoT Hub lekérdezések alapjai

SELECT záradék

FROM záradék

WHERE záradék

GROUP BY záradék

Lekérdezési eredmények lapozása

Kifejezések és feltételek

Operátorok

Functions

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

C# példa

Node.js példa

Következő lépések

További források