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

Двойники устройств и двойники модулей могут содержать произвольные объекты 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
        }
    }
}

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

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

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.

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

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.

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

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

Рекомендуется не полагаться на lastActivityTime, найденное в свойствах удостоверения устройства для запросов двойников, в любом сценарии. Это поле не гарантирует точную оценку состояния устройства. Вместо этого используйте события жизненного цикла устройств Интернета вещей для управления состоянием устройства и действиями. Дополнительные сведения об использовании событий жизненного цикла Центра Интернета вещей в решении см. в разделе React to IoT Hub events by using Event Grid to trigger actions.

Дальнейшие действия

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