Dotazovací jazyk služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv

Článek
08/15/2023

IoT Hub poskytuje výkonný jazyk podobný SQL pro načítání informací týkajících se dvojčat zařízení, dvojčat modulů, úloh a směrování zpráv. Tento článek uvádí:

Úvod k hlavním funkcím dotazovacího jazyka IoT Hub a
Podrobný popis jazyka. Podrobnosti o dotazovacím jazyce pro směrování zpráv najdete v tématu Dotazy ve směrování zpráv.

Konkrétní příklady najdete v tématu Dotazy na dvojčata zařízení a modulů nebo Dotazy pro úlohy.

Poznámka

Některé funkce uvedené v tomto článku, jako je zasílání zpráv z cloudu do zařízení, dvojčata zařízení a správa zařízení, jsou k dispozici ve službě IoT Hub pouze na úrovni Standard. Další informace o úrovních IoT Hub Basic a Standard/Free najdete v tématu Volba správné IoT Hub úrovně pro vaše řešení.

Spouštění dotazů IoT Hub

Dotazy na centrum IoT můžete spouštět přímo v Azure Portal.

Přihlaste se k Azure Portal a přejděte do centra IoT.
V části Správa zařízení v navigační nabídce vyberte Dotazy.
Do textového pole zadejte svůj dotaz a vyberte Spustit dotaz.

Dotazy můžete také spouštět v rámci svých aplikací pomocí sad SDK služby Azure IoT a rozhraní API služeb.

Příklad implementace kódu IoT Hub dotazů najdete v části Příklady dotazů pomocí sad SDK služby.

Odkazy na referenční stránky a ukázky sady SDK najdete v tématu Sady SDK Pro Azure IoT.

Základy IoT Hub dotazu

Každý IoT Hub dotaz se skládá z klauzulí SELECT a FROM s volitelnými klauzulemi WHERE a GROUP BY.

Dotazy se spouští na kolekci dokumentů JSON, například dvojčat zařízení. Klauzule FROM označuje kolekci dokumentů, na které se má iteovat ( zařízení, devices.modules nebo devices.jobs).

Potom se použije filtr v klauzuli WHERE. U agregací jsou výsledky tohoto kroku seskupené podle klauzule GROUP BY. Pro každou skupinu se vygeneruje řádek podle klauzule SELECT.

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

Klauzule SELECT

Klauzule SELECT <select_list> se vyžaduje v každém dotazu IoT Hub. Určuje, jaké hodnoty se z dotazu načtou. Určuje hodnoty JSON, které se mají použít ke generování nových objektů JSON. Pro každý prvek filtrované (a volitelně seskupené) podmnožiny kolekce FROM fáze projekce vygeneruje nový objekt JSON. Tento objekt je vytvořen s hodnotami zadanými v klauzuli SELECT.

Příklad:

Vrátit všechny hodnoty
```
SELECT *
```
Vrácení konkrétních vlastností
```
SELECT DeviceID, LastActivityTime
```
Agregace výsledků dotazu pro vrácení počtu
```
SELECT COUNT() as TotalNumber
```

V současné době jsou klauzule výběru jiné než SELECT podporované pouze v agregovaných dotazech na dvojčata zařízení.

Následující syntaxe je gramatika klauzule 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 odkazuje na libovolnou vlastnost dokumentu JSON v kolekci FROM.

Klauzule FROM

Klauzule FROM <from_specification> se vyžaduje v každém dotazu ioT Hubu. Musí to být jedna ze tří hodnot:

zařízení pro dotazování dvojčat zařízení
devices.modules pro dotazování dvojčat modulů
devices.jobs k dotazování na podrobnosti o úloze podle zařízení

Příklad:

Načtení všech dvojčat zařízení
```
SELECT * FROM devices
```

Klauzule WHERE

Klauzule WHERE <filter_condition> je volitelná. Určuje jednu nebo více podmínek, které musí dokumenty JSON v kolekci FROM splňovat, aby byly zahrnuty jako součást výsledku. Každý dokument JSON musí vyhodnotit zadané podmínky jako true, aby byl zahrnut do výsledku.

Příklad:

Načtení všech úloh, které cílí na konkrétní zařízení

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

Povolené podmínky jsou popsané v části výrazy a podmínky .

Klauzule GROUP BY

