Язык запросов Центра Интернета вещей для двойников устройств и двойников модулей, заданий и маршрутизации сообщений
Центр Интернета вещей предоставляет эффективный язык, похожий на SQL, для получения сведений о двойниках устройств, двойниках модулей и заданиях и маршрутизации сообщений. В этой статье представлены:
- общие сведения об основных возможностях языка запросов Центра Интернета вещей;
- подробное описание языка. Дополнительные сведения о языке запросов для маршрутизации сообщений см. в этой статье.
Конкретные примеры см. в разделе "Запросы для двойников устройств и модулей" или "Запросы для заданий".
Примечание.
Некоторые функции, упоминаемые в этой статье, например обмен сообщениями между облаком и устройством, двойники устройств и управление устройствами, доступны только для Центра Интернета вещей уровня "Стандартный". Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.
Выполнение запросов Центр Интернета вещей
Запросы к центру Интернета вещей можно выполнять непосредственно в портал Azure.
- Войдите на портал Azure и перейдите к своему Центру Интернета вещей.
- Выберите запросы в разделе управления устройствами в меню навигации.
- Введите запрос в текстовое поле и нажмите кнопку "Выполнить запрос".
Вы также можете выполнять запросы в приложениях с помощью пакетов SDK службы Интернета вещей Azure и API-интерфейсов служб.
Примеры кода, реализующие запросы Центр Интернета вещей, см. в примерах запросов с разделом пакетов SDK службы.
Ссылки на справочные страницы и примеры пакета SDK см . в пакетах SDK для Интернета вещей Azure.
Основные сведения о запросе Центра Интернета вещей
Каждый запрос Центра Интернета вещей состоит из предложений SELECT и FROM, а также необязательных предложений WHERE и GROUP BY.
Запросы выполняются в коллекции документов JSON, например двойников устройств. Предложение FROM указывает, что коллекция документов будет итерирована на (устройствах, устройствах, модулях или 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 записей. Чтобы получить несколько страниц, вызовите 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 |
| Сравнение | =, !=, <, ><=, =, =, ><> |
Функции
В запросах двойников и заданий поддерживается только одна функция.
| Function | Description |
|---|---|
| IS_DEFINED(Свойство) | Возвращает логическое значение, указывающее, назначено ли свойству значение (в том числе значение null). |
В условиях маршрута поддерживаются следующие математические функции.
| Function | Description |
|---|---|
| ABS(x) | Возвращает модуль (положительное значение) указанного числового выражения. |
| EXP(x) | Возвращает значение экспоненты для указанного числового выражения (e^x). |
| POWER(x,y) | Возвращает результат возведения указанного числового выражения в заданную степень (x^y). |
| SQUARE(x) | Возвращает квадратный корень из указанного числового значения. |
| CEILING(x) | Возвращает наименьшее целочисленное значение, которое больше или равно указанному числовому выражению. |
| FLOOR(x) | Возвращает наибольшее целое число, меньшее или равное указанному числовому выражению. |
| SIGN(x) | Возвращает знак указанного числового выражения (+1 для положительных чисел, 0 для нуля или -1 для отрицательных). |
| SQRT(x) | Возвращает квадратный корень из указанного числового значения. |
В условиях маршрута поддерживаются следующие функции проверки и приведения типов.
| Function | Description |
|---|---|
| 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 | Возвращает логическое значение, указывающее, является ли указанное выражение строковым значением. |
В условиях маршрутов поддерживаются следующие строковые функции.
| Function | Description |
|---|---|
| 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 несколько раз.
Следующие шаги
- Сведения о маршрутизации сообщений на основе свойств сообщения или текста сообщения с помощью синтаксиса запроса маршрутизации сообщений Центр Интернета вещей.
- Получите конкретные примеры запросов для двойников устройств и модулей или запросов для заданий.
Кері байланыс
Жақында қолжетімді болады: 2024 жыл бойы біз GitHub Issues жүйесін мазмұнға арналған кері байланыс механизмі ретінде біртіндеп қолданыстан шығарамыз және оны жаңа кері байланыс жүйесімен ауыстырамыз. Қосымша ақпаратты мұнда қараңыз: https://aka.ms/ContentUserFeedback.
Жіберу және пікірді көру