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

IoT 中心设备孪生和模块孪生的查询

项目
03/18/2023

设备孪生和模块孪生可以包含标记和属性形式的任意 JSON 对象。通过 IoT 中心，可将设备孪生和模块孪生作为包含所有孪生信息的单个 JSON 文档进行查询。

下面是一个示例 IoT 中心设备孪生（模块孪生与此类似，但使用的参数为 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
        }
    }
}

设备孪生查询

IoT 中心将设备孪生公开为名为设备的文档集合。例如，最基本的查询将检索设备孪生的整个集：

SELECT * FROM devices

注意

Azure IoT SDK 支持将大型结果分页。

可以使用 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（非 IN）运算符结合使用。例如，以下查询检索报告 WiFi 或有线连接的设备孪生：

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

通常需要标识包含特定属性的所有设备孪生。为此，IoT 中心支持函数 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"
    }
]

在此示例中，三个设备报告了成功配置，两个仍在应用配置，一个报告了错误。

投影查询允许开发人员仅返回他们所关注的属性。例如，若要检索上次活动时间以及已断开连接的所有已启用设备的设备 ID，请使用以下查询：

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

该查询的结果将如以下示例所示：

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

模块孪生查询

对模块孪生进行查询类似于对设备孪生进行查询，但使用不同的集合/命名空间，即不从设备进行查询，而是从 devices.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 分钟的延迟。在大多数情况下，孪生查询将在几秒钟内返回结果。 IoT 中心致力于降低所有操作的延迟。但是，由于网络条件和其他不可预测因素，它不能保证特定的延迟。

孪生查询的另一种选项是使用 get twin REST API 按 ID 查询单个设备孪生。此 API 始终返回最新值，并具有更高的节流限制。可以直接发出 REST API 或使用 Azure IoT 中心服务 SDK 之一中的等效功能。

查询表达式的最大长度可以为 8192 个字符。

目前，仅支持在基元类型（无对象）之间进行比较，例如，仅在这些属性具有基元值时才支持 ... WHERE properties.desired.config = properties.reported.config。

在任何情况下，建议都不要依赖在孪生查询的设备标识属性中找到的 lastActivityTime。此字段不保证准确度量设备状态。请改用 IoT 设备生命周期事件来管理设备状态和活动。有关如何在你的解决方案中使用 IoT 中心生命周期事件的详细信息，请访问通过使用事件网格触发操作来响应 IoT 中心事件。

注意

避免对此操作的最大延迟进行假定。有关如何在考虑延迟的情况下构建解决方案的详细信息，请参阅延迟解决方案。

后续步骤

了解 IoT 中心查询语言的基础知识

通过

IoT 中心设备孪生和模块孪生的查询

设备孪生查询

模块孪生查询

孪生查询限制

后续步骤

反馈

其他资源