Klauzule GROUP BY <group_specification> je volitelná. Tato klauzule se spustí po filtru zadaném v klauzuli WHERE a před projekcí zadanou v příkazu SELECT. Seskupuje dokumenty na základě hodnoty atributu. Tyto skupiny se používají ke generování agregovaných hodnot, jak je uvedeno v klauzuli SELECT.

Příklad:

Vrácení počtu zařízení, která hlásí stav konfigurace telemetrie.

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

V současné době se klauzule GROUP BY podporuje jenom při dotazování dvojčat zařízení.

Upozornění

Termín group se v dotazech v současné době považuje za speciální klíčové slovo. V případě, že jako název vlastnosti použijete group , zvažte jeho okolí dvojitými závorkami, abyste se vyhnuli chybám, SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'například .

Formální syntaxe funkce GROUP BY je:

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

Attribute_name odkazuje na libovolnou vlastnost dokumentu JSON v kolekci FROM.

Stránkování výsledků dotazu

Vytvoří se instance objektu dotazu s maximální velikostí stránky menší neborovnou 100 záznamů. Pokud chcete získat více stránek, zavolejte metodu nextAsTwin v sadě Node.js SDK nebo metodu GetNextAsTwinAsync v sadě .NET SDK několikrát. Objekt dotazu může zveřejnit více hodnot Next v závislosti na možnosti deserializace vyžadované dotazem. Například objekt dotazu může při použití projekcí vrátit objekty dvojčete nebo úlohy zařízení nebo prostý JSON.

Výrazy a podmínky

Na vysoké úrovni výraz:

Vyhodnotí se jako instance typu JSON (například logická hodnota, číslo, řetězec, pole nebo objekt).
Definuje se manipulací s daty pocházejícími z dokumentu JSON zařízení a konstantami pomocí předdefinovaných operátorů a funkcí.

Podmínky jsou výrazy, které se vyhodnocují jako logická hodnota. Jakákoliv konstanta odlišná od logické hodnoty true se považuje za nepravdivé. Toto pravidlo zahrnuje hodnotu null, nedefinovanou, libovolný objekt nebo instanci pole, libovolný řetězec a logickou hodnotu false.

Syntaxe výrazů je:

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

Informace o tom, co jednotlivé symboly v syntaxi výrazů jsou, najdete v následující tabulce:

Symbol	Definice
Attribute_name	Libovolná vlastnost dokumentu JSON v kolekci FROM
binary_operator	Libovolný binární operátor uvedený v části Operátory .
function_name	Libovolná funkce uvedená v části Funkce .
decimal_literal	Float vyjádřený desetinným zápisem.
hexadecimal_literal	Číslo vyjádřené řetězcem "0x" následované řetězcem šestnáctkových číslic.
string_literal	Řetězce Unicode reprezentované posloupností nula nebo více znaků Unicode nebo řídicích sekvencí. Řetězcové literály jsou uzavřeny v jednoduchých nebo dvojitých uvozovkách. Povolené řídicí objekty: `\'`, `\"`, `\\`pro `\uXXXX` znaky Unicode definované čtyřmi šestnáctkovou číslicí.

Operátory

Podporují se následující operátory:

Rodina	Operátory
Aritmetické	+, -, *, /, %
Logické	A, NEBO, NOT
Porovnání	=, !=, <, >, <=, >=, <>

Functions

Při dotazování dvojčat a úloh je jediná podporovaná funkce:

Funkce	Popis
IS_DEFINED(vlastnost)	Vrátí logickou hodnotu označující, jestli má vlastnost přiřazenou hodnotu (včetně `null`).

V podmínkách tras jsou podporovány následující matematické funkce:

Funkce	Popis
ABS(x)	Vrátí absolutní (kladnou) hodnotu zadaného číselného výrazu.
EXP(x)	Vrátí exponenciální hodnotu zadaného číselného výrazu (e^x).
POWER(x,y)	Vrátí hodnotu zadaného výrazu na zadanou mocninu (x^y).
ČTVEREC(x)	Vrátí druhou mocninu zadané číselné hodnoty.
CEILING(x)	Vrátí nejmenší celočíselnou hodnotu větší nebo rovno zadanému číselnému výrazu.
FLOOR(x)	Vrátí největší celé číslo menší nebo rovno zadanému číselnému výrazu.
SIGN(x)	Vrátí kladné znaménko (+1), nula (0) nebo záporné (-1) zadaného číselného výrazu.
SQRT(x)	Vrátí druhou odmocninu zadané číselné hodnoty.

