Udostępnij za pośrednictwem

Język zapytań usługi IoT Hub dla urządzeń, zdublowanych modułów, zadań i trasowania komunikatów

Usługa IoT Hub udostępnia zaawansowany język przypominający język SQL do pobierania informacji dotyczących bliźniaczych reprezentacji urządzeń, bliźniaczych reprezentacji modułów, zadań i routingu komunikatów. W tym artykule przedstawiono następujące elementy:

Aby zobaczyć konkretne przykłady, zobacz Zapytania dotyczące urządzeń i modulów typu bliźniak w IoT Hub lub Zapytania dotyczące zadań w IoT Hub.

Uwaga

Niektóre funkcje wymienione w tym artykule, takie jak przesyłanie komunikatów z chmury do urządzenia, bliźniaczy stan urządzeń i zarządzanie urządzeniami, są dostępne tylko w warstwie standardowej usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy i rozmiaru usługi IoT Hub dla rozwiązania.

Uruchamianie zapytań usługi IoT Hub

Zapytania dotyczące centrum IoT można uruchamiać bezpośrednio w witrynie Azure Portal.

  1. Zaloguj się do witryny Azure Portal i przejdź do centrum IoT Hub.
  2. Wybierz pozycję Zapytania w sekcji Zarządzanie urządzeniami w menu nawigacji.
  3. Wprowadź zapytanie w polu tekstowym i wybierz pozycję Uruchom zapytanie.

Zapytania można również uruchamiać w aplikacjach przy użyciu zestawów SDK usługi Azure IoT i interfejsów API usługi.

Na przykład kod implementowania zapytań usługi IoT Hub można znaleźć w sekcji Przykłady zapytań z zestawami SDK usługi.

Aby uzyskać linki do stron referencyjnych i przykładów zestawu SDK, zobacz Zestawy SDK usługi Azure IoT Hub.

Podstawy zapytania usługi IoT Hub

Każde zapytanie usługi IoT Hub składa się z klauzul SELECT i FROM z opcjonalnymi klauzulami WHERE i GROUP BY.

Zapytania są wykonywane na kolekcji dokumentów JSON, na przykład bliźniaków urządzeń. Klauzula FROM wskazuje kolekcję dokumentów, która ma być iterowana (devices, devices.modules lub devices.jobs).

Następnie filtr w klauzuli WHERE jest stosowany. W przypadku agregacji wyniki tego kroku są grupowane zgodnie z opisem w klauzuli GROUP BY. Dla każdej grupy wiersz jest generowany zgodnie z opisem w klauzuli SELECT.

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

Klauzula SELECT

Klauzula SELECT <select_list> jest wymagana w każdym zapytaniu usługi IoT Hub. Określa, jakie wartości są pobierane z zapytania. Określa wartości JSON, które mają być używane do generowania nowych obiektów JSON. Dla każdego elementu filtrowanego (i opcjonalnie pogrupowanego) podzestawu kolekcji FROM faza projekcji generuje nowy obiekt JSON. Ten obiekt jest konstruowany z wartościami określonymi w klauzuli SELECT.

Na przykład:

  • Zwróć wszystkie wartości

    SELECT *

  • Zwracanie określonych właściwości

    SELECT DeviceID, LastActivityTime

  • Zagreguj wyniki zapytania, aby zwrócić liczbę.

    SELECT COUNT() as TotalNumber

Obecnie klauzule wyboru inne niż SELECT są obsługiwane tylko w zapytaniach agregacyjnych w bliźniaczych urządzeniach.

Następująca składnia to gramatyka klauzuli 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 odnosi się do dowolnej właściwości dokumentu JSON w kolekcji FROM.

Klauzula FROM

Klauzula FROM <from_specification> jest wymagana w każdym zapytaniu usługi ioT Hub. Musi to być jedna z trzech wartości:

  • urządzenia do wykonywania zapytań dotyczących urządzeń-bliźniaczych
  • devices.modules aby zapytać o bliźniacze moduły
  • devices.jobs, aby zapytać o szczegóły zadań dla każdego urządzenia

Na przykład:

  • Pobierz wszystkie bliźniacze urządzenia

    SELECT * FROM devices

Klauzula WHERE

