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

IoT Hub lekérdezési nyelv eszköz- és modul-ikrekhez, munkákhoz, és üzenetirányításhoz

IoT Hub egy hatékony, SQL-szerű nyelvet biztosít az információ lekérdezéséhez a eszköz ikrek, modul ikrek, feladatok, és üzenet továbbítás vonatkozásában. Ez a cikk bemutatja:

Konkrét példákért tekintse meg az IoT Hub-eszközök és -modulok ikerpéldányainak lekérdezései vagy az IoT Hub-feladatok lekérdezései című témakört.

Megjegyzés

Az ebben a cikkben említett funkciók közül néhány, mint például a felhőből eszközre irányuló üzenetküldés, az eszközipárok és az eszközkezelés, csak az IoT Hub standard szintjén érhető el. Az alapszintű és standard/ingyenes IoT Hub-szintekkel kapcsolatban további információkért lásd Válassza ki a megoldása számára megfelelő IoT Hub-szintet és -méretet.

Futtassa az IoT Hub lekérdezéseket

A lekérdezéseket közvetlenül az Azure portálon futtathatja az IoT-hubján.

  1. Jelentkezzen be az Azure portálra, és navigáljon az IoT központjához.
  2. Válassza ki a Queries elemet a navigációs menü Device management szakaszában.
  3. Adja meg lekérdezését a szövegdobozba, majd válassza a Lekérdezés futtatása lehetőséget.

Az alkalmazásaiban futtathat lekérdezéseket az Azure IoT szolgáltatás SDK-kkal és szolgáltatás API-kkal.

Az IoT Hub lekérdezések példakódjaiért tekintse meg a Lekérdezési példák a szolgáltatási SDK-kkal című részt.

Az SDK referenciaoldalaira és mintáira mutató hivatkozásokért tekintse meg az Azure IoT Hub SDK-jait.

Alapok az IoT Hub lekérdezéshez

Minden IoT Hub lekérdezés SELECT és FROM utasításokból áll, opcionális WHERE és GROUP BY utasításokkal.

Lelekérdezések JSON dokumentumok gyűjteményén futnak, például eszköz ikrek esetében. A FROM záradék megadja a dokumentumgyűjteményt, amelyen iterálni kell (vagy eszközök, eszközök.modulok, vagy eszközök.munkák).

Ezután a WHERE feltételben lévő szűrő alkalmazásra kerül. Az aggregációk alapján ebben a lépésben az eredmények a GROUP BY záradékban meghatározottak szerint csoportosításra kerülnek. Minden csoporthoz egy sor jön létre, ahogy azt a SELECT utasítás meghatározza.

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

SELECT klauzula

Az SELECT <select_list> záradék minden IoT Hub lekérdezésben kötelező. Megadja, hogy a lekérdezés milyen értékeket ad vissza. Megadja a JSON értékeket, amelyeket új JSON objektumok létrehozásához kell használni. Minden egyes elem esetében a szűrt (és opcionálisan csoportosított) FROM gyűjtemény részhalmazában a vetítési fázis egy új JSON objektumot hoz létre. Ez az objektum a SELECT záradékban megadott értékekkel van felépítve.

For example:

  • Téríts vissza minden értéket

    SELECT *

  • Specifikus tulajdonságok visszaadása

    SELECT DeviceID, LastActivityTime

  • Érje el a lekérdezés eredményeinek összegzését, hogy megkaphassa az összesítést.

    SELECT COUNT() as TotalNumber

Jelenleg a SELECT-től eltérő kiválasztási záradékok csak eszközpárok aggregált lekérdezéseiben támogatottak.

A következő 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>)

A Attribute_name a FROM gyűjteményben lévő JSON dokumentum bármely tulajdonságára utal.

FROM záradék

A FROM <from_specification> záradékra minden ioT Hub lekérdezéshez szükség van. Ennek a három érték egyikének kell lennie.

  • Eszközök az eszköz ikrek lekérdezésére
  • devices.modules a modul ikrek lekérdezéséhez
  • devices.jobs a készülékenkénti feladat részleteinek lekérdezéséhez

