Язык запросов Центра Интернета вещей для двойников устройств и двойников модулей, заданий и маршрутизации сообщений
Центр Интернета вещей предоставляет эффективный язык, похожий на SQL, для получения сведений о двойниках устройств, двойниках модулей и заданиях и маршрутизации сообщений. В этой статье представлены:
- общие сведения об основных возможностях языка запросов Центра Интернета вещей;
- подробное описание языка. Дополнительные сведения о языке запросов для маршрутизации сообщений см. в этой статье.
Конкретные примеры см. в разделах Запросы для двойников устройств и модулей или Запросы для заданий.
Примечание
Некоторые функции, упоминаемые в этой статье, например обмен сообщениями между облаком и устройством, двойники устройств и управление устройствами, доступны только для Центра Интернета вещей уровня "Стандартный". Дополнительные сведения о базовых и стандартных и бесплатных уровнях Центр Интернета вещей см. в статье Выбор подходящего уровня Центр Интернета вещей для решения.
Выполнение запросов Центр Интернета вещей
Вы можете выполнять запросы к центру Интернета вещей непосредственно в портал Azure.
- Войдите на портал Azure и перейдите к своему Центру Интернета вещей.
- Выберите Запросы в разделе Управление устройствами в меню навигации.
- Введите запрос в текстовое поле и выберите Выполнить запрос.
Вы также можете выполнять запросы в приложениях с помощью пакетов SDK для службы Интернета вещей Azure и API служб.
Пример кода, реализующих Центр Интернета вещей запросы, см. в разделе Примеры запросов с пакетами SDK для службы.
Ссылки на справочные страницы и примеры пакета SDK см. в статье Пакеты SDK для Интернета вещей Azure.
Основные сведения о запросе Центра Интернета вещей
Каждый запрос Центра Интернета вещей состоит из предложений SELECT и FROM, а также необязательных предложений WHERE и GROUP BY.
Запросы выполняются для коллекции документов JSON, например двойников устройств. Предложение FROM указывает коллекцию документов для итерации ( devices, devices.modules или devices.jobs).
Затем применяется фильтр в предложении WHERE. С использованием агрегации результаты этого шага сгруппированы, как указано в предложении GROUP BY. Для каждой группы создается строка, как указано в предложении SELECT.
SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]
Предложение SELECT
Предложение SELECT <select_list> требуется в каждом запросе Центр Интернета вещей. Он указывает, какие значения извлекаются из запроса. Здесь задаются значения JSON, которые используются для создания новых объектов JSON. На этапе проекции для каждого элемента, отфильтрованного (и при необходимости сгруппированного) подмножества коллекции FROM создается объект JSON. Этот объект собран из значений, которые указаны в предложении SELECT.
Пример:
Возврат всех значений
SELECT *Возврат определенных свойств
SELECT DeviceID, LastActivityTimeАгрегировать результаты запроса для возврата счетчика
SELECT COUNT() as TotalNumber
В настоящее время предложения выбора, отличные от SELECT , поддерживаются только в статистических запросах двойников устройств.
Следующий синтаксис является грамматикой предложения 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 относится к любому свойству документа JSON в коллекции FROM.
Предложение FROM
Предложение FROM <from_specification> требуется в каждом запросе Центра Интернета вещей. Это должно быть одно из трех значений:
- устройства для запроса двойников устройств
- devices.modules для запроса двойников модулей
- devices.jobs для запроса сведений о задании для каждого устройства
Пример:
Получение всех двойников устройств
SELECT * FROM devices
Предложение WHERE
Предложение WHERE <filter_condition> является необязательным. Оно определяет одно или несколько условий, которым должны соответствовать документы JSON в коллекции FROM, чтобы быть включенными в результат. Любой документ JSON должен при вычислении указанных условий возвращать значение true, чтобы быть включенным в результат.
Пример:
Получение всех заданий, предназначенных для определенного устройства
SELECT * FROM devices.jobs WHERE devices.jobs.deviceId = 'myDeviceId'
Допустимые условия описаны в разделе выражения и условия .
Предложение GROUP BY
Предложение GROUP BY <group_specification> является необязательным. Это предложение выполняется после фильтра, указанного в предложении WHERE, и перед проекцией, указанной в SELECT. Оно группирует документы на основе значения атрибута. Эти группы используются для создания статистических значений, как указано в предложении SELECT.
Пример:
Возвращает количество устройств, которые сообщают о состоянии конфигурации телеметрии
SELECT properties.reported.telemetryConfig.status AS status, COUNT() AS numberOfDevices FROM devices GROUP BY properties.reported.telemetryConfig.status
В настоящее время предложение GROUP BY поддерживается только при запросе к двойникам устройств.
Внимание!
Сейчас термин group обрабатывается как специальное ключевое слово в запросах. Если вы используете group в качестве имени свойства, заключите этот термин в двойные скобки, чтобы избежать ошибок. Например, так: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.
Далее указан формальный синтаксис предложения GROUP BY:
GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name
Attribute_name относится к любому свойству документа JSON в коллекции FROM.
Разбиение результатов запроса на страницы
Объект запроса создается с максимальным размером страницы , который меньше 100 записей или равен 100. Чтобы получить несколько страниц, несколько раз вызовите метод nextAsTwin в пакете SDK Node.js или Метод GetNextAsTwinAsync в пакете SDK для .NET. Объект запроса может предоставлять несколько значений Next в зависимости от параметра десериализации, требуемого для запроса. Например, при использовании проекций объект запроса может возвращать объекты двойника устройства или задания или обычный КОД JSON.
Выражения и условия
В общем выражение:
- возвращает экземпляр типа JSON (например, логическое значение, число, строка, массив или объект);
- определяется обработкой данных, поступающих из документа JSON устройства, и констант с помощью встроенных операторов и функций.
Условия — это выражения, результатом вычисления которых является логическое значение. Любая другая константа, отличная от логической true, считается false. Это правило включает значение null, не определено, любой экземпляр объекта или массива, любую строку и логическое значение false.
Выражения имеют следующий синтаксис:
<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>]+ ']'
Чтобы понять, что означает каждый символ в синтаксисе выражений, ознакомьтесь со следующей таблицей:
| Символ | Определение |
|---|---|
| attribute_name | Любое свойство документа JSON в коллекции FROM. |
| binary_operator | Любой бинарный оператор, перечисленный в разделе Операторы. |
| function_name | Любая функция, перечисленная в разделе Функции. |
| decimal_literal | Число с плавающей запятой в десятичном представлении. |
| hexadecimal_literal | Число, представленное строкой «0x», за которой следует строка с шестнадцатеричными цифрами. |
| string_literal | Строки Юникода, представленные последовательностью из нуля или более символов Юникода или escape-последовательности. Строковые литералы заключаются в одинарные или двойные кавычки. Допустимые экраны: \', \", \\, \uXXXX для символов Юникода, определенных четырьмя шестнадцатеричными цифрами. |
Операторы
Поддерживаются следующие операторы:
| Семейство | Операторы |
|---|---|
| Арифметические | +, -, *, /, % |
| Логические | AND, OR, NOT |
| Сравнение | =, !=, <, >, <=, >=, <> |
Функции
В запросах двойников и заданий поддерживается только одна функция.
| Функция | Описание |
|---|---|
| IS_DEFINED(Свойство) | Возвращает логическое значение, указывающее, назначено ли свойству значение (в том числе значение null). |
В условиях маршрута поддерживаются следующие математические функции.
| Функция | Описание |
|---|---|
| ABS(x) | Возвращает модуль (положительное значение) указанного числового выражения. |
| EXP(x) | Возвращает значение экспоненты для указанного числового выражения (e^x). |
| POWER(x,y) | Возвращает результат возведения указанного числового выражения в заданную степень (x^y). |
| SQUARE(x) | Возвращает квадратный корень из указанного числового значения. |
| CEILING(x) | Возвращает наименьшее целочисленное значение, которое больше или равно указанному числовому выражению. |
| FLOOR(x) | Возвращает наибольшее целое число, меньшее или равное указанному числовому выражению. |
| SIGN(x) | Возвращает знак указанного числового выражения (+1 для положительных чисел, 0 для нуля или -1 для отрицательных). |
| SQRT(x) | Возвращает квадратный корень из указанного числового значения. |
В условиях маршрута поддерживаются следующие функции проверки и приведения типов.
| Функция | Описание |
|---|---|
| AS_NUMBER | Преобразует входную строку в число. noop Значение , если входные данные являются числом; Undefined Значение , если строка не представляет число. |
| IS_ARRAY | Возвращает логическое значение, указывающее, является ли указанное выражение массивом. |
| IS_BOOL | Возвращает логическое значение, указывающее, является ли указанное выражение логическим значением. |
| IS_DEFINED | Возвращает логическое значение, указывающее, назначено ли свойству значение. Эта функция поддерживается, только если значение является примитивным типом. К примитивным относятся строковые, логические, числовые типы, а также тип null. DateTime, типы объектов и массивы не поддерживаются. |
| IS_NULL | Возвращает логическое значение, указывающее, является ли указанное выражение значением Null. |
| IS_NUMBER | Возвращает логическое значение, указывающее, является ли указанное выражение числовым значением. |
| IS_OBJECT | Возвращает логическое значение, указывающее, является ли указанное выражение объектом JSON. |
| IS_PRIMITIVE | Возвращает логическое значение, указывающее, является ли указанное выражение примитивом (строкой, логическим значением, числовым значением или null). |
| IS_STRING | Возвращает логическое значение, указывающее, является ли указанное выражение строковым значением. |
В условиях маршрутов поддерживаются следующие строковые функции.
| Функция | Описание |
|---|---|
| CONCAT(x, y, …) | Возвращает строку, являющуюся результатом объединения двух или более строковых значений. |
| LENGTH(x) | Возвращает число символов указанного строкового выражения. |
| LOWER(x) | Возвращает строковое выражение после преобразования символов верхнего регистра в нижний. |
| UPPER(x) | Возвращает строковое выражение после преобразования символов нижнего регистра в верхний. |
| SUBSTRING(строка, начало[, длина]) | Возвращает часть строкового выражения, начиная с указанной позиции (отсчет начинается с нуля) и до достижения указанной длины (или до конца строки). |
| INDEX_OF(строка, фрагмент) | Возвращает начальную позицию первого вхождения второго строкового выражения в первом указанном строковом выражении или значение -1, если строка не найдена. |
| STARTSWITH(x, y) | Возвращает значение логического типа, указывающее, начинается ли первое строковое выражение вторым. |
| ENDSWITH(x, y) | Возвращает значение логического типа, указывающее, заканчивается ли первое строковое выражение вторым. |
| CONTAINS(x,y) | Возвращает значение логического типа, указывающее, содержит ли первое строковое выражение второе. |
Примеры запросов с помощью пакетов SDK для служб
Пример в C#
Функция обработки запросов предоставляется в пакете SDK для служб C# в классе RegistryManager.
Ниже приведен пример простого запроса:
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
}
}
Экземпляр объекта запроса создается с параметрами, упомянутыми в разделе разбиения результатов запроса на страницы . Несколько страниц извлекаются путем многократного вызова методов GetNextAsTwinAsync .
Пример для Node.js
Функция обработки запросов предоставляется в пакете SDK службы Azure IoT для Node.js в объекте Registry.
Ниже приведен пример простого запроса:
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);
Экземпляр объекта запроса создается с параметрами, упомянутыми в разделе разбиения результатов запроса на страницы . Несколько страниц извлекаются путем многократного вызова метода nextAsTwin .
Дальнейшие действия
- Сведения о маршрутизации сообщений на основе свойств сообщения или текста сообщения с помощью синтаксиса запроса маршрутизации сообщений Центр Интернета вещей.
- Получение конкретных примеров запросов для двойников устройств и модулей или запросов для заданий.