Klauzula WHERE <filter_condition> jest opcjonalna. Określa co najmniej jeden warunek, który dokumenty JSON w kolekcji FROM muszą spełniać, aby zostały uwzględnione w ramach wyniku. Każdy dokument JSON musi ocenić określone warunki na wartość "true", która ma zostać uwzględniona w wyniku.

Na przykład:

  • Pobierz wszystkie zadania przeznaczone dla określonego urządzenia

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

Dozwolone warunki opisano w sekcji Wyrażenia i warunki .

klauzula GROUP BY

Klauzula GROUP BY <group_specification> jest opcjonalna. Ta klauzula jest wykonywana po filtrze określonym w klauzuli WHERE i przed projekcją określoną w elemecie SELECT. Grupuje dokumenty na podstawie wartości atrybutu. Te grupy są używane do generowania zagregowanych wartości określonych w klauzuli SELECT.

Na przykład:

  • Zwraca liczbę urządzeń, które zgłaszają stan konfiguracji poszczególnych danych telemetrycznych

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

Obecnie klauzula GROUP BY jest obsługiwana tylko podczas wykonywania zapytań dotyczących bliźniaczych modeli urządzeń.

Uwaga

group Termin jest obecnie traktowany jako specjalne słowo kluczowe w zapytaniach. Jeśli używasz group jako nazwy właściwości, rozważ otoczenie jej podwójnymi nawiasami, aby uniknąć błędów, jak pokazano w tym przykładzie: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

Formalna składnia GROUP BY to:

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

Attribute_name odnosi się do dowolnej właściwości dokumentu JSON w kolekcji FROM.

Stronicowanie wyników zapytania

Obiekt zapytania jest tworzony przy użyciu maksymalnego rozmiaru strony mniejszy lub równy 100 rekordów. Aby uzyskać wiele stron, wywołaj metodę nextAsTwin w Node.js SDK lub GetNextAsTwinAsync w metodzie .NET SDK wiele razy. Obiekt zapytania może uwidocznić wiele wartości "dalej", w zależności od wymagań zapytania dotyczących opcji deserializacji. Na przykład obiekt zapytania może zwracać obiekty bliźniacze urządzenia, obiekty zadania lub zwykły kod JSON przy używaniu projekcji.

Wyrażenia i warunki

Na wysokim poziomie wyrażenie jest:

  • Wyznacza instancję typu JSON (taką jak wartość logiczna, liczba, ciąg znaków, tablica lub obiekt).
  • Jest definiowany przez manipulowanie danymi pochodzącymi z dokumentu JSON urządzenia i stałymi przy użyciu wbudowanych operatorów i funkcji.

Warunki to wyrażenia, które dają wartość logiczną. Każda stała inna niż logiczna true jest uważana za fałsz. Ta reguła zawiera null, wartość niezdefiniowaną, dowolny obiekt lub wystąpienie tablicy, dowolny łańcuch znaków oraz wartość logiczną false.

Składnia wyrażeń to:

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

Aby zrozumieć, co oznacza każdy symbol w składni wyrażeń, zapoznaj się z następującą tabelą:

Symbol Definicja
nazwa_atrybutu Dowolna właściwość dokumentu JSON w kolekcji FROM .
binary_operator Dowolny operator binarny wymieniony w sekcji Operatory .
function_name Dowolna funkcja wymieniona w sekcji Funkcje .
liczba dziesiętna Liczba zmiennoprzecinkowa wyrażona w notacji dziesiętnej.
hexadecimal_literal Liczba wyrażona przez ciąg "0x", po którym następuje ciąg cyfr szesnastkowych.
string_literal Ciągi Unicode reprezentowane przez sekwencję zero lub więcej znaków Unicode lub sekwencje ucieczki. Literały ciągu są ujęte w pojedyncze lub podwójne cudzysłowy. Dozwolone znaki ucieczki: \', \", \\, \uXXXX dla znaków Unicode zdefiniowanych przez cztery cyfry szesnastkowe.

Operatory

Obsługiwane są następujące operatory:

Rodzina Operatorzy
Arytmetyka +, -, *, /, %
Logiczny I, LUB, NIE
Porównanie =, !=, <, >, <=, >=, <>

Funkcje

Podczas wykonywania zapytań do bliźniaków i zadań jedyną obsługiwaną funkcją jest:

Funkcja opis
IS_DEFINED(właściwość) Zwraca wartość logiczną wskazującą, czy właściwość ma przypisaną wartość (w tym null).