For example:

  • Minden eszköztükröt lekérdezni

    SELECT * FROM devices

WHERE feltétel

A WHERE <filter_condition> záradék opcionális. Megadja az egy vagy több feltételt, amelyet a FROM gyűjtemény JSON dokumentumainak teljesíteniük kell ahhoz, hogy bekerüljenek az eredménybe. Minden JSON dokumentumnak értékelnie kell a megadott feltételeket "igaz"-ra, hogy bekerüljön az eredménybe.

For example:

  • Kérje le az összes munkát, amely egy bizonyos eszközt céloz meg.

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

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

GROUP BY clause

A GROUP BY <group_specification> klauzula opcionális. Ez a záradék a WHERE záradékban meghatározott szűrő után, és a SELECT-ben meghatározott kivetítés előtt hajtódik végre. Dokumentumokat csoportosít egy attribútum értéke alapján. Ezeket a csoportokat használják a SELECT záradékban megadott összesített értékek generálására.

For example:

  • Térj vissza az eszközök számával, amelyek jelentik az egyes telemetriai konfigurációs állapotokat.

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

Currently, the GROUP BY clause is only supported when querying device twins.

Caution

The term group is currently treated as a special keyword in queries. Abban az esetben, ha a tulajdonságnévként használja group , fontolja meg, hogy a hibákat elkerülendő két szögletes zárójelekkel körülvezze, ahogyan az ebben a példában látható: 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 refers to any property of the JSON document in the FROM collection.

Lekérdezési eredmények lapozása

Egy lekérdezési objektum példányosítva lesz egy legfeljebb 100 rekordnyi oldal méretével, amely kevesebb vagy egyenlő lehet. Több oldal beszerzéséhez hívja meg többször a KövetkezőAsTwin Node.js SDK-n vagy a GetNextAsTwinAsync metódust a .NET SDK-val. Egy lekérdezési objektum több következő értéket is képes megjeleníteni, attól függően, hogy a lekérdezéshez milyen deszerializációs opció szükséges. Például egy lekérdezési objektum visszaadhat eszköz-iker vagy feladat objektumokat, vagy egyszerű JSON-t, ha vetítéseket használ.

Expressions and conditions

Magas szinten, egy expression:

  • Kiértékel egy JSON típusú példányt (például logikai, szám, szöveg, tömb vagy objektum).
  • Is defined by manipulating data coming from the device JSON document and constants using built-in operators and functions.

Feltételek olyan kifejezések, amelyek Booleant eredményeznek. Bármely konstans, amely eltér a Boolean true-től, false-nek tekinthető. Ez a szabály magában foglalja a null, undefined, bármely objektum vagy tömb példányát, bármely karakterláncot, és a Boolean false-t.

The syntax for expressions is:

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

To understand what each symbol in the expressions syntax stands for, refer to the following table:

Szimbólum Definition
attribute_name A JSON dokumentum bármely tulajdonsága a FROM gyűjteményben.
bináris operátor Bármely bináris operátor, amely a Operátorok szakaszban szerepel.
function_name A Functions szakaszban felsorolt bármely funkció.
decimal_literal Lebegőpontos szám decimális jelöléssel.
hexadecimális_literál Egy szám, amelyet a '0x' karakterlánc követ, amit hexadecimális számjegyek karakterlánca követ.
string_literal Unicode strings represented by a sequence of zero or more Unicode characters or escape sequences. A string literálokat egyes idézőjelek vagy kettős idézőjelek közé zárják. Engedélyezett escape-ek: \', \", \\, \uXXXX az Unicode karakterek számára, amelyeket négy hexadecimális számjegy definiál.

Operátorok

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

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

Functions

Amikor a twineket és a feladatokat kérdezzük le, az egyetlen támogatott funkció:

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

A feltételek útvonalain a következő matematikai függvények támogatottak:

