从 IoT 中心发送云到设备的消息

10/29/2018
作者

从解决方案后端向设备应用发送单向通知, 从 IoT 中心向设备发送云到设备的消息。有关 IoT 中心支持的其他云到设备选项的介绍，请参阅云到设备的通信指南。

Note

本文中所述的功能仅可在 IoT 中心的标准层中使用。有关基本和标准 IoT 中心层的详细信息，请参阅如何选择合适的 IoT 中心层。

可以通过面向服务的终结点 (/messages/devicebound) 发送从云到设备的消息。随后设备可以通过特定于设备的终结点 (/devices/{deviceId}/messages/devicebound) 接收这些消息。

要将每个从云到设备的消息都设为以单个设备为目标，请通过 IoT 中心将 to 属性设置为 /devices/{deviceId}/messages/devicebound。

每个设备队列最多可以保留 50 条云到设备的消息。尝试将更多消息传送到同一设备会导致错误。

云到设备的消息生命周期

为了保证至少一次消息传递，IoT 中心将云到设备的消息保留在每个设备队列中。设备必须显式确认完成，IoT 中心才会从队列中将其删除。这种方法可以保证连接失败和设备故障时能够复原。

下图显示了 IoT 中心内云到设备消息的生命周期状态图。

云到设备的消息生命周期

IoT 中心服务向设备发送消息时，该服务会将消息状态设置为“排队”。设备要接收消息时，IoT 中心会锁定该消息（将状态设置为“不可见”），以便让设备上的其他线程开始接收其他消息。当设备线程完成消息的处理后，将通过完成消息来通知 IoT 中心。随后 IoT 中心会将状态设置为“已完成”。

设备还可以选择：

拒绝消息，这会使 IoT 中心将此消息设置为死信状态。通过 MQTT 协议进行连接的设备无法拒绝云到设备的消息。
放弃消息，这会使 IoT 中心将消息放回队列，并将状态设置为已排队。通过 MQTT 协议连接的设备无法放弃云到设备消息。

线程可能无法处理消息，且不通知 IoT 中心。在此情况下，在可见性(或锁定)超时时间之后，消息从不可见状态自动转换回已排队状态。此超时的默认值为一分钟。

消息可以在“已排队”与“不可见”状态之间转换的次数，以 IoT 中心上“最大传送计数”属性中指定的次数为上限。在该转换次数之后，IoT 中心会将消息的状态设置为“死信”。同样，IoT 中心也会在消息的到期时间之后（请参阅生存时间），将消息的状态设置为“死信”。

如何使用 IoT 中心发送云到设备的消息介绍如何从云端发送云到设备的消息以及如何在设备上接收这些消息。

通常只要丢失消息不影响应用程序逻辑，设备就会完成云到设备的消息。例如，设备已在本地保留消息内容或已成功执行操作。消息还可能携带暂时性信息，这类信息的丢失不会影响应用程序的功能。有时，对于长时间运行的任务，可以：

将任务说明保留到本地存储后完成该云到设备的消息。
在作业进度的不同阶段，可以使用一条或多条设备到云的消息通知解决方案后端。

消息到期时间（生存时间）

每条云到设备的消息都有过期时间。此时间由下列内容之一设定：

服务中的 ExpiryTimeUtc 属性。
使用了指定为 IoT 中心属性的默认生存时间的 IoT 中心。

请参阅云到设备的配置选项。

利用消息到期时间并避免将消息发送到已断开连接的设备的常见方法是设置较短的生存时间值。此方法可达到与维护设备连接状态一样的效果，而且更加有效。请求消息确认时，IoT 中心将通知你哪些设备：

可以接收消息。
不处于联机状态，或出现故障。

消息反馈

发送云到设备的消息时，服务可以请求传送每条消息的反馈（关于该消息的最终状态）。

Ack 属性	行为
positive	如果云到设备的消息达到“已完成”状态，IoT 中心将生成反馈消息。
negative	如果云到设备的消息达到“死信”状态，IoT 中心将生成反馈消息。
full	IoT 中心在任一情况下都会生成反馈消息。

如果 Ack 为 full，且未收到反馈消息，则意味着反馈消息已过期。该服务无法了解原始消息的经历。实际上，服务应该确保它可以在反馈过期之前对其进行处理。最长过期时间是两天，因此当发生故障时，有时间让服务再次运行。

如终结点中所述，IoT 中心通过面向服务的终结点 (/messages/servicebound/feedback) 以消息方式传送反馈。接收反馈的语义与云到设备消息的语义相同。可能的话，消息反馈将放入单个消息中，其格式如下：

属性	说明
EnqueuedTime	指示中心收到反馈消息时的时间戳。
UserId	`{iot hub name}`
ContentType	`application/vnd.microsoft.iothub.feedback.json`

正文是记录的 JSON 序列化数组，每条记录具有以下属性：

属性	说明
EnqueuedTimeUtc	指示消息结果出现时的时间戳。例如，中心收到了已过期的反馈消息或原始消息。
OriginalMessageId	与此反馈信息相关的从云到设备的消息的 MessageId。
StatusCode	必需的字符串。在 IoT 中心生成的反馈消息中使用。 “Success” “Expired” “DeliveryCountExceeded” “Rejected” “Purged”
说明	StatusCode的字符串值。
deviceId	与此反馈信息相关的从云到设备的消息的目标设备的 DeviceId。
DeviceGenerationId	与此反馈信息相关的从云到设备的消息的目标设备的 DeviceGenerationId。

服务必须指定从云到设备的消息的 MessageId，才能将其反馈与原始消息相关联。

以下示例演示了反馈消息的正文。

[
  {
    "OriginalMessageId": "0987654321",
    "EnqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
    "StatusCode": 0,
    "Description": "Success",
    "DeviceId": "123",
    "DeviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
  },
  {
    ...
  },
  ...
]

云到设备的配置选项

每个 IoT 中心都针对云到设备的消息传送公开以下配置选项：

属性	说明	范围和默认值
defaultTtlAsIso8601	云到设备消息的默认 TTL。	ISO_8601 间隔高达 2D（最小为 1 分钟）。默认值：1 小时。
maxDeliveryCount	每个设备队列的云到设备最大传送计数。	1 到 100。默认值：10。
feedback.ttlAsIso8601	服务绑定反馈消息的保留时间。	ISO_8601 间隔高达 2D（最小为 1 分钟）。默认值：1 小时。
feedback.maxDeliveryCount	反馈队列的最大传送计数。	1 到 100。默认值：100。

有关如何设置这些配置选项的详细信息，请参阅创建 IoT 中心。

从 IoT 中心发送云到设备的消息

云到设备的消息生命周期

消息到期时间（生存时间）

消息反馈

云到设备的配置选项

后续步骤