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

设备孪生 和 模块孪生 可以包含任意 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

可以使用 SELECT 子句聚合查询的结果。 例如，以下查询获取 IoT 中心内设备总数的计数：

SELECT COUNT() as totalNumberOfDevices FROM devices

使用 WHERE 子句筛选查询结果。 例如，若要接收 location.region 标记设置为 美国 的设备孪生，请使用以下查询：

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 （不在）运算符中使用。 例如，以下查询检索报告 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.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 按 ID 查询单个设备孪生。 此 API 始终返回最新值，并具有更高的限制。 可以直接颁发 REST API，也可以在其中一个 Azure IoT 中心服务 SDK 中使用等效的功能。

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

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

对于任何方案，我们建议不要依赖于 lastActivityTime 在设备标识属性中找到的孪生查询。 此字段不能保证设备状态的准确仪表。 请改用 IoT 设备生命周期事件来管理设备状态和活动。 有关如何在解决方案中使用 IoT 中心生命周期事件的详细信息，请访问 使用事件网格触发作的 React to IoT 中心事件。

后续步骤

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