Function Leírás
ABS(x) Returns the absolute (positive) value of the specified numeric expression.
EXP(x) Returns the exponential value of the specified numeric expression (e^x).
POWER(x,y) Visszaadja a megadott kifejezés megadott hatványra emelt értékét (x^y).
SQUARE(x) Visszaadja a megadott numerikus érték négyzetét.
FELSŐ ÉRTÉK(x) Megadja a legkisebb egész számot, amely nagyobb vagy egyenlő a megadott numerikus kifejezéssel.
padló(x) Returns the largest integer less than or equal to the specified numeric expression.
SIGN(x) Returns the positive (+1), zero (0), or negative (-1) sign of the specified numeric expression.
SQRT(x) Returns the square root of the specified numeric value.

In routes conditions, the following type checking and casting functions are supported:

Function Leírás
AS_SZÁM Átalakítja a bemeneti karakterláncot számmá. noop ha a bemenet egy szám; Undefined ha a karakterlánc nem egy számot képvisel.
IS_ARRAY Visszaad egy logikai értéket, amely jelzi, hogy a megadott kifejezés típusa tömb-e.
IS_BOOL Returns a Boolean value indicating if the type of the specified expression is a Boolean.
IS_DEFINED Logikai értéket ad vissza, amely jelzi, hogy a tulajdonság érték-e. Ez a funkció csak akkor támogatott, ha az érték primitív típusú. A primitív típusok közé tartozik a karakterlánc, a logikai, a numerikus, vagy null. A DateTime, az objektumtípusok és a tömbök nem támogatottak.
IS_NULL Visszaad egy logikai értéket, amely jelzi, hogy a megadott kifejezés típusa nulla-e.
SZÁM_E? Visszaad egy logikai értéket, amely jelzi, hogy a megadott kifejezés típusa szám-e.
IS_OBJEKTUM Returns a Boolean value indicating if the type of the specified expression is a JSON object.
IS_PRIMITIVE Visszaad egy logikai értéket, amely jelzi, hogy a megadott kifejezés típusa primitív-e (karakterlánc, logikai, numerikus vagy null).
IS_STRING Returns a Boolean value indicating if the type of the specified expression is a string.

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

Funkció Leírás
CONCAT(x, y, …) Visszaad egy karakterláncot, amely két vagy több karakterlánc érték összefűzésének eredménye.
LENGTH(x) Megadja a megadott karaktersor kifejezésben található karakterek számát.
KISBETŰS(x) Visszaad egy karakterlánc kifejezést, miután a nagybetűs karakteradatokat kisbetűssé alakította.
UPPER(x) Returns a string expression after converting lowercase character data to uppercase.
SUBSTRING(string, start [, hossz]) A karakterlánc-kifejezés egy részét visszaadja, kezdve a megadott nulla-alapú karakterpozíciónál, és folytatódik a megadott hosszúságig vagy a karakterlánc végéig.
INDEX_OF(string, fragment) Returns the starting position of the first occurrence of the second string expression within the first specified string expression, or -1 if the string isn't found.
STARTS_WITH(x, y) Visszaad egy logikai értéket, hogy az első karakterlánc kifejezés kezdődik-e a másodikkal.
VÉGZŐDIK(x, y) Returns a Boolean indicating whether the first string expression ends with the second.
CONTAINS(x,y) Returns a Boolean indicating whether the first string expression contains the second.

Query examples with the service SDKs

C# example

A lekérdezési funkciót az Azure IoT Hub service SDK for .NET teszi elérhetővé a RegistryManager osztályban.

Íme egy egyszerű lekérdezés példája:

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és eredményei lapozás szakaszában említett paraméterekkel történik. Több oldalt érünk el a GetNextAsTwinAsync metódusok többszöri meghívásával.

Node.js example

A lekérdezési funkciót az Azure IoT Hub szolgáltatás SDK Node.js a Beállításjegyzék-objektumban teszi közzé.

Here's an example of a simple query:

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és eredményei lapozás 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 történik.

Next steps

  • Last updated on