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.

1. Přihlaste se k webu Azure Portal a přejděte do centra IoT.
2. V navigační nabídce vyberte Dotazy v části Správa zařízení.
3. 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, 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í 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ší neborovnou 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í	=, !=, <, , <>=, >=,<>

Functions

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.