你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 IoT Central REST API 查询设备

项目
08/09/2024

通过 IoT Central REST API，你可以开发与 IoT Central 应用程序集成的客户端应用程序。可以使用 REST API 查询 IoT Central 应用程序中的设备。以下示例演示如何使用查询 REST API：

获取设备报告的最后 10 个遥测值。
查找所有状态为错误且固件已过时的设备。
来自设备的遥测趋势，以 10 分钟时段为平均值。
获取所有恒温器设备的当前固件版本。

本文介绍如何使用 /query API 查询设备。

设备可以将其支持的属性、遥测数据和命令按组件和模块进行分组。

每个 IoT Central REST API 调用都需要授权标头。有关详细信息，请参阅如何对 IoT Central REST API 调用进行身份验证和授权。

有关 IoT Central REST API 的参考文档，请参阅 Azure IoT Central REST API 参考。

若要了解如何使用 IoT Central UI 来查询设备，请参阅如何使用数据资源管理器分析设备数据。

运行查询

使用以下请求运行查询：

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)"
}

FROM 子句中的 dtmi:eclipsethreadx:devkit:hlby5jgib2o 值为设备模板 ID。若要查找设备模板 ID，请导航到 IoT Central 应用程序中的“设备”页，并将鼠标悬停在使用该模板的设备上。此卡包括设备模板 ID：

显示如何在页面 URL 中查找设备模板 ID 的屏幕截图。

响应包括来自共享相同设备模板的多个设备的遥测数据。对此请求的响应如以下示例所示：

{
  "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 是必需的，它标识要查询的设备类型。此子句指定设备模板 ID。
WHERE 是可选的，它用于筛选结果。
ORDER BY 是可选的，它用于对结果进行排序。
GROUP BY 是可选的，它用于聚合结果。

下面各部分详细说明了这些子句。

SELECT 子句

SELECT 子句列出要包括在查询输出中的数据值，并且可以包含以下项：

遥测。使用设备模板中的遥测名称。
$id。设备 ID。
$provisioned。一个布尔值，它指示设备是否已预配。
$simulated。一个布尔值，它指示设备是否为模拟设备。
$ts。与遥测值关联的时间戳。

如果设备模板使用组件，则引用组件中定义的遥测，如下所示：

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

可以在设备模板中找到组件名称：

以下限制适用于 SELECT 子句：

没有通配符运算符。
选择列表中的项不能超过 15 个。
查询最多返回 10,000 条记录。

别名

使用 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 子句必须包含设备模板 ID。 FROM 子句指定要查询的设备的类型。

若要查找设备模板 ID，请导航到 IoT Central 应用程序中的“设备”页，并将鼠标悬停在使用该模板的设备上。此卡包括设备模板 ID：

还可使用 Devices - Get REST API 调用获取设备的设备模板 ID。

WHERE 子句

WHERE 子句允许使用值和时间范围来筛选结果：

时间范围

若要获取应用程序在指定的时间范围内收到的遥测数据，请使用 WITHIN_WINDOW 作为 WHERE 子句的一部分。例如，若要检索过去一天的温度和湿度遥测数据，请使用以下查询：

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

时间范围值使用 ISO 8601 持续时间格式。下表包含了一些示例：

示例	说明
PT10M	过去 10 分钟
P1D	前一天
P2DT12H	过去 2 天 12 小时
P1W	上周
PT5H	过去 5 小时
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z'	特定时间范围

值的比较

可以基于特定值获取遥测。例如，以下查询返回温度大于零、压力大于 50 且设备 ID 为 sample-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 子句

使用聚合函数，可以计算时间范围内遥测数据的平均值、最大值和最小值等值。例如，以下查询计算 10 分钟内设备 sample-001 的平均温度和湿度：

{
  "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
        }
    ]
}

支持以下聚合函数：SUM、MAX、MIN、COUNT、AVG、FIRST 和 LAST。

使用 GROUP BY WINDOW 指定时间范围大小。如果不使用 GROUP BY WINDOW，查询将聚合过去 30 天的遥测数据。

注意

只能聚合遥测值。

ORDER BY 子句

ORDER BY 子句支持按遥测值、时间戳或设备 ID 对查询结果进行排序。可以按升序或降序顺序排序。例如，以下查询首先返回最新结果：

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

提示

将 ORDER BY 和 TOP 结合使用来限制排序后查询返回的结果数。

限制

查询的当前限制是：

SELECT 子句列表中的项不超过 15 个。
WHERE 子句中的逻辑操作不超过 10 个。
查询字符串的最大长度为 350 个字符。
不能在 SELECT 子句列表中使用通配符 (*)。
查询最多可以检索 10,000 条记录。

后续步骤

现在你已了解如何使用 REST API 查询设备，建议接下来了解如何使用 IoT Central REST API 管理用户和角色。

通过