创建和读取 IoT 中心消息

为了支持无缝的跨协议互操作性,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 中心消息,请参阅快速入门