创建和读取 IoT 中心消息Create and read IoT Hub messages
为了支持无缝的跨协议互操作性，IoT 中心为所有面向设备的协议定义了通用消息格式。To support seamless interoperability across protocols, IoT Hub defines a common message format for all device-facing protocols. 此消息格式同时适用于设备到云的路由和云到设备的消息。This message format is used for both device-to-cloud routing and cloud-to-device messages.
备注
本文中提到的某些功能（例如云到设备消息传递、设备孪生、设备管理）仅在 IoT 中心的标准层中提供。Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT hub. 有关基本和标准 IoT 中心层的详细信息，请参阅如何选择合适的 IoT 中心层。For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.
IoT 中心使用流式消息传递模式实现设备到云的消息传递。IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. 与事件中心事件和服务总线消息相比，IoT 中心的设备到云消息更类似前者，类似之处在于有大量事件通过可供多个读取器读取的服务 。IoT Hub's device-to-cloud messages are more like Event Hubs events than Service Bus messages in that there is a high volume of events passing through the service that can be read by multiple readers.
IoT 中心消息由以下部分组成：An IoT Hub message consists of:
- 一组预先确定的“系统属性” 如下所示。A predetermined set of system properties as listed below.
- 一组 应用程序属性。A set of application properties. 应用程序可以定义的字符串属性字典，而不需将消息正文反序列化即可进行访问。A dictionary of string properties that the application can define and access, without needing to deserialize the message body. IoT 中心永不修改这些属性。IoT Hub never modifies these properties.
- 不透明的二进制正文。An opaque binary body.
使用 HTTPS 协议发送设备到云的消息或发送云到设备的消息时，属性名称和值只能包含 ASCII 字母数字字符加上 {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'}。Property names and values can only contain ASCII alphanumeric characters, plus {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} when you send device-to-cloud messages using the HTTPS protocol or send cloud-to-device messages.
使用 IoT 中心进行的设备到云的消息传送具有以下特征：Device-to-cloud messaging with IoT Hub has the following characteristics:
设备到云的消息可持久保留在 IoT 中心的默认 messages/events 终结点长达 7 天。Device-to-cloud messages are durable and retained in an IoT hub's default messages/events endpoint for up to seven days.
设备到云的消息最大可为 256 KB，而且可分成多个批以优化发送。Device-to-cloud messages can be at most 256 KB, and can be grouped in batches to optimize sends. 批最大可为 256 KB。Batches can be at most 256 KB.
IoT 中心不允许任意分区。IoT Hub does not allow arbitrary partitioning. 设备到云的消息根据其源于的 deviceId进行分区。Device-to-cloud messages are partitioned based on their originating deviceId.
如控制对 IoT 中心的访问中所述，IoT 中心允许基于设备的身份验证和访问控制。As explained in Control access to IoT Hub, IoT Hub enables per-device authentication and access control.
有关如何使用不同协议对已发送消息进行编码和解码的详细信息，请参阅 Azure IoT SDK。For more information about how to encode and decode messages sent using different protocols, see Azure IoT SDKs.
D2C IoT 中心消息的系统属性System Properties of D2C IoT Hub messages
| 属性Property | 说明Description | 用户可设置？User Settable? | 关键字（用于Keyword for 路由查询）routing query |
|---|---|---|---|
| message-idmessage-id | 用户可设置的消息标识符，用于请求-答复模式。A user-settable identifier for the message used for request-reply patterns. 格式：ASCII 7 位字母数字字符 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''} 的区分大小写字符串（最长为 128 个字符）。Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
是Yes | messageIdmessageId |
| iothub-enqueuedtimeiothub-enqueuedtime | IoT 中心收到设备到云消息的日期和时间。Date and time the Device-to-Cloud message was received by IoT Hub. | 否No | enqueuedTimeenqueuedTime |
| user-iduser-id | 用于指定消息的源的 ID。An ID used to specify the origin of messages. 如果消息是由 IoT 中心生成的，则设置为 {iot hub name}。When messages are generated by IoT Hub, it is set to {iot hub name}. |
是Yes | userIduserId |
| iothub-connection-device-idiothub-connection-device-id | IoT 中心对设备到云的消息设置的 ID。An ID set by IoT Hub on device-to-cloud messages. 它包含发送消息的设备的 deviceId 。It contains the deviceId of the device that sent the message. | 否No | connectionDeviceIdconnectionDeviceId |
| iothub-connection-module-idiothub-connection-module-id | IoT 中心对设备到云的消息设置的 ID。An ID set by IoT Hub on device-to-cloud messages. 它包含发送消息的设备的 moduleId。It contains the moduleId of the device that sent the message. | 否No | connectionModuleIdconnectionModuleId |
| iothub-connection-auth-generation-idiothub-connection-auth-generation-id | IoT 中心对设备到云的消息设置的 ID。An ID set by IoT Hub on device-to-cloud messages. 它包含发送消息的设备的 connectionDeviceGenerationId（根据设备标识属性）。It contains the connectionDeviceGenerationId (as per Device identity properties) of the device that sent the message. | 否No | connectionDeviceGenerationIdconnectionDeviceGenerationId |
| iothub-connection-auth-methodiothub-connection-auth-method | 由 IoT 中心对设备到云的消息设置的身份验证方法。An authentication method set by IoT Hub on device-to-cloud messages. 此属性包含用于验证发送消息的设备的身份验证方法的相关信息。This property contains information about the authentication method used to authenticate the device sending the message. | 否No | connectionAuthMethodconnectionAuthMethod |
C2D IoT 中心消息的系统属性System Properties of C2D IoT Hub messages
| 属性Property | 说明Description | 用户可设置？User Settable? | |
|---|---|---|---|
| message-idmessage-id | 用户可设置的消息标识符，用于请求-答复模式。A user-settable identifier for the message used for request-reply patterns. 格式：ASCII 7 位字母数字字符 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''} 的区分大小写字符串（最长为 128 个字符）。Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
是Yes | |
| sequence-numbersequence-number | IoT 中心分配给每条云到设备消息的编号（对每个设备队列是唯一的）。A number (unique per device-queue) assigned by IoT Hub to each cloud-to-device message. | 否No | |
| toto | 云到设备消息中指定的目标。A destination specified in Cloud-to-Device messages. | 否No | |
| absolute-expiry-timeabsolute-expiry-time | 消息过期的日期和时间。Date and time of message expiration. | 否No | |
| correlation-idcorrelation-id | 响应消息中的字符串属性，通常包含采用“请求-答复”模式的请求的 MessageId。A string property in a response message that typically contains the MessageId of the request, in request-reply patterns. | 是Yes | |
| user-iduser-id | 用于指定消息的源的 ID。An ID used to specify the origin of messages. 如果消息是由 IoT 中心生成的，则设置为 {iot hub name}。When messages are generated by IoT Hub, it is set to {iot hub name}. |
是Yes | |
| iothub-ackiothub-ack | 反馈消息生成器。A feedback message generator. 此属性在云到设备的消息中用于请求 IoT 中心因为设备使用消息而生成反馈消息。This property is used in cloud-to-device messages to request IoT Hub to generate feedback messages as a result of the consumption of the message by the device. 可能的值：none（默认值）：不生成任何反馈消息；positive：如果消息已完成，则接收反馈消息；negative：如果消息未由设备完成就过期（或已达到最大传送计数），则收到反馈消息；full：positive 和 negative。Possible values: none (default): no feedback message is generated, positive: receive a feedback message if the message was completed, negative: receive a feedback message if the message expired (or maximum delivery count was reached) without being completed by the device, or full: both positive and negative. | 是Yes |
系统属性名称System Property Names
系统属性名称根据消息要路由到的终结点而有所不同。The system property names vary based on the endpoint to which the messages are being routed. 有关这些名称的详细信息，请参阅下表。Please see the table below for details on these names.
| 系统属性名称System property name | 事件中心Event Hubs | Azure 存储Azure Storage | 服务总线Service Bus | 事件网格Event Grid |
|---|---|---|---|---|
| 消息 IDMessage ID | message-idmessage-id | messageIdmessageId | MessageIdMessageId | message-idmessage-id |
| 用户 idUser id | user-iduser-id | userIduserId | UserIdUserId | user-iduser-id |
| 连接设备 idConnection device id | iothub-connection-device-idiothub-connection-device-id | connectionDeviceIdconnectionDeviceId | iothub-connection-device-idiothub-connection-device-id | iothub-connection-device-idiothub-connection-device-id |
| 连接模块 idConnection module id | iothub-connection-module-idiothub-connection-module-id | connectionModuleIdconnectionModuleId | iothub-connection-module-idiothub-connection-module-id | iothub-connection-module-idiothub-connection-module-id |
| 连接身份验证生成 idConnection auth generation id | iothub-connection-auth-generation-idiothub-connection-auth-generation-id | connectionDeviceGenerationIdconnectionDeviceGenerationId | iothub-connection-auth-generation-idiothub-connection-auth-generation-id | iothub-connection-auth-generation-idiothub-connection-auth-generation-id |
| 连接身份验证方法Connection auth method | iothub-connection-auth-methodiothub-connection-auth-method | connectionAuthMethodconnectionAuthMethod | iothub-connection-auth-methodiothub-connection-auth-method | iothub-connection-auth-methodiothub-connection-auth-method |
| contentTypecontentType | content-typecontent-type | contentTypecontentType | ContentTypeContentType | iothub-content-typeiothub-content-type |
| contentEncodingcontentEncoding | content-encodingcontent-encoding | contentEncodingcontentEncoding | ContentEncodingContentEncoding | iothub-content-encodingiothub-content-encoding |
| iothub-enqueuedtimeiothub-enqueuedtime | iothub-enqueuedtimeiothub-enqueuedtime | enqueuedTimeenqueuedTime | 空值N/A | iothub-enqueuedtimeiothub-enqueuedtime |
| iothub-interface-nameiothub-interface-name | iothub-interface-nameiothub-interface-name | interfaceNameinterfaceName | Iothub-interface-nameIothub-interface-name | iothub-interface-nameiothub-interface-name |
| CorrelationIdCorrelationId | correlation-idcorrelation-id | correlationIdcorrelationId | CorrelationIdCorrelationId | correlation-idcorrelation-id |
消息大小Message size
IoT 中心用于衡量消息大小的方法与协议无关，仅考虑实际有效负载。IoT Hub measures message size in a protocol-agnostic way, considering only the actual payload. 以字节为单位的大小计算为以下值的和：The size in bytes is calculated as the sum of the following values:
- 以字节为单位的正文大小。The body size in bytes.
- 以字节为单位的消息系统属性的所有值的大小。The size in bytes of all the values of the message system properties.
- 以字节为单位的所有用户属性名称和值的大小。The size in bytes of all user property names and values.
属性名称和值限制为 ASCII 字符，因此，字符串的长度等于以字节为单位的大小。Property names and values are limited to ASCII characters, so the length of the strings equals the size in bytes.
反欺骗属性Anti-spoofing properties
为了避免设备到云的消息中出现设备欺骗，IoT 中心使用以下属性在所有消息上加上戳记：To avoid device spoofing in device-to-cloud messages, IoT Hub stamps all messages with the following properties:
- iothub-connection-device-idiothub-connection-device-id
- iothub-connection-auth-generation-idiothub-connection-auth-generation-id
- iothub-connection-auth-methodiothub-connection-auth-method
根据设备标识属性，前两个属性包含源设备的 deviceId 和 generationId 。The first two contain the deviceId and generationId of the originating device, as per Device identity properties.
iothub-connection-auth-method 属性包含具有以下属性的 JSON 序列化对象：The iothub-connection-auth-method property contains a JSON serialized object, with the following properties:
{
"scope": "{ hub | device }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
后续步骤Next steps
有关 IoT 中心消息大小限制的详细信息，请参阅 IoT 中心配额和限制。For information about message size limits in IoT Hub, see IoT Hub quotas and throttling.
若要了解如何用不同编程语言创建并读取 IoT 中心消息，请参阅快速入门。To learn how to create and read IoT Hub messages in various programming languages, see the Quickstarts.