创建和读取 IoT 中心消息

项目
12/03/2021

为了支持无缝的跨协议互操作性，IoT 中心为所有面向设备的协议定义了通用消息格式。此消息格式同时适用于设备到云的路由和云到设备的消息。

注意

本文中提到的某些功能（例如云到设备消息传递、设备孪生、设备管理）仅在 IoT 中心的标准层中提供。有关基本和标准 IoT 中心层的详细信息，请参阅如何选择合适的 IoT 中心层。

IoT 中心使用流式消息传递模式实现设备到云的消息传递。与事件中心事件和服务总线消息相比，IoT 中心的设备到云消息更类似前者，类似之处在于有大量事件通过可供多个读取器读取的服务。

IoT 中心消息由以下部分组成：

一组预先确定的“系统属性”如下所示。
一组 应用程序属性。应用程序可以定义的字符串属性字典，而不需将消息正文反序列化即可进行访问。 IoT 中心永不修改这些属性。
不透明的二进制正文。

使用 HTTPS 协议发送设备到云的消息或发送云到设备的消息时，属性名称和值只能包含 ASCII 字母数字字符加上 {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'}。

使用 IoT 中心进行的设备到云的消息传送具有以下特征：

设备到云的消息可持久保留在 IoT 中心的默认 messages/events 终结点长达 7 天。
设备到云的消息最大可为 256 KB，而且可分成多个批以优化发送。批最大可为 256 KB。
IoT 中心不允许任意分区。设备到云的消息根据其源于的 deviceId进行分区。
如控制对 IoT 中心的访问中所述，IoT 中心允许基于设备的身份验证和访问控制。

有关如何使用不同协议对已发送消息进行编码和解码的详细信息，请参阅 Azure IoT SDK。

D2C IoT 中心消息的系统属性

属性	说明	用户可设置？	路由查询的关键字
message-id	用户可设置的消息标识符，用于请求-答复模式。格式：ASCII 7 位字母数字字符 + `{'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}` 的区分大小写字符串（最长为 128 个字符）。	是	messageId
iothub-enqueuedtime	IoT 中心收到设备到云消息的日期和时间。	否	enqueuedTime
user-id	用于指定消息的源的 ID。如果消息是由 IoT 中心生成的，则设置为 `{iot hub name}`。	是	userId
iothub-connection-device-id	IoT 中心对设备到云的消息设置的 ID。它包含发送消息的设备的 deviceId 。	否	connectionDeviceId
iothub-connection-module-id	IoT 中心对设备到云的消息设置的 ID。它包含发送消息的设备的 moduleId。	否	connectionModuleId
iothub-connection-auth-generation-id	IoT 中心对设备到云的消息设置的 ID。它包含发送消息的设备的 connectionDeviceGenerationId（根据设备标识属性）。	否	connectionDeviceGenerationId
iothub-connection-auth-method	由 IoT 中心对设备到云的消息设置的身份验证方法。此属性包含用于验证发送消息的设备的身份验证方法的相关信息。	否	connectionAuthMethod
dt-dataschema	此值是由 IoT 中心对设备到云的消息设置的。它包含在设备连接中设置的设备型号 ID。	否	$dt-dataschema
dt-subject	正在发送设备到云的消息的组件的名称。	是	$dt-subject

D2C IoT 中心消息的应用程序属性

应用程序属性的一个常见用途是使用 iothub-creation-time-utc 属性从设备发送时间戳，以记录设备发送消息的时间。此时间戳的格式必须为 UTC（不含时区信息）。例如，2021-04-21T11:30:16Z 有效，2021-04-21T11:30:16-07:00 无效：

{
  "applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
  "messageSource":"telemetry",
  "deviceId":"sample-device-01",
  "schema":"default@v1",
  "templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
  "enqueuedTime":"2021-01-29T16:45:39.143Z",
  "telemetry":{
    "temperature":8.341033560421833
  },
  "messageProperties":{
    "iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
  },
  "enrichments":{}
}

C2D IoT 中心消息的系统属性

属性	说明	用户可设置？
message-id	用户可设置的消息标识符，用于请求-答复模式。格式：ASCII 7 位字母数字字符 + `{'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}` 的区分大小写字符串（最长为 128 个字符）。	是
sequence-number	IoT 中心分配给每条云到设备消息的编号（对每个设备队列是唯一的）。	否
to	云到设备消息中指定的目标。	否
absolute-expiry-time	消息过期的日期和时间。	是
correlation-id	响应消息中的字符串属性，通常包含采用“请求-答复”模式的请求的 MessageId。	是
user-id	用于指定消息的源的 ID。如果消息是由 IoT 中心生成的，则设置为 `{iot hub name}`。	是
iothub-ack	反馈消息生成器。此属性在云到设备的消息中用于请求 IoT 中心因为设备使用消息而生成反馈消息。可能的值：none（默认值）：不生成任何反馈消息；positive：如果消息已完成，则接收反馈消息；negative：如果消息未由设备完成就过期（或已达到最大传送计数），则收到反馈消息；full：positive 和 negative。	是

系统属性名称

系统属性名称根据消息要路由到的终结点而有所不同。有关这些名称的详细信息，请参阅下表。

系统属性名称	事件中心	Azure 存储	服务总线	事件网格
消息 ID	message-id	messageId	MessageId	message-id
用户 id	user-id	userId	UserId	user-id
连接设备 id	iothub-connection-device-id	connectionDeviceId	iothub-connection-device-id	iothub-connection-device-id
连接模块 id	iothub-connection-module-id	connectionModuleId	iothub-connection-module-id	iothub-connection-module-id
连接身份验证生成 id	iothub-connection-auth-generation-id	connectionDeviceGenerationId	iothub-connection-auth-generation-id	iothub-connection-auth-generation-id
连接身份验证方法	iothub-connection-auth-method	connectionAuthMethod	iothub-connection-auth-method	iothub-connection-auth-method
contentType	content-type	contentType	ContentType	iothub-content-type
contentEncoding	content-encoding	contentEncoding	ContentEncoding	iothub-content-encoding
iothub-enqueuedtime	iothub-enqueuedtime	enqueuedTime	空值	iothub-enqueuedtime
CorrelationId	correlation-id	correlationId	CorrelationId	correlation-id
dt-dataschema	dt-dataschema	dt-dataschema	dt-dataschema	dt-dataschema
dt-subject	dt-subject	dt-subject	dt-subject	dt-subject

消息大小

IoT 中心用于衡量消息大小的方法与协议无关，仅考虑实际有效负载。以字节为单位的大小计算为以下值的和：

以字节为单位的正文大小。
以字节为单位的消息系统属性的所有值的大小。
以字节为单位的所有用户属性名称和值的大小。

属性名称和值限制为 ASCII 字符，因此，字符串的长度等于以字节为单位的大小。

反欺骗属性

为了避免设备到云的消息中出现设备欺骗，IoT 中心使用以下属性在所有消息上加上戳记：

iothub-connection-device-id
iothub-connection-auth-generation-id
iothub-connection-auth-method

根据设备标识属性，前两个属性包含源设备的 deviceId 和 generationId 。

iothub-connection-auth-method 属性包含具有以下属性的 JSON 序列化对象：

{
  "scope": "{ hub | device }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

后续步骤

有关 IoT 中心消息大小限制的详细信息，请参阅 IoT 中心配额和限制。
若要了解如何用不同编程语言创建并读取 IoT 中心消息，请参阅快速入门。