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

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.

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.

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:

Operátorok

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

Függvények

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

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

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

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

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

• Ismerje meg az üzenettulajdonságok vagy üzenettörzs alapján történő útválasztást az IoT Hub üzenet-útválasztási lekérdezési 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.