Udostępnij za pośrednictwem


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.

  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.

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