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

Query - Get Twins

服务:

IoT Hub

API 版本:

2021-04-12

查询IoT 中心，以使用类似于 SQL 的语言检索有关设备孪生的信息。 有关详细信息，请参阅https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language。 支持分页。 这仅返回有关设备孪生的信息。

POST https://fully-qualified-iothubname.azure-devices.net/devices/query?api-version=2021-04-12

URI 参数

名称	在	必需	类型	说明
api-version	query	True	string	Api 的版本。

请求头

名称	必需	类型	说明
x-ms-continuation		string	用于获取下一页结果的继续标记。
x-ms-max-item-count		string	每页返回的最大项数。 如果指定的值不可接受，则服务可能会使用不同的值。

请求正文

名称	类型	说明
query	string	查询字符串。

响应

名称	类型	说明
200 OK	Twin[]	没问题。 标头 x-ms-item-type: string x-ms-continuation: string

定义

名称	说明
DeviceCapabilities	设备上启用的功能的状态。
QuerySpecification	Json 查询请求。
Twin	设备或模块的状态信息。 在IoT 中心中创建或删除相应的设备/模块标识时，会隐式创建和删除此标识。
TwinProperties	孪生体的所需属性和报告属性。 对象的最大深度为 10。
X509Thumbprint

DeviceCapabilities

设备上启用的功能的状态。

名称	类型	说明
iotEdge	boolean	确定设备是否为边缘设备的属性。

QuerySpecification

Json 查询请求。

名称	类型	说明
query	string	查询字符串。

Twin

设备或模块的状态信息。 在IoT 中心中创建或删除相应的设备/模块标识时，会隐式创建和删除此标识。

名称	类型	说明
authenticationType	enum: certificateAuthority none sas selfSigned	设备使用的身份验证类型。
capabilities	DeviceCapabilities	设备上启用的功能的状态。
cloudToDeviceMessageCount	integer	发送的云到设备的消息数。
connectionState	enum: Connected Disconnected	设备的连接状态。
deviceEtag	string	表示设备的 ETag 的字符串，根据 RFC7232。
deviceId	string	IoT 中心标识注册表中设备的唯一标识符。 它是一个区分大小写的字符串， (最多 128 个字符长) ASCII 7 位字母数字字符， 以及以下特殊字符 {'-'， '：'， '.'， '+'， '%'， '_'， '#'， '*'， '？'， '！'， ' ('， ') '， '，'， '='， '@'， ';'， '$'， '''}。
deviceScope	string	设备的范围。
etag	string	表示设备孪生的 ETag 的字符串，根据 RFC7232。
lastActivityTime	string	设备上次连接、接收或发送消息的日期和时间。 日期和时间以 UTC 格式ISO8601日期/时间格式分隔，例如 2015-01-28T16：24：48.789Z。 如果设备使用 HTTP/1 协议执行消息传送操作，则不会更新此值。
moduleId	string	IoT 中心标识注册表中模块的唯一标识符。 它是一个区分大小写的字符串， (最多 128 个字符长) ASCII 7 位字母数字字符， 以及以下特殊字符 {'-'， '：'， '.'， '+'， '%'， '_'， '#'， '*'， '？'， '！'， ' ('， ') '， '，'， '='， '@'， ';'， '$'， '''}。
parentScopes	string[]	上层边缘设备的范围（如果适用）。 仅适用于边缘设备。
properties	TwinProperties	孪生体的所需属性和报告属性。
status	enum: disabled enabled	设备的启用状态。 如果禁用，设备将无法连接到服务。
statusReason	string	设备当前状态的原因（如果有）。
statusUpdateTime	string	上次更新设备状态的日期和时间。
tags	object	由解决方案后端读取和写入的键值对的集合。 它们对设备应用不可见。 它们的密钥是 UTF-8 编码的，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 值为 JSON 对象，长度最大为 4KB。
version	integer	设备孪生的版本，包括标记和所需属性
x509Thumbprint	X509Thumbprint	设备的 X509 指纹。

TwinProperties

孪生体的所需属性和报告属性。 对象的最大深度为 10。

名称	类型	说明
desired	object	所需属性键值对的集合。 密钥采用 UTF-8 编码，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 所需的 porperty 值为 JSON 对象，长度最大为 4KB。
reported	object	报告的属性键值对的集合。 密钥采用 UTF-8 编码，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 报告的属性值是 JSON 对象，长度最大为 4KB。

X509Thumbprint

名称	类型	说明
primaryThumbprint	string	X509 客户端证书主指纹。
secondaryThumbprint	string	X509 客户端证书辅助指纹。