创建和读取 IoT 中心消息

项目
09/30/2024

为了支持跨协议的互操作性，IoT 中心定义了一组通用的消息传送功能，这些功能在所有面向设备的协议中都可用。这些功能可用于设备到云消息和云到设备消息。

注意

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

IoT 中心使用流式消息传递模式实现设备到云的消息传递。 IoT 中心的设备到云消息更像是事件中心事件，而非服务总线消息，因为有大量事件通过服务传递，可供多个读取器读取。

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

一组预先确定的系统属性，如本文后面所述。
一组 应用程序属性。应用程序可以定义的字符串属性字典，而不需将消息正文反序列化即可进行访问。 IoT 中心永不修改这些属性。
消息正文，可以是任何类型的数据。

每个设备协议都以不同的方式实现属性的设置。有关详细信息，请参阅 MQTT 协议指南和 AMQP 开发人员指南。

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

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

设备到云的消息可持久保留在 IoT 中心的默认 messages/events 终结点长达 7 天。
设备到云的消息最大可为 256 KB，而且可分成多个批以优化发送。批最大可为 256 KB。
IoT 中心不允许任意分区。设备到云的消息根据其源于的 deviceId进行分区。
如控制对 IoT 中心的访问所述，IoT 中心允许基于设备的身份验证和访问控制。
对于包含要进入应用程序属性的信息的消息，可以加上戳记。有关详细信息，请参阅消息扩充。

注意

每个 IoT 中心协议都提供一个消息内容类型属性。将数据路由到自定义终结点时，会沿用该属性。要在目标位置正确处理数据（例如，将 JSON 视为可分析字符串而不是 Base64 编码的二进制数据），请为消息提供适当的内容类型和字符集。

要在 IoT 中心路由查询中使用消息正文，请为消息提供有效的 JSON 对象，并将消息的内容类型属性设置为 application/json;charset=utf-8。

以下示例显示了有效的可路由消息正文：

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

设备到云消息的系统属性

properties	说明	用户可设置？	路由查询的关键字
message-id	用户可设置的消息标识符，用于请求-答复模式。格式：ASCII 7 位字母数字字符 + `- : . + % _ # * ? ! ( ) , = @ ; $ '` 的区分大小写字符串（最长为 128 个字符）。	是	messageId
iothub-enqueuedtime	IoT 中心收到设备到云消息的日期和时间。	否	enqueuedTime
user-id	用于指定消息的源的 ID。	是	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
iothub-app-iothub-creation-time-utc	允许设备在批量发送数据时发送事件创建时间。	是	creation-time-utc
iothub-creation-time-utc	允许设备在一次发送一条消息时发送事件创建时间。	是	creation-time-utc
dt-dataschema	此值是由 IoT 中心对设备到云的消息设置的。它包含在设备连接中设置的设备型号 ID。	否	$dt-dataschema
dt-subject	正在发送设备到云的消息的组件的名称。	是	$dt-subject

设备到云消息的应用程序属性

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

{
  "applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
  "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":{}
}

云到设备消息的系统属性

properties	说明	用户可设置？
message-id	用户可设置的消息标识符，用于请求-答复模式。格式：ASCII 7 位字母数字字符 + `- : . + % _ # * ? ! ( ) , = @ ; $ '` 的区分大小写字符串（最长为 128 个字符）。	是
sequence-number	IoT 中心分配给每条云到设备消息的编号（对每个设备队列是唯一的）。	否
to	云到设备消息中指定的目标。	否
absolute-expiry-time	消息过期的日期和时间。	是
correlation-id	响应消息中的字符串属性，通常包含采用“请求-答复”模式的请求的 MessageId。	是
user-id	用于指定消息的源的 ID。 IoT 中心生成消息时，用户 ID 是 IoT 中心名称。	是
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 | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

后续步骤

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

通过