Język zapytań usługi IoT Hub dla urządzeń i bliźniaczych reprezentacji modułów, zadań i routingu 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:
- Wprowadzenie do głównych funkcji języka zapytań usługi IoT Hub i
- 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 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 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.
- Zaloguj się do witryny 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ł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.
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ą uruchamiane w kolekcji dokumentów JSON, na przykład bliźniaczych reprezentacji urządzeń. Klauzula FROM wskazuje, że kolekcja dokumentów ma być iteracja (urządzenia, urządzenia.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:
Zwracanie wszystkich wartości
SELECT *Zwracanie określonych właściwości
SELECT DeviceID, LastActivityTimeAgregowanie 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 w 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ń o bliźniacze reprezentacje modułów
- devices.jobs, aby wykonać zapytanie o szczegóły zadania 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 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:
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 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 reprezentacji urządzeń.
Uwaga
group Termin jest obecnie traktowany jako specjalne słowo kluczowe w zapytaniach. W przypadku, gdy używasz group nazwy właściwości, rozważ jej otaczanie podwójnym nawiasem, aby uniknąć błędów, np. 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 tworzone przy użyciu maksymalnego rozmiaru strony mniejszego lub ró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 uważana za fałsz. Ta reguła zawiera wartość null, niezdefiniowaną, dowolny obiekt lub wystąpienie 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 | 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ę znaków Unicode lub więcej znaków Unicode lub sekwencje ucieczki. Literały ciągu są ujęte w cudzysłów pojedynczych lub podwójnych cudzysłowów. Dozwolone znaki ucieczki: \', , \uXXXX \"\\dla znaków Unicode zdefiniowanych przez cztery cyfry szesnastkowe. |
Operatory
Obsługiwane są następujące operatory:
| Rodzina | Operatory |
|---|---|
| Arytmetyczny | +, -, *, /, % |
| Wartość logiczna | AND, OR, NOT |
| Porównanie | =, !=, <, ><=, =, >=,<> |
Funkcje
Podczas wykonywania zapytań dotyczących bliźniaczych reprezentacji bliźniaczych i zadań jedyną obsługiwaną funkcją jest:
| Function | opis |
|---|---|
| IS_DEFINED(właściwość) | Zwraca wartość logiczną wskazującą, czy właściwość została przypisana wartość (w tym null). |
W warunkach tras obsługiwane są następujące funkcje matematyczne:
| Function | 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ń:
| Function | 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. 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 tras obsługiwane są następujące funkcje ciągów:
| Function | 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 w języku 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 uwidaczniona przez zestaw SDK usługi Azure IoT 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 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 usługi IoT Hub.
- Uzyskaj konkretne przykłady zapytań dotyczących bliźniaczych reprezentacji urządzeń i modułów lub zapytań dotyczących zadań.