V podmínkách tras jsou podporovány následující funkce kontroly typu a přetypování:

Funkce	Popis
AS_NUMBER	Převede vstupní řetězec na číslo. `noop` pokud je vstup číslo; `Undefined` pokud řetězec nepředstavuje číslo.
IS_ARRAY	Vrátí logickou hodnotu označující, jestli je typem zadaného výrazu pole.
IS_BOOL	Vrátí logickou hodnotu označující, jestli je typem zadaného výrazu logická hodnota.
IS_DEFINED	Vrátí logickou hodnotu označující, jestli byla vlastnosti přiřazena hodnota. Tato funkce je podporována pouze v případě, že je hodnota primitivním typem. Primitivní typy zahrnují řetězec, logickou hodnotu, číselnou hodnotu nebo `null`. DateTime, typy objektů a pole se nepodporují.
IS_NULL	Vrátí logickou hodnotu označující, jestli je typ zadaného výrazu null.
IS_NUMBER	Vrátí logickou hodnotu označující, jestli je typem zadaného výrazu číslo.
IS_OBJECT	Vrátí logickou hodnotu označující, jestli je typem zadaného výrazu objekt JSON.
IS_PRIMITIVE	Vrátí logickou hodnotu označující, jestli je typ zadaného výrazu primitivní (řetězec, logický, číselný nebo `null`).
IS_STRING	Vrátí logickou hodnotu označující, jestli je typem zadaného výrazu řetězec.

V podmínkách tras jsou podporovány následující řetězcové funkce:

Funkce	Popis
CONCAT(x, y, ...)	Vrátí řetězec, který je výsledkem zřetězení dvou nebo více řetězcových hodnot.
LENGTH(x)	Vrátí počet znaků zadaného řetězcového výrazu.
LOWER(x)	Vrátí řetězcový výraz po převodu dat velkých písmen na malá písmena.
UPPER(x)	Vrátí řetězcový výraz po převodu dat s malými písmeny na velká písmena.
SUBSTRING(řetězec, začátek [; délka])	Vrátí část řetězcového výrazu začínající na zadaném znaku na nulové pozici a pokračuje po zadanou délku nebo na konec řetězce.
INDEX_OF(řetězec, fragment)	Vrátí počáteční pozici prvního výskytu druhého řetězcového výrazu v prvním zadaném řetězcovém výrazu, nebo -1, pokud se řetězec nenajde.
STARTSWITH(x, y)	Vrátí logickou hodnotu označující, zda první řetězcový výraz začíná druhým řetězcem.
ENDSWITH(x, y)	Vrátí logickou hodnotu označující, zda první řetězcový výraz končí druhou.
CONTAINS(x,y)	Vrátí logickou hodnotu označující, zda první řetězcový výraz obsahuje druhý.

Příklady dotazů pomocí sad SDK služby

Příklad jazyka C#

Funkce dotazu je zpřístupněna sadou SDK služby jazyka C# ve třídě RegistryManager .

Tady je příklad jednoduchého dotazu:

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

Objekt dotazu se vytvoří s parametry uvedenými v části stránkování výsledků dotazu . Více stránek se načte voláním metod GetNextAsTwinAsync vícekrát.

Node.js příklad

Funkce dotazu je zpřístupněna sadou SDK služby Azure IoT pro Node.js v objektu Registry .

Tady je příklad jednoduchého dotazu:

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

Objekt dotazu se vytvoří s parametry uvedenými v části stránkování výsledků dotazu . Více stránek se načte voláním metody nextAsTwin vícekrát.

Další kroky

Přečtěte si informace o směrování zpráv na základě vlastností zprávy nebo textu zprávy pomocí syntaxe dotazu směrování IoT Hub zpráv.
Získejte konkrétní příklady dotazů pro dvojčata zařízení a modulů nebo Dotazy pro úlohy.

Dotazovací jazyk služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv

Spouštění dotazů IoT Hub

Základy IoT Hub dotazu

Klauzule SELECT

Klauzule FROM

Klauzule WHERE

Klauzule GROUP BY

Stránkování výsledků dotazu

Výrazy a podmínky

Operátory

Functions

Příklady dotazů pomocí sad SDK služby

Příklad jazyka C#

Node.js příklad

Další kroky

Další materiály