创建和读取 IoT 中心消息

  • 项目

为了支持跨协议的无缝互操作性，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 中心允许基于设备的身份验证和访问控制。

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

有关如何使用不同协议对已发送消息进行编码和解码的详细信息，请参阅 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"
}

后续步骤