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.

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í.

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:

Operátory

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

Functions

Při dotazování dvojčat a úloh je jedinou podporovanou funkcí:

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

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

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

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.