Język zapytań usługi IoT Hub dla urządzeń i bliźniaczych reprezentacji modułów, zadań i routingu komunikatów

Artykuł
08/15/2023

IoT Hub zapewnia zaawansowany język przypominający 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:

Wprowadzenie do głównych funkcji języka zapytań IoT Hub oraz
Szczegółowy opis języka. Aby uzyskać szczegółowe informacje na temat języka zapytań na potrzeby routingu komunikatów, zobacz zapytania w routingu komunikatów.

Aby zapoznać się z konkretnymi przykładami, zobacz Zapytania dotyczące bliźniaczych reprezentacji urządzeń i modułów lub Zapytania dotyczące zadań.

Uwaga

Niektóre funkcje wymienione w tym artykule, takie jak obsługa komunikatów w chmurze, bliźniacze reprezentacje urządzeń i zarządzanie urządzeniami, są dostępne tylko w warstwie Standardowa IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowych i standardowych/bezpłatnych IoT Hub, zobacz Wybieranie odpowiedniej warstwy IoT Hub dla rozwiązania.

Uruchamianie zapytań IoT Hub

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

Zaloguj się do Azure Portal i przejdź do centrum IoT Hub.
Wybierz pozycję Zapytania w sekcji Zarządzanie urządzeniami w menu nawigacji.
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ług.

Na przykład kod implementowania zapytań 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.

Podstawy zapytania IoT Hub

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

Zapytania są uruchamiane w kolekcji dokumentów JSON, na przykład bliźniaczych reprezentacji urządzeń. Klauzula FROM wskazuje kolekcję dokumentów do iteracji (urządzenia, urządzenia.modules lub devices.jobs).

Następnie filtr w klauzuli WHERE jest stosowany. W przypadku agregacji wyniki tego kroku są pogrupowane zgodnie z klauzulą 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 IoT Hub. Określa ona, 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:

Zwracanie wszystkich wartości
```
SELECT *
```
Zwracanie określonych właściwości
```
SELECT DeviceID, LastActivityTime
```
Agregowanie wyników zapytania w celu zwrócenia liczby
```
SELECT COUNT() as TotalNumber
```

Obecnie klauzule wyboru inne niż SELECT są obsługiwane tylko w zapytaniach agregacji na bliźniaczych reprezentacjach urządzeń.

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 bliźniaczych reprezentacji urządzeń
devices.modules do wykonywania zapytań dotyczących bliźniaczych reprezentacji modułów
devices.jobs do wykonywania zapytań dotyczących zadań dla poszczególnych urządzeń

Na przykład:

Pobieranie wszystkich bliźniaczych reprezentacji urządzeń
```
SELECT * FROM devices
```

Klauzula WHERE

Klauzula WHERE <filter_condition> jest opcjonalna. Określa jeden lub więcej warunków, które 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:

Pobieranie wszystkich zadań przeznaczonych dla określonego urządzenia

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

Dozwolone warunki są opisane w sekcji wyrażenia i warunki .

GROUP BY, klauzula

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 każdej telemetrii

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 w przypadku wykonywania zapytań dotyczących bliźniaczych reprezentacji urządzenia.

Przestroga

Termin group jest obecnie traktowany jako specjalne słowo kluczowe w zapytaniach. W przypadku, gdy używasz group nazwy właściwości, rozważ jego otaczanie podwójnym nawiasem, aby uniknąć błędów, np. SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

Formalna składnia grupy 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 tworzone za pomocą maksymalnego rozmiaru strony mniejszego lubrównego 100 rekordom. 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 opcji deserializacji wymaganej przez zapytanie. Na przykład obiekt zapytania może zwracać obiekty bliźniaczej reprezentacji urządzenia lub zadania albo zwykły kod JSON podczas korzystania z projekcji.

Wyrażenia i warunki

Na wysokim poziomie wyrażenie:

Oblicza wystąpienie typu JSON (na przykład wartość logiczna, liczba, ciąg, 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 oceniają wartość logiczną. Każda stała inna niż wartość logiczna true jest uznawana za fałsz. Ta reguła obejmuje null, niezdefiniowane, dowolne wystąpienie obiektu lub tablicy, dowolny ciąg i 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
Attribute_name	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 .
decimal_literal	Zmiennoprzecinkowy wyrażony 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ę zera lub większej liczby znaków Unicode lub sekwencji ucieczki. Literały ciągu są ujęte w cudzysłowy pojedyncze lub cudzysłowy podwójne. Dozwolone ucieczki: `\'`, `\"\\\uXXXX` dla znaków Unicode zdefiniowanych przez cztery cyfry szesnastkowe.

Operatory

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

Family	Operatory
Arytmetyczny	+, -, *, /, %
Wartości logiczne	AND, OR, NOT
Porównanie	=, !=, <, >, <=, >=, <>

Funkcje

Podczas wykonywania zapytań dotyczących bliźniaczych reprezentacji i zadań jedyną obsługiwaną funkcją jest:

Funkcja	Opis
IS_DEFINED(właściwość)	Zwraca wartość logiczną wskazującą, czy właściwość została przypisana do wartości (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).
POWER(x,y)	Zwraca wartość określonego wyrażenia do określonej mocy (x^y).
SQUARE(x)	Zwraca kwadrat określonej wartości liczbowej.
CEILING(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ą.
SIGN(x)	Zwraca dodatni znak (+1), zero (0) lub ujemny (-1) określonego wyrażenia liczbowego.
SQRT(x)	Zwraca pierwiastek kwadratowy określonej wartości liczbowej.

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

Funkcja	Opis
AS_NUMBER	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ą.
IS_DEFINED	Zwraca wartość logiczną wskazującą, do właściwości przypisano wartość. Ta funkcja jest obsługiwana tylko wtedy, gdy wartość jest typem pierwotnym. Typy pierwotne obejmują ciąg, wartość logiczną, liczbową lub `null`. Data/godzina, 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 tras obsługiwane są następujące funkcje ciągu:

Funkcja	Opis
CONCAT(x, y, ...)	Zwraca ciąg, który jest wynikiem połączenia co najmniej dwóch wartości ciągu.
LENGTH(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ślonego znaku zero-based position i kontynuuje określoną długość lub na końcu ciągu.
INDEX_OF(ciąg, 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.
STARTSWITH(x, y)	Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu rozpoczyna się od drugiego.
ENDSWITH(x, y)	Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu kończy się drugim.
CONTAINS(x,y)	Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu zawiera drugie.

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

Przykład języka C#

Funkcjonalność zapytania jest uwidoczniona przez zestaw SDK usługi języka C# 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 tworzone za pomocą parametrów wymienionych w sekcji stronicowania wyników zapytania . Wiele stron jest pobieranych przez wywołanie metod GetNextAsTwinAsync wiele razy.

przykład Node.js

Funkcjonalność zapytania jest uwidoczniona przez zestaw SDK usługi Azure IoT dla Node.js w obiekcie Rejestru .

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 stronicowania wyników zapytania . Wiele stron jest pobieranych przez wywołanie metody nextAsTwin wiele razy.

Następne kroki

Dowiedz się więcej o routingu komunikatów na podstawie właściwości komunikatów lub treści komunikatów przy użyciu składni zapytania routingu komunikatów IoT Hub.
Uzyskaj konkretne przykłady zapytań dotyczących bliźniaczych reprezentacji urządzeń i modułów lub zapytań dotyczących zadań.

Język zapytań usługi IoT Hub dla urządzeń i bliźniaczych reprezentacji modułów, zadań i routingu komunikatów

Uruchamianie zapytań IoT Hub

Podstawy zapytania IoT Hub

Klauzula SELECT

Klauzula FROM

Klauzula WHERE

GROUP BY, klauzula

Stronicowanie wyników zapytania

Wyrażenia i warunki

Operatory

Funkcje

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

Przykład języka C#

przykład Node.js

Następne kroki

Dodatkowe zasoby