设备孪生(device twins)是存储设备状态信息(包括元数据,配置和条件)的 JSON 文档。 Azure IoT Hub 为连接到 IoT Hub 的每个设备维护一个设备对。 本文以下内容介绍:
使用设备孪生是为了:
有关使用报告的属性,设备到云消息或文件上载的指导,请参阅设备到云通信指南。有关使用所需的属性,直接方法或云到设备消息的指导,请参阅云端到设备的通信指南。
设备孪生存储设备相关的信息:
设备孪生的生命周期链接到相应的设备身份。在物联网集线器中创建或删除设备标识时,会隐式创建和删除设备孪生。
设备孪生是一个 JSON 文件,其中包括:
以下示例显示了一个设备孪生 JSON 文档:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"$etag": "123",
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
}
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
在根对象中是设备标识属性,用于 tags
的容器对象以及 reported
和 desired
属性。properties
容器包含设备孪生元数据和乐观并发(Optimistic concurrency) 部分中描述的一些只读元素( $metadata
,$etag
和 $version
)。
在前面的示例中,设备对包含由设备应用程序报告的 batteryLevel
属性。 此属性可以根据上次报告的电池电量查询和操作设备。 其他示例包括设备应用报告设备功能或连接选项。
> 注意
: 报告(Reported)的属性简化了解决方案后端对属性的最后一个已知值感兴趣的场景。如果解决方案后端需要以时间戳事件序列(如时间序列)的形式处理设备遥测,请使用设备到云消息。
在前面的示例中,解决方案后端和设备应用程序使用 telemetryConfig
设备所需的和报告的属性,来同步此设备的遥测配置。 例如:
1.解决方案后端使用所需的配置值设置所需的期望(desired)。以下是具有 desired
属性集的文档部分:
...
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
...
},
...
2.如果连接,或者在第一次重新连接,设备应用程序会立即通知更改。设备应用程序然后报告更新的配置(或使用 status 属性的错误条件)。以下是报告属性的一部分:
...
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
}
...
}
...
3.解决方案后端可以通过查询设备孪生,来跟踪跨许多设备的配置操作的结果。
> 注意:上面的代码片段是为了可读性而优化的一个例子,它是对设备配置及其状态进行编码的一种方式。物联网中心不强制设备孪生期望(desired)和报告(reported)的设备孪生的特定模式。
您可以使用孪生来同步长时间运行的操作,例如固件更新。有关如何使用属性来同步和跟踪跨设备的长时间运行操作的更多信息,请参阅Use desired properties to configure devices
解决方案后端使用以下原子操作在设备对上运行,通过 HTTPS 暴露:
null
的属性被删除。下面的示例创建一个新值为 {"newProperty":"newValue"}
的所需属性,用 otherNewValue
覆盖 existingProperty
的现有值,并删除 otherOldProperty
。现有的所需(desired)属性或标签(tags)没有其他更改:{
"properties": {
"desired": {
"newProperty": {
"nestedProperty": "newValue"
},
"existingProperty": "otherNewValue",
"otherOldProperty": null
}
}
}
properties/desired
。tags
。接收孪生通知。此操作允许解决方案后端在双胞胎被修改时得到通知。为此,您的物联网解决方案需要创建一个路由,并将数据源设置为 twinChangeEvents
。默认情况下,不发送双机通知,即不存在这样的路由。如果更改率过高,或由于其他原因(如内部故障),IoT Hub 可能只发送一个包含所有更改的通知。因此,如果您的应用程序需要可靠的审计和记录所有中间状态,那么仍然建议您使用 D2C 消息。孪生通知消息包括属性和正文。
Name | Value |
---|---|
$content-type | application/json |
$iothub-enqueuedtime | Time when the notification was sent |
$iothub-message-source | twinChangeEvents |
$content-encoding | utf-8 |
deviceId | ID of the device |
hubName | Name of IoT Hub |
operationTimestamp | ISO8601 timestamp of operation |
iothub-message-schema | deviceLifecycleNotification |
opType | "replaceTwin" or "updateTwin" |
消息系统属性以 $
符号为前缀。
- Body
本部分包含 JSON 格式的所有更改。 它使用与修补程序相同的格式,区别在于它可以包含所有的两个部分:tags、properties.reported、properties.desired,并且包含 ``$metadata`` 元素。例如:
{
"properties": {
"desired": {
"$metadata": {
"$lastUpdated": "2016-02-30T16:24:48.789Z"
},
"$version": 1
},
"reported": {
"$metadata": {
"$lastUpdated": "2016-02-30T16:24:48.789Z"
},
"$version": 1
}
}
}
以上所有操作均支持开放式并发,并需要安全性文章中定义的 ServiceConnect
权限。
除了这些操作之外,解决方案后端还可以:
设备应用程序使用以下原子操作在设备上运行:
所有上述操作都需要安全性文章中定义的 DeviceConnect
权限。
Azure IoT 设备 SDK 可以轻松地使用来自多种语言和平台的上述操作。有关所需属性同步的 IoT Hub 基元详细信息,请参阅设备重新连接流程。
标签,期望的属性和报告的属性是具有以下限制的 JSON 对象:
.
,
和 $
。{
...
"tags": {
"one": {
"two": {
"three": {
"four": {
"five": {
"property": "value"
}
}
}
}
}
},
...
}
IoT Hub 对标签,属性/期望以及属性/报告的每个相应总值进行 8KB 大小限制,排除只读元素。通过计算所有字符计算大小,不包括 UNICODE 控制字符(段 C0 和 C1)以及字符串常量之外的空格。 IoT Hub 会拒绝所有将超出限制的文档大小的操作。
IoT Hub 维护设备孪生所需和报告属性中每个 JSON 对象的上次更新的时间戳。时间戳以 UTC 格式编码,并以 ISO8601 格式 YYYY-MM-DDTHH:MM:SS.mmmZ
编码。 例如:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
}
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
}
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
这些信息保存在每个级别(不仅仅是JSON结构的叶子),以保留删除对象键的更新
标签,期望和报告的属性都支持 Optimistic 并发。标签有一个ETag,根据 RFC7232,代表标签的 JSON 表示。 您可以在解决方案后端的条件更新操作中使用 ETags 以确保一致性。
设备孪生想要和报告的属性没有 ETags,但有一个 $version
的值,保证是增量。与 ETag 类似,更新方可以使用该版本来强化更新的一致性。例如,报告的属性的设备应用程序或期望的属性的解决方案后端。
当观察代理(例如观察所需属性的设备应用)必须协调检索操作的结果与更新通知之间的竞争时,版本也是有用的。设备重新连接流程部分提供了更多信息。
IoT Hub 不保留断开设备的所需属性更新通知。 因此,除了订阅更新通知之外,连接的设备还必须检索完整的所需属性文档。 鉴于更新通知和完全检索之间的比赛的可能性,必须确保以下流程:
设备应用程序可以忽略 $version
小于或等于完整检索文档版本的所有通知。这种方法是可能的,因为 IoT Hub 保证版本总是增加。
> 注意:这个逻辑已经在 Azure IoT device SDK 中实现了。此说明仅在设备应用程序无法使用任何 Azure IoT device SDK,并且必须直接编程 MQTT 接口时才有用。
现在您已经了解了设备双胞胎,您可能对以下 IoT Hub 开发者指南主题感兴趣:
如果您想尝试本文中介绍的一些概念,您可能会对以下 IoT Hub 教程感兴趣:
英语原文链接:https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins
观光\评论区