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

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

Úvod do hlavních funkcí dotazovacího jazyka IoT Hubu a
Podrobný popis jazyka. Další informace o dotazovacím jazyce pro směrování zpráv najdete v tématu Syntaxe dotazů směrování zpráv služby IoT Hub.

Konkrétní příklady najdete v tématu Dotazy pro dvojčata zařízení a moduly ioT Hubu nebo dotazy pro úlohy IoT Hubu.

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 Basic a Standard/Free IoT Hub najdete v tématu Volba správné úrovně a velikosti služby IoT Hub pro vaše řešení.

Spouštění dotazů ioT Hubu

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

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

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

Příklad kódu, který implementuje dotazy IoT Hubu, najdete v příkladech dotazů v části Sady SDK služby.

Odkazy na referenční stránky a ukázky sady SDK najdete v sadách SDK služby Azure IoT Hub.

Základy dotazu IoT Hubu

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

Dotazy se spouští v kolekci dokumentů JSON, například na digitálních dvojčatech zařízení. Klauzule FROM definuje kolekci dokumentů, která má být procházená (buď zařízení, devices.modules nebo devices.jobs).

Pak se použije filtr v klauzuli WHERE. S agregacemi jsou výsledky tohoto kroku seskupené podle klauzule GROUP BY. Pro každou skupinu se vygeneruje řádek zadaný v klauzuli 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 Hubu. Určuje, jaké hodnoty se z dotazu načtou. Určuje hodnoty JSON, které se mají použít k vygenerování nových objektů JSON. Pro každý prvek filtrované (a volitelně seskupené) podmnožině kolekce FROM vygeneruje fáze projekce nový objekt JSON. Tento objekt je vytvořen s hodnotami zadanými v klauzuli SELECT.

Příklad:

Vrácení všech hodnot
```
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 podporovány 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í k dotazování digitálních dvojčat
devices.modules k dotazování modulových dvojníků
devices.jobs k dotazování na podrobnosti úloh pro jednotlivá zařízení

Příklad:

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

Klauzule WHERE

Klauzule WHERE <filter_condition> je nepovinná. 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 na true, aby se do výsledku zahrnuly.

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 popsány v části Výrazy a podmínky .

Klauzule GROUP BY

Klauzule GROUP BY <group_specification> je volitelná. Tato klauzule se spustí za filtrem zadaným v klauzuli WHERE a před projekcí určenou v select. Seskupuje dokumenty na základě hodnoty atributu. Tyto skupiny se používají k vygenerování agregovaných hodnot, jak je uvedeno v klauzuli SELECT.

Příklad:

Vrátí počet zařízení, která hlásí každý 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 pouze při dotazování dvojčat zařízení.

Upozornění

group Termín se v dotazech aktuálně považuje za speciální klíčové slovo. V případě, že použijete group jako název vlastnosti, zvažte jeho obklopení dvojitými hranatými závorkami, abyste se vyhnuli chybám, jak je znázorněno v tomto příkladu: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

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ů dotazů

Objekt dotazu je instanciován s maximální velikostí stránky menší nebo rovnou 100 záznamům. Pokud chcete získat více stránek, volejte nextAsTwin na Node.js SDK nebo GetNextAsTwinAsync v metodě .NET SDK několikrát. Objekt dotazu může v závislosti na možnosti deserializace vyžadované dotazem zveřejnit více hodnot Další. Například objekt dotazu může při použití projekce vrátit dvojče zařízení nebo objekty úloh nebo prostý JSON.

Výrazy a podmínky

Na obecné úrovni, výraz::

Vyhodnotí se jako příklad 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 konstant pomocí předdefinovaných operátorů a funkcí.

Podmínky jsou výrazy, které se vyhodnocují jako logická hodnota. Každá konstanta odlišná od logické hodnoty true se považuje za false. Toto pravidlo zahrnuje hodnotu null, nedefinovanou, libovolnou instanci objektu nebo 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>]+ ']'

Pokud chcete zjistit, jaké jsou jednotlivé symboly v syntaxi výrazů, přečtěte si následující tabulku:

Symbol	Definice
attribute_name	Libovolná vlastnost dokumentu JSON v kolekci FROM
binární operátor	Libovolný binární operátor uvedený v části Operátory .
function_name	Jakákoli funkce uvedená v části Funkce.
desetinný literál	Plovoucí hodnota 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 únikových sekvencí. Řetězcové literály jsou uzavřeny v jednoduchých uvozovkách nebo dvojitých uvozovkách. Povolené escape sekvence: `\'`, `\"`, `\\`, `\uXXXX` pro znaky Unicode definované čtyřmi šestnáctkovými číslicemi.

Operátory

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

Rodina	Operátory
Aritmetika	+, -, *, /, %
Logický	A NEBO NE
Porovnání	=, !=, <, >, <=, >=, <>

Funkce

Při dotazování na dvojčata a úlohy je jedinou podporovanou funkcí:

Funkce	Popis
IS_DEFINED(vlastnost)	Vrátí logickou hodnotu označující, zda je vlastnost přiřazena hodnota (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).
SQUARE(x)	Vrací druhou mocninu zadané číselné hodnoty.
ZAOKROUHLENÍ NAHORU(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.
ZNAMÉNKO(x)	Vrátí kladné znaménko (+1), nula (0) nebo záporné znaménko (-1) zadaného číselného výrazu.
SQRT(x)	Vrátí druhou odmocninu zadané číselné hodnoty.

U trasových podmínek jsou podporovány následující funkce pro kontrolu a přetypování typů:

Funkce	Popis
AS_NUMBER	Převede vstupní řetězec na číslo. `noop` je-li vstup číslo; `Undefined` pokud řetězec nepředstavuje číslo.
IS_ARRAY	Vrátí logickou hodnotu označující, zda je typ zadaného výrazu pole.
IS_BOOL	Vrátí hodnotu typu Boolean, která označuje, zda je typ zadaného výrazu Boolean.
JE_DEFINOVÁNO	Vrátí logickou hodnotu označující, zda je vlastnost hodnotou. 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 nejsou podporované.
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 typ 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á hodnota, číselná hodnota 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 velkých písmen na malá písmena.
UPPER(x)	Vrátí řetězcový výraz po převodu malých písmen na velká písmena.
SUBSTRING(řetězec, začátek [; délka])	Vrátí část řetězcového výrazu začínající na zadané pozici nulového znaku a pokračuje na 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 rámci prvního zadaného řetězcového výrazu nebo -1, pokud řetězec nebyl nalezen.
STARTS_WITH(x; y)	Vrátí Boolean označující, jestli první řetězcový výraz začíná druhým výrazem.
ENDS_WITH(x; y)	Vrátí logickou hodnotu označující, jestli první řetězcový výraz končí druhým.
CONTAINS(x;y)	Vrátí logickou hodnotu určující, zda první řetězcový výraz obsahuje druhý výraz.

Příklady dotazů pomocí služebních sad SDK

Příklad jazyka C#

Funkce dotazu je zpřístupněna sadou SDK služby Azure IoT Hub pro .NET 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 pro dotaz je inicializován s parametry uvedenými v části stránkování výsledků dotazu. Více stránek je načítáno opakovaným voláním metod GetNextAsTwinAsync.

příklad Node.js

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

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 je instancován s parametry uvedenými v části stránkování výsledků dotazu. Více stránek se načte voláním metody nextAsTwin několikrát.

Další kroky

Seznamte se se směrováním zpráv na základě vlastností zprávy nebo textu zprávy pomocí syntaxe dotazu směrování zpráv služby IoT Hub.
Získejte konkrétní příklady dotazů na zařízení a dvojčata modulů ioT Hubu nebo dotazy pro úlohy IoT Hubu.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-04-03

Sdílet prostřednictvím

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 Hubu

Základy dotazu IoT Hubu

Klauzule SELECT

Klauzule FROM

Klauzule WHERE

Klauzule GROUP BY

Stránkování výsledků dotazů

Výrazy a podmínky

Operátory

Funkce

Příklady dotazů pomocí služebních sad SDK

Příklad jazyka C#

příklad Node.js

Další kroky

Váš názor

Další materiály