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

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

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

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

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

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

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

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

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

Ссылки на справочные страницы и примеры SDK см. в разделе Центр Интернета вещей Azure SDKs.

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

Каждый запрос Центра Интернета вещей состоит из предложений 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> требуется для каждого запроса Центр Интернета вещей. Он указывает, какие значения извлекаются из запроса. Здесь задаются значения 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

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

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

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

Ниже приведен пример двойника устройства узла Интернета вещей (двойник модуля будет аналогичным, но с параметром moduleId):

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "Disconnected",
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "US",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

Запросы двойника устройства

Центр Интернета вещей предоставляет цифровые двойники устройств в виде коллекции документов под названием devices. Например, самый простой запрос извлекает весь набор двойников устройств:

SELECT * FROM devices

Результаты запроса можно агрегировать с помощью предложения SELECT. Например, следующий запрос вычисляет количество всех устройств в узле IoT.

SELECT COUNT() as totalNumberOfDevices FROM devices

Фильтрация результатов запроса с помощью предложения WHERE. Например, чтобы получить двойники устройств, в которых для тега location.region задано значение US, используйте следующий запрос:

SELECT * FROM devices
WHERE tags.location.region = 'US'

Создание сложных предложений WHERE с помощью логических операторов и арифметических сравнений. Например, следующий запрос извлекает двойники устройств, расположенные в США и настроенные для отправки телеметрии меньше, чем каждую минуту:

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

Можно также использовать константы массива с операторами IN и NIN (не в). Например, следующий запрос извлекает цифровые двойники устройств, которые сообщают о Wi-Fi или проводном подключении.

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

Часто необходимо определить все двойники устройств, содержащие определенное свойство. Центр Интернета вещей поддерживает функцию is_defined() для этой цели. Например, следующий запрос извлекает двойники устройств, определяющие connectivity свойство:

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

Подробная информация о возможностях фильтрации представлена в разделе WHERE clause.

Группирование также поддерживается. Например, следующий запрос возвращает количество устройств в каждом состоянии конфигурации телеметрии:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

Этот запрос группирования возвращает результат, аналогичный следующему примеру:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

В этом примере три устройства сообщили об успешной настройке, два по-прежнему применяют конфигурацию, и одна сообщила об ошибке.

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

SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'

Результат этого запроса будет выглядеть следующим образом:

[
  {
    "deviceId": "AZ3166Device",
    "lastActivityTime": "2021-05-07T00:50:38.0543092Z"
  }
]

Запросы двойника модуля

Запросы к двойникам модулей похожи на запросы к двойникам устройств, но осуществляются с использованием другого пространства имен/коллекции; вместо devices вы запрашиваете из devices.modules:

SELECT * FROM devices.modules

Мы не разрешаем присоединение между устройствами и коллекциями device.modules. Если вы хотите запросить двойники модулей на разных устройствах, это можно сделать на основе тегов. Следующий запрос возвращает все двойники модулей на всех устройствах с состоянием сканирования:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

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

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

Ограничения для запросов двойников

Альтернативным вариантом запросов двойников является запрос отдельных двойников устройств по идентификатору с помощью REST API получения двойника. Этот API всегда возвращает последние значения и имеет более высокие ограничения регулирования. Вы можете напрямую выдавать REST API или использовать эквивалентную функциональность в одном из пакетов SDK службы Центр Интернета вещей Azure Service SDK.

Выражения запросов могут иметь максимальную длину 8 192 символов.

В настоящее время сравнения поддерживаются только между примитивными типами (без объектов). Например, ... WHERE properties.desired.config = properties.reported.config поддерживается только в случае, если эти свойства имеют примитивные значения.

Мы рекомендуем не полагаться на lastActivityTime, найденное в свойствах удостоверения устройства для запросов двойников в любом сценарии. Это поле не гарантирует точное измерение состояния устройства. Вместо этого используйте события жизненного цикла устройств Интернета вещей для управления состоянием и действиями устройства. Сведения об использовании событий жизненного цикла Центр Интернета вещей в решении см. в разделе реагировать на события Центр Интернета вещей с помощью Event Grid для активации действий.

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

Задания предоставляют способ выполнения операций на наборах устройств. Каждый двойник устройства содержит сведения о заданиях, предназначенных для него в коллекции, называемой заданиями. Центр Интернета вещей позволяет запрашивать задания, получая их в виде единого документа JSON, содержащего все сведения о цифровых двойниках.

Ниже приведен пример двойника устройства Центра Интернета вещей, который является частью задания myJobId:

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        ...
    },
    "properties": {
        ...
    },
    "jobs": [
        {
            "deviceId": "myDeviceId",
            "jobId": "myJobId",
            "jobType": "scheduleUpdateTwin",
            "status": "completed",
            "startTimeUtc": "2016-09-29T18:18:52.7418462",
            "endTimeUtc": "2016-09-29T18:20:52.7418462",
            "createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
            "lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
            "outcome": {
                "deviceMethodResponse": null
            }
        },
        ...
    ]
}

В настоящее время эта коллекция запрашивается как devices.jobs на языке запросов Центр Интернета вещей.

Например, следующий запрос возвращает все задания (прошлые и запланированные), которые влияют на одно устройство:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Обратите внимание, что этот запрос предоставляет состояние конкретного устройства (и, возможно, прямой ответ метода) каждого возвращаемого задания.

В коллекции devices.jobs также возможно фильтровать по произвольным логическим условиям всех свойств объекта.

Например, следующий запрос извлекает все завершенные задания обновления двойника устройства, созданные после сентября 2016 года для конкретного устройства:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'
    AND devices.jobs.jobType = 'scheduleUpdateTwin'
    AND devices.jobs.status = 'completed'
    AND devices.jobs.createdTimeUtc > '2016-09-01'

Вы также можете получить результаты одного задания для каждого устройства.

SELECT * FROM devices.jobs
  WHERE devices.jobs.jobId = 'myJobId'

Ограничения запросов работы

Выражения запросов могут иметь максимальную длину 8 192 символов.

В настоящее время запросы на devices.jobs не поддерживают:

• Поэтому возможны только SELECT * проекции.
• Условия, ссылающиеся на двойник устройства в дополнение к свойствам задания (см. предыдущий раздел).
• Агрегаты, такие как количество, среднее и группирование по.

Связанный контент

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