W warunkach tras obsługiwane są następujące funkcje matematyczne:

Funkcja opis
ABS(x) Zwraca wartość bezwzględną (dodatnią) podanego wyrażenia liczbowego.
EXP(x) Zwraca wartość wykładniczą określonego wyrażenia liczbowego (e^x).
POTĘGA(x,y) Zwraca wartość określonego wyrażenia do określonej mocy (x^y).
SQUARE(x) Zwraca kwadrat określonej wartości liczbowej.
SUFIT(x) Zwraca najmniejszą wartość całkowitą równą określonemu wyrażeniu liczbowemu lub większą.
FLOOR(x) Zwraca największą wartość całkowitą równą określonemu wyrażeniu liczbowemu lub mniejszą.
ZNAK(x) Zwraca dodatni znak (+1), zero (0) lub ujemny (-1) określonego wyrażenia liczbowego.
sqrt(x) Zwraca pierwiastek kwadratowy podanej wartości liczbowej.

W warunkach tras obsługiwane są następujące funkcje sprawdzania typów i rzutowań.

Funkcja opis
Numer AS Konwertuje ciąg wejściowy na liczbę. noop jeśli dane wejściowe są liczbą; Undefined jeśli ciąg nie reprezentuje liczby.
IS_ARRAY Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest tablicą.
IS_BOOL Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest wartością logiczną.
JEST_ZDEFINIOWANY Zwraca wartość logiczną wskazującą, czy właściwość jest wartością. Ta funkcja jest obsługiwana tylko wtedy, gdy wartość jest typem pierwotnym. Typy pierwotne obejmują łańcuch znaków, wartość logiczną, liczbę lub null. Funkcja DateTime, typy obiektów i tablice nie są obsługiwane.
IS_NULL Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia ma wartość null.
IS_NUMBER Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest liczbą.
IS_OBJECT Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest obiektem JSON.
IS_PRIMITIVE Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest pierwotny (ciąg, wartość logiczna, numeryczna lub null).
IS_STRING Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest ciągiem.

W warunkach dotyczących tras obsługiwane są następujące funkcje ciągów:

Funkcja opis
CONCAT(x, y, ...) Zwraca ciąg, który jest wynikiem połączenia co najmniej dwóch wartości ciągu.
DŁUGOŚĆ(x) Zwraca liczbę znaków określonego wyrażenia ciągu.
LOWER(x) Zwraca wyrażenie ciągu po przekonwertowaniu danych znakowych wielkich liter na małe litery.
UPPER(x) Zwraca wyrażenie ciągu po przekonwertowaniu danych znakowych małych liter na wielkie litery.
SUBSTRING(ciąg, początek [, długość]) Zwraca część wyrażenia ciągu rozpoczynającą się od określonej pozycji, liczonej od zera, i kontynuuje na określoną długość lub do końca ciągu.
INDEX_OF(łańcuch, fragment) Zwraca pozycję początkową pierwszego wystąpienia drugiego wyrażenia ciągu w pierwszym określonym wyrażeniu ciągu lub -1, jeśli ciąg nie zostanie znaleziony.
STARTS_WITH(x, y) (sprawdza, czy x zaczyna się od y) Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu znaków rozpoczyna się od drugiego.
KOŃCZY_SIĘ(x, y) Zwraca wartość logiczną typu Boolean wskazującą, czy pierwszy ciąg znaków kończy się drugim.
CONTAINS(x,y) Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu znaków zawiera drugie.

Przykłady zapytań przy użyciu zestawów SDK usługi

Przykład w języku C#

Funkcje zapytania są udostępniane przez zestaw SDK usługi Azure IoT Hub dla platformy .NET w klasie RegistryManager .

Oto przykład prostego zapytania:

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

Obiekt zapytania jest tworzony za pomocą parametrów wymienionych w sekcji stronicowanie wyników zapytania. Wiele stron jest pobieranych przez wywołanie metod GetNextAsTwinAsync wiele razy.

przykład Node.js

Funkcje zapytań są udostępniane przez zestaw SDK usługi Azure IoT Hub dla Node.js w obiekcie Registry .

Oto przykład prostego zapytania:

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

Obiekt zapytania jest tworzone za pomocą parametrów wymienionych w sekcji stronicowanie wyników zapytania . Wiele stron jest pobieranych przez wywołanie metody nextAsTwin wiele razy.

Następne kroki