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

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

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

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

Выполнение запросов Центр Интернета вещей

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

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

Вы также можете выполнять запросы в приложениях с помощью пакетов 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 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 для служб 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 несколько раз.

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

• Сведения о маршрутизации сообщений на основе свойств сообщения или текста сообщения с помощью синтаксиса запроса маршрутизации сообщений Центр Интернета вещей.
• Получите конкретные примеры запросов для двойников устройств и модулей или запросов для заданий.