创建和读取 IoT 中心消息

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

注意

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

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

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

  • 一组预先确定的“系统属性”如下所示。

  • 一组 应用程序属性。 应用程序可以定义的字符串属性字典,而不需将消息正文反序列化即可进行访问。 IoT 中心永不修改这些属性。

  • 消息正文,可以是任何类型的数据。

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

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

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

  • 设备到云的消息可持久保留在 IoT 中心的默认 messages/events 终结点长达 7 天。

  • 设备到云的消息最大可为 256 KB,而且可分成多个批以优化发送。 批最大可为 256 KB。

  • IoT 中心不允许任意分区。 设备到云的消息根据其源于的 deviceId进行分区。

  • 控制对 IoT 中心的访问所述,IoT 中心允许基于设备的身份验证和访问控制。

  • 对于包含要进入应用程序属性的信息的消息,可以加上戳记。 有关详细信息,请参阅消息扩充

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

注意

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

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

有效的可路由消息正文可能如下所示:

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

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"
}

后续步骤