数字孪生：在 Azure IoT Hub 使用设备孪生（device twins）

Phodal Huang

phodal

一月 10, 2018

设备孪生（device twins）是存储设备状态信息（包括元数据，配置和条件）的 JSON 文档。 Azure IoT Hub 为连接到 IoT Hub 的每个设备维护一个设备对。本文以下内容介绍：

设备孪生的结构：标签（tags），期望（desired）和报告（reported）的属性。
在设备孪生上，应用程序和后端可以在设备上执行的操作。

使用设备孪生是为了：

将设备特定的元数据存储在云中。例如，自动售货机的部署位置。
从您的设备应用报告当前的状态信息，如可用的功能和条件。例如，设备通过蜂窝或 WiFi 连接到您的物联网集线器。
在设备应用程序和后端应用程序之间同步长时间运行的工作流的状态。例如，当解决方案回退可以以新的固件版本结束安装，并且设备应用程序报告更新过程的各个阶段。
查询您的设备元数据，配置或状态。

有关使用报告的属性，设备到云消息或文件上载的指导，请参阅设备到云通信指南。有关使用所需的属性，直接方法或云到设备消息的指导，请参阅云端到设备的通信指南。

设备孪生

设备孪生存储设备相关的信息：

设备和后端可用于同步设备条件和配置。
解决方案后端可用于查询和定位长时间运行的操作。

设备孪生的生命周期链接到相应的设备身份。在物联网集线器中创建或删除设备标识时，会隐式创建和删除设备孪生。

设备孪生是一个 JSON 文件，其中包括：

标签（Tags）。解决方案后端可以读取和写入的 JSON 文档的一部分。设备应用不可见标签。
所需的属性（Desired properties）。与报告的属性一起使用以同步设备配置或条件。解决方案后端可以设置所需的属性，设备应用程序可以读取它们。设备应用程序还可以接收所需属性更改的通知。
报告的属性（Reported properties.）。与所需的属性一起使用，以同步设备配置或条件。设备应用程序可以设置报告的属性，解决方案后端可以读取和查询它们。
设备标识属性（Device identity properties）。设备孪生 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）。

报告（Reported）属性示例

在前面的示例中，设备对包含由设备应用程序报告的 batteryLevel 属性。此属性可以根据上次报告的电池电量查询和操作设备。其他示例包括设备应用报告设备功能或连接选项。

> 注意: 报告（Reported）的属性简化了解决方案后端对属性的最后一个已知值感兴趣的场景。如果解决方案后端需要以时间戳事件序列（如时间序列）的形式处理设备遥测，请使用设备到云消息。

Desired 属性示例

在前面的示例中，解决方案后端和设备应用程序使用 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 暴露：

通过id检索设备孪生兄弟。此操作返回设备的双胞胎文档，包括标签和所需和报告的系统属性。
部分更新设备双胞胎。此操作使解决方案后端，能够部分更新设备对中的标签或所需的属性。部分更新表示为添加或更新任何属性的JSON文档。设置为 null 的属性被删除。下面的示例创建一个新值为 {"newProperty"："newValue"}的所需属性，用 otherNewValue 覆盖 existingProperty 的现有值，并删除 otherOldProperty。现有的所需（desired）属性或标签（tags）没有其他更改：

{
      "properties": {
          "desired": {
              "newProperty": {
                  "nestedProperty": "newValue"
              },
              "existingProperty": "otherNewValue",
              "otherOldProperty": null
          }
      }
  }

替换 desired 属性。此操作使解决方案后端能够完全覆盖所有现有的所需属性，并将新的 JSON 文档替换为 properties/desired。
替换 tags。通过此操作，解决方案后端可以完全覆盖所有现有标签，并将新的 JSON 文档替换为 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 权限。

除了这些操作之外，解决方案后端还可以：

使用类似 SQL 的 IoT Hub 查询语言查询设备孪生。
使用作业在大型设备孪生上执行操作。

设备操作

设备应用程序使用以下原子操作在设备上运行：

取回设备孪生。此操作将返回当前连接的设备的设备孪生文档（包括标签和所需和报告的系统属性）。
部分更新报告的属性。此操作可以部分更新当前连接设备的报告属性。此操作使用解决方案后端用于部分更新所需属性的相同 JSON 更新格式。
观察所需的属性。当前连接的设备可以选择在其发生时通知所需属性的更新。设备接收到解决方案后端执行的相同形式的更新（部分或全部替换）。

所有上述操作都需要安全性文章中定义的 DeviceConnect 权限。

Azure IoT 设备 SDK 可以轻松地使用来自多种语言和平台的上述操作。有关所需属性同步的 IoT Hub 基元详细信息，请参阅设备重新连接流程。

标签和属性格式

标签，期望的属性和报告的属性是具有以下限制的 JSON 对象：

JSON 对象中的所有密钥都是区分大小写的 64 个字节的 UTF-8 UNICODE 字符串。允许的字符不包括 UNICODE 控制字符（段 C0 和 C1）以及.，和 $。
JSON 对象中的所有值都可以是以下 JSON 类型：布尔值，数字，字符串，对象。数组是不允许的。整数的最大值是 4503599627370495，整数的最小值是 -4503599627370496。
标记，所需和报告属性中的所有 JSON 对象的最大深度均为 5。例如，以下对象是有效的：

{
      ...
      "tags": {
          "one": {
              "two": {
                  "three": {
                      "four": {
                          "five": {
                              "property": "value"
                          }
                      }
                  }
              }
          }
      },
      ...
  }

所有的字符串值最多可以有 4KB 的长度。

设备孪生大小

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 并发

标签，期望和报告的属性都支持 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

微信公众号