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

  • Статья

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

Примечание

Пакеты SDK для Azure IoT поддерживают разбивку на страницы объемных результатов.

Вы можете агрегировать результаты запроса с помощью предложения SELECT. Например, следующий запрос возвращает число устройств в центре Интернета вещей:

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 (не in). Например, следующий запрос извлекает двойники устройств, которые сообщают о 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 вы можете делать запросы из device.modules:

SELECT * FROM devices.modules

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

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

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

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

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

Важно!

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

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

Длина выражения запроса не должна превышать 8192 символа.

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

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

Примечание

Старайтесь не делать никаких предположений о максимальной задержке этой операции. Дополнительные сведения о создании решения с учетом задержки см. в статье Решения по задержкам .

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