为了支持跨协议的互操作性,IoT 中心定义了一组通用的消息传送功能,这些功能在所有面向设备的协议中都可用。 这些功能可用于设备到云消息和云到设备消息。
备注
本文中提到的某些功能(例如云到设备消息传递、设备孪生、设备管理)仅在 IoT 中心的标准层中提供。 有关 IoT 中心基本层和标准/免费层的详细信息,请参阅选择适合你的解决方案的 IoT 中心层。
IoT 中心使用流式消息传递模式实现设备到云的消息传递。 IoT 中心的设备到云消息更类似于事件中心事件,而不是服务总线消息,因为有大量的事件可以被多个读取器读取。
IoT 中心消息由以下部分组成:
一组预先确定的系统属性,如本文后面所述。
一组 应用程序属性。 应用程序可以定义的字符串属性字典,而不需将消息正文反序列化即可进行访问。 IoT 中心永不修改这些属性。
消息正文,可以是任何类型的数据。
每个设备协议都以不同的方式实现属性的设置。 有关详细信息,请参阅使用 MQTT 协议与 IoT 中心通信 , 并使用 AMQP 协议开发人员指南与 IoT 中心通信 以了解详细信息。
使用 HTTPS 协议发送设备到云消息或发送云到设备消息时,属性名称和值只能包含 ASCII 字母数字字符以及 ! # $ % & ' * + - . ^ _ ` | ~
。
使用 IoT 中心进行的设备到云的消息传送具有以下特征:
设备到云的消息可持久保留在 IoT 中心的默认 messages/events 终结点长达 7 天。
设备到云的消息最多可以是 256 KB,可以分批分组以优化发送。 批最大可为 256 KB。
IoT 中心不允许任意分区。 设备到云的消息根据其源于的 deviceId进行分区。
如 使用 Microsoft Entra ID 控制对 IoT 中心的访问中所述,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 | 说明 | 用户可设置? | 路由查询 的关键字 |
---|---|---|---|
消息标识符 | 用户可设置的消息标识符,用于请求-答复模式。 格式:ASCII 7 位字母数字字符 + - : . + % _ # * ? ! ( ) , = @ ; $ ' 的区分大小写字符串(最长为 128 个字符)。 |
是 | 消息ID |
iothub-enqueuedtime | IoT 中心接收 设备到云 的消息的日期和时间。 | 否 | enqueuedTime |
用户ID | 用于指定消息的源的 ID。 | 是 | 用户 ID |
iothub连接设备ID | IoT 中心对设备到云的消息设置的 ID。 它包含发送消息的设备的 deviceId 。 | 否 | 连接设备标识 |
iothub-connection-module-id | IoT 中心对设备到云的消息设置的 ID。 它包含发送消息的设备的 moduleId。 | 否 | 连接模块ID |
iothub-connection-auth-generation-id | IoT 中心对设备到云的消息设置的 ID。 它包含发送消息的设备的 connectionDeviceGenerationId(根据设备标识属性)。 | 否 | 连接设备生成ID |
物联网中心-连接-认证方法 | 由 IoT 中心对设备到云的消息设置的身份验证方法。 此属性包含用于验证发送消息的设备的身份验证方法的相关信息。 | 否 | 连接认证方法 |
iothub-app-iothub-creation-time-utc(物联网中心应用创建时间-协调世界时) | 允许设备在批量发送数据时发送事件创建时间。 | 是 | 创建时间-UTC |
iothub-creation-time-utc (物联网中心创建时间,世界协调时间) | 允许设备在一次发送一条消息时发送事件创建时间。 | 是 | 创建时间-UTC |
dt-数据架构 | IoT 中心在设备到云的消息上设置此值。 它包含在设备连接中设置的设备型号 ID。 | 否 | $dt-dataschema |
dt-subject | 正在发送设备到云的消息的组件的名称。 | 是 | $dt-主题 |
应用程序属性的常见用途是使用 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 | 说明 | 用户可设置? |
---|---|---|
消息标识符 | 用户可设置的消息标识符,用于请求-答复模式。 格式:ASCII 7 位字母数字字符 + - : . + % _ # * ? ! ( ) , = @ ; $ ' 的区分大小写字符串(最长为 128 个字符)。 |
是 |
序列号 | IoT 中心分配给每条云到设备消息的编号(对每个设备队列是唯一的)。 | 否 |
到 | 云到设备消息中指定的目标。 | 否 |
绝对过期时间 | 消息过期的日期和时间。 | 是 |
关联标识符 | 响应消息中的字符串属性,通常包含采用“请求-答复”模式的请求的 MessageId。 | 是 |
用户ID | 用于指定消息的源的 ID。 当 IoT 中心生成消息时,用户 ID 是 IoT 中心名称。 | 是 |
iothub-ack | 反馈消息生成器。 此属性在云到设备的消息中用于请求 IoT 中心因为设备使用消息而生成反馈消息。 可能的值:none(默认值):不生成任何反馈消息;positive:如果消息已完成,则接收反馈消息;negative:如果消息未由设备完成就过期(或已达到最大传送计数),则收到反馈消息;full:positive 和 negative。 | 是 |
系统属性名称根据消息要路由到的终结点而有所不同。
系统属性名称 | 事件中心 | Azure 存储 | 服务总线 | 事件网格 |
---|---|---|---|---|
消息 ID | 消息标识符 | 消息ID | 消息ID | 消息标识符 |
用户 id | 用户ID | 用户 ID | UserId | 用户ID |
连接设备 id | iothub连接设备ID | 连接设备标识 | iothub连接设备ID | iothub连接设备ID |
连接模块 id | iothub-connection-module-id | 连接模块标识 | iothub-连接模块-id | iothub-connection-module-id(IoT 中心连接模块 ID) |
连接身份验证生成 id | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
连接身份验证方法 | 物联网中心-连接-认证方法 | 连接认证方法 | 物联网中心-连接-认证方法 | 物联网中心-连接-认证方法 |
内容类型 | Content-Type | 内容类型 | 内容类型 | iothub-content-type |
内容编码 | 内容编码 | 内容编码 | 内容编码 | iothub-内容编码 |
iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | 空值 | iothub-enqueuedtime |
CorrelationId | 关联标识符 | correlationId | CorrelationId | 关联标识符 |
dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
dt-subject | dt-subject | dt-subject | dt-subject | dt-主题 |
IoT 中心用于衡量消息大小的方法与协议无关,仅考虑实际有效负载。 以字节为单位的大小计算为以下值的和:
- 以字节为单位的正文大小。
- 以字节为单位的消息系统属性的所有值的大小。
- 以字节为单位的所有用户属性名称和值的大小。
属性名称和值限制为 ASCII 字符,因此,字符串的长度等于以字节为单位的大小。
为了避免设备到云的消息中出现设备欺骗,IoT 中心使用以下属性在所有消息上加上戳记:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-连接认证方法
根据设备标识属性,前两个属性包含源设备的 deviceId 和 generationId 。
iothub-connection-auth-method 属性包含具有以下属性的 JSON 序列化对象:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
- 有关 IoT 中心消息大小限制的详细信息,请参阅 IoT 中心配额和限制。
- 若要了解如何使用各种编程语言创建和读取 IoT 中心消息,请参阅 教程:将遥测数据从 IoT 即插即用设备发送到 Azure IoT 中心。
- 若要了解 IoT 中心生成的非遥测事件的结构,请参阅 Azure IoT 中心非遥测事件架构。