Skip to content

Latest commit

 

History

History
95 lines (65 loc) · 6.45 KB

iot-hub-devguide-messages-construct.md

File metadata and controls

95 lines (65 loc) · 6.45 KB

title: Understand Azure IoT Hub message format | Microsoft Docs description: Developer guide - descibes the format and expected content of IoT Hub messages. author: ash2017 manager: briz ms.service: iot-hub services: iot-hub ms.topic: conceptual ms.date: 08/13/2018 ms.author: asrastog

Create and read IoT Hub messages

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.

[!INCLUDE iot-hub-basic]

IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. 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.

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 Hub never modifies these properties.

  • An opaque binary body.

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.

Device-to-cloud messaging with IoT Hub has the following characteristics:

  • Device-to-cloud messages are durable and retained in an IoT hub's default messages/events endpoint for up to seven days.

  • Device-to-cloud messages can be at most 256 KB, and can be grouped in batches to optimize sends. Batches can be at most 256 KB.

  • IoT Hub does not allow arbitrary partitioning. Device-to-cloud messages are partitioned based on their originating deviceId.

  • As explained in Control access to IoT Hub, IoT Hub enables per-device authentication and access control.

For more information about how to encode and decode messages sent using different protocols, see Azure IoT SDKs.

The following table lists the set of system properties in IoT Hub messages.

Property Description Is user settable?
message-id A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. Yes
sequence-number A number (unique per device-queue) assigned by IoT Hub to each cloud-to-device message. No for C2D messages; yes otherwise.
to A destination specified in Cloud-to-Device messages. No for C2D messages; yes otherwise.
absolute-expiry-time Date and time of message expiration. Yes
iothub-enqueuedtime Date and time the Cloud-to-Device message was received by IoT Hub. No for C2D messages; yes otherwise.
correlation-id A string property in a response message that typically contains the MessageId of the request, in request-reply patterns. Yes
user-id An ID used to specify the origin of messages. When messages are generated by IoT Hub, it is set to {iot hub name}. No
iothub-ack A feedback message generator. 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. 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 |

| iothub-connection-device-id |An ID set by IoT Hub on device-to-cloud messages. It contains the deviceId of the device that sent the message. | No for D2C messages; yes otherwise. | | iothub-connection-auth-generation-id |An ID set by IoT Hub on device-to-cloud messages. It contains the generationId (as per Device identity properties) of the device that sent the message. | No for D2C messages; yes otherwise. | | iothub-connection-auth-method |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 for D2C messages; yes otherwise. | | iothub-creation-time-utc | Date and time the message was created on a device. A device must set this value explicitly. | Yes |

Message size

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:

  • 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.

Property names and values are limited to ASCII characters, so the length of the strings equals the size in bytes.

Anti-spoofing properties

To avoid device spoofing in device-to-cloud messages, IoT Hub stamps all messages with the following properties:

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • iothub-connection-auth-method

The first two contain the deviceId and generationId of the originating device, as per Device identity properties.

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