Язык запросов для центра управления Интернетом вещей с двойниками устройств и модулей, заданиями и маршрутизацией сообщений

Центр Интернета вещей предоставляет эффективный язык, похожий на SQL, для получения сведений о двойниках устройств, двойниках модулей и заданиях и маршрутизации сообщений. В этой статье представлены:

• общие сведения об основных возможностях языка запросов Центра Интернета вещей;
• подробное описание языка. Дополнительные сведения о языке запросов для маршрутизации сообщений см. в синтаксисе запросов маршрутизации сообщений Центра Интернета вещей.

Конкретные примеры см. в разделе "Запросы для устройств и двойников модулей Центра Интернета вещей" или"Запросы" для заданий Центра Интернета вещей.

Запускать запросы в Центре Интернета вещей

Запросы к центру Интернета вещей можно выполнять непосредственно в портал Azure.

1. Войдите на портал Azure и перейдите к своему Центру Интернета вещей.
2. Выберите запросы в разделе управления устройствами в меню навигации.
3. Введите запрос в текстовое поле и нажмите кнопку "Выполнить запрос".

Вы также можете выполнять запросы в приложениях с помощью пакетов SDK службы Интернета вещей Azure и API-интерфейсов служб.

Примеры кода, реализующие запросы в IoT Hub, см. в разделе Примеры запросов с использованием SDK служб.

Ссылки на справочные страницы SDK и примеры см. в разделе SDK для Azure IoT Hub.

Основные сведения о запросе Центра Интернета вещей

Каждый запрос Центра Интернета вещей состоит из предложений SELECT и FROM, а также необязательных предложений WHERE и GROUP BY.

Запросы выполняются в коллекции документов JSON, таких как цифровые двойники устройств. Предложение FROM указывает на коллекцию документов, такую как устройства, устройства.модули, или устройства.задания, которые следует итерировать.

Затем применяется фильтр в предложении WHERE. С использованием агрегации результаты этого шага сгруппированы, как указано в предложении GROUP BY. Для каждой группы создается строка, как указано в предложении SELECT.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

Предложение SELECT

Необходима конструкция SELECT <select_list> в каждом запросе IoT-хаб. Он указывает, какие значения извлекаются из запроса. Здесь задаются значения 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> требуется в каждом запросе IoT Hub. Это должно быть одно из трех значений:

• устройства для запроса двойников устройств
• 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 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>]+ ']'

Чтобы понять, что означает каждый символ в синтаксисе выражений, ознакомьтесь со следующей таблицей:

Операторы

Поддерживаются следующие операторы:

Функции

В запросах двойников и заданий поддерживается только одна функция.

В условиях маршрута поддерживаются следующие математические функции.

В условиях маршрутов поддерживаются следующие функции проверки и приведения типов.

В условиях маршрутов поддерживаются следующие строковые функции.

Примеры запросов с SDK службы

Пример C#

Функции запроса предоставляются пакетом SDK службы Центра Интернета вещей Azure для .NET в классе 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 для Node.js в объекте Реестра .

Ниже приведен пример простого запроса:

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 несколько раз.

Следующие шаги

• Узнайте о маршрутизации сообщений на основе свойств сообщения или содержания сообщения с использованием синтаксиса запросов Центра Интернета вещей (IoT Hub).
• Получите конкретные примеры запросов для двойников устройств и модулей Центра Интернета вещей или запросов для заданий Центра Интернета вещей.