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. Podrobnosti o dotazovacím jazyce pro směrování zpráv najdete v dotazech 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 Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu 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 můžete také spouštět ve svých aplikacích pomocí sad SDK služby Azure IoT a rozhraní API služeb.
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 AZURE IoT SDK.
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 dvojčata zařízení. Klauzule FROM označuje kolekci dokumentů, která má být iterated na ( 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, LastActivityTimeAgregace 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í dvojčat zařízení
- devices.modules pro dotazování dvojčat modulů
- devices.jobs dotazování úloh na 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 jako název vlastnosti použijete group , zvažte jeho obklopení dvojitými hranatými závorkami, abyste se vyhnuli chybám, například 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 se vytvoří instance s maximální velikostí stránky menší nebo rovnou 100 záznamům. Pokud chcete získat více stránek, zavolejte 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
Výraz na vysoké úrovni:
- 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 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 |
| binary_operator | Libovolný binární operátor uvedený v části Operátory . |
| function_name | Všechny funkce uvedené v části Funkce . |
| decimal_literal | 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 řídicích sekvencí. Řetězcové literály jsou uzavřeny v jednoduchých uvozovkách nebo dvojitých uvozovkách. Povolené řídicí znaky: \', , \\\"\uXXXX pro znaky Unicode definované čtyřmi šestnáctkovými číslicemi. |
Operátory
Podporují se následující operátory:
| Rodina | Operátory |
|---|---|
| Aritmetické | +, -, *, /, % |
| Logický | A NEBO NE |
| Porovnání | =, !=, <, , <>=, >=,<> |
Funkce
Při dotazování dvojčat a úloh je jedinou podporovanou funkcí:
| Function | Popis |
|---|---|
| IS_DEFINED(vlastnost) | Vrátí logickou hodnotu označující, jestli byla vlastnost přiřazena hodnota (včetně null). |
V podmínkách tras jsou podporovány následující matematické funkce:
| Function | 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) | 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é znaménko (-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 typů a přetypování:
| Function | 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í logickou hodnotu označující, jestli je typ zadaného výrazu logická hodnota. |
| IS_DEFINED | Vrátí logickou hodnotu označující, zda byla vlastnost 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. Datum a čas, typy objektů a pole nejsou podporovány. |
| 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:
| Function | 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. |
| STARTSWITH(x; y) | Vrátí logickou hodnotu označující, jestli první řetězcový výraz začíná druhým. |
| ENDSWITH(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í sad SDK služby
Příklad jazyka C#
Funkce dotazu je vystavena 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ří instance s parametry uvedenými v části stránkování výsledků dotazu. Více stránek se načte voláním metod GetNextAsTwinAsync několikrát.
příklad Node.js
Funkce dotazu je zpřístupněna sadou SDK služby Azure IoT 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 se vytvoří instance 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ů pro dvojčata zařízení a modulů nebo dotazy pro úlohy.