Использование REST API IoT Central для запроса устройств

Статья
04/11/2024

REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. REST API можно использовать для запроса устройств в приложении IoT Central. Ниже приведены примеры использования REST API запроса:

Получение последних 10 значений телеметрии, сообщаемых устройством.
Найдите все устройства, которые находятся в состоянии ошибки и имеют устаревшее встроенное ПО.
Тенденции телеметрии с устройств, в среднем за 10 минут.
Получите текущую версию встроенного ПО всех устройств термостата.

В этой статье описывается, как использовать /query API для запроса устройств.

Устройство может объединять поддерживаемые свойства, данные телеметрии и команды в компоненты и модули.

Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.

Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.

Совет

С помощью Postman можно попробовать вызовы REST API, описанные в этой статье. Скачайте коллекцию Postman IoT Central и импортируйте ее в Postman. В коллекции необходимо задать переменные, такие как поддомен приложения и маркер администратора.

Сведения о том, как запрашивать устройства с помощью пользовательского интерфейса IoT Central, см. в статье "Как использовать обозреватель данных для анализа данных устройства".

Выполнение запроса

Используйте следующий запрос для выполнения запроса:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

Запрос находится в тексте запроса и выглядит следующим образом:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Значение dtmi:eclipsethreadx:devkit:hlby5jgib2o в предложении FROM — это идентификатор шаблона устройства. Чтобы найти идентификатор шаблона устройства, перейдите на страницу "Устройства" в приложении IoT Central и наведите указатель мыши на устройство, использующее шаблон. Карта включает идентификатор шаблона устройства:

Снимок экрана: поиск идентификатора шаблона устройства в URL-адресе страницы.

Ответ включает данные телеметрии с нескольких устройств, использующих один и тот же шаблон устройства. Ответ на этот запрос выглядит так, как показано в следующем примере.

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Синтаксис

Синтаксис запроса аналогичен синтаксису SQL и состоит из следующих предложений:

SELECT требуется и определяет данные, которые требуется получить, например значения телеметрии устройства.
FROM является обязательным и определяет тип устройства, который вы запрашиваете. Это предложение указывает идентификатор шаблона устройства.
WHERE необязательный и позволяет фильтровать результаты.
ORDER BY необязательный и позволяет сортировать результаты.
GROUP BY является необязательным и позволяет агрегировать результаты.

В следующих разделах более подробно описаны эти предложения.

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

Предложение SELECT содержит значения данных для включения в выходные данные запроса и может включать следующие элементы:

Телеметрия. Используйте имена телеметрии из шаблона устройства.
$id. идентификатор устройства;
$provisioned. Логическое значение, показывающее, подготовлено ли устройство.
$simulated. Логическое значение, показывающее, является ли устройство имитируемым.
$ts. Метка времени, связанная со значением телеметрии.

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

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Имя компонента можно найти в шаблоне устройства:

Следующие ограничения применяются в предложении SELECT :

Нет дикого оператора карта.
В списке выбора не может быть более 15 элементов.
Запрос возвращает не более 10 000 записей.

Aliases

AS Используйте ключевое слово для определения псевдонима элемента в предложенииSELECT. Псевдоним используется в выходных данных запроса. Его также можно использовать в другом месте запроса. Например:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Совет

Вы не можете использовать другой элемент в списке выбора в качестве псевдонима. Например, не допускается SELECT id, temp AS id...следующее.

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

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

TOP Используйте для ограничения количества результатов, возвращаемых запросом. Например, следующий запрос возвращает первые 10 результатов:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Если вы не используете TOP, запрос возвращает не более 10 000 результатов.

Чтобы отсортировать результаты до TOP ограничения количества результатов, используйте ORDER BY.

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

Предложение FROM должно содержать идентификатор шаблона устройства. Предложение FROM указывает тип запрашиваемого устройства.

Чтобы найти идентификатор шаблона устройства, перейдите на страницу "Устройства" в приложении IoT Central и наведите указатель мыши на устройство, использующее шаблон. Карта включает идентификатор шаблона устройства:

Для получения идентификатора шаблона устройства для устройства можно также использовать вызов REST API.

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

Предложение WHERE позволяет использовать значения и интервалы времени для фильтрации результатов:

Окна времени

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

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Значение периода времени использует формат длительности ISO 8601. В следующей таблице приведены некоторые примеры:

Пример	Description
PT10M	Последние 10 минут
P1D	Прошлый день
P2DT12H	Последние 2 дня и 12 часов
P1W	Последняя неделя
PT5H	Последние пять часов
'2021-06-13T13:00Z/2021-06-13T15:30:00Z'	Определенный диапазон времени

Сравнения значений

Данные телеметрии можно получить на основе определенных значений. Например, следующий запрос возвращает все сообщения, в которых температура превышает нулю, давление превышает 50, а идентификатор устройства — один из примеров 002 и sample-003:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

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

Логические операторы AND и OR.
Операторы =сравнения, !=, <<=<>>>=и .IN

Примечание.

Оператор IN работает только с телеметрией и $id.

Следующие ограничения применяются в предложении WHERE :

В одном запросе можно использовать не более 10 операторов.
В запросе WHERE предложение может содержать только фильтры телеметрии и метаданных устройства.
В запросе можно получить до 10 000 записей.

Агрегаты и предложение GROUP BY

Функции агрегирования позволяют вычислять такие значения, как среднее, максимальное и минимальное значение данных телеметрии в течение периода времени. Например, следующий запрос вычисляет среднюю температуру и влажность с устройства sample-001 в 10-минутных окнах:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

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

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

Поддерживаются следующие функции агрегирования: , , , , , FIRSTAVGи LAST. COUNTMINMAXSUM

Используется GROUP BY WINDOW для указания размера окна. Если вы не используете GROUP BY WINDOW, запрос агрегирует данные телеметрии за последние 30 дней.

Примечание.

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

Предложение ORDER BY

Предложение ORDER BY позволяет сортировать результаты запроса по значению телеметрии, метке времени или идентификатору устройства. Вы можете сортировать по возрастанию или убыванию. Например, следующий запрос сначала возвращает последние результаты:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Совет

Объединение ORDER BY с TOP ограничением количества результатов, возвращаемых запросом после сортировки.

Ограничения

Текущие ограничения для запросов:

В списке SELECT предложений не более 15 элементов.
В предложении не более 10 логических операций WHERE .
Максимальная длина строки запроса составляет 350 символов.
Вы не можете использовать дикую карта (*) в списке SELECT предложений.
Запросы могут извлекать до 10 000 записей.

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

Теперь, когда вы узнали, как запрашивать устройства с помощью REST API, рекомендуется узнать , как использовать REST API IoT Central для управления пользователями и ролями.

Поделиться через

Использование REST API IoT Central для запроса устройств

Выполнение запроса

Синтаксис

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

Aliases

TOP

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

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

Окна времени

Сравнения значений

Агрегаты и предложение GROUP BY

Предложение ORDER BY

Ограничения

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

Дополнительные ресурсы