Skip to content

Latest commit

 

History

History
75 lines (58 loc) · 4.81 KB

iot-hub-devguide-messages-construct.md

File metadata and controls

75 lines (58 loc) · 4.81 KB
title description services documentationcenter author manager editor ms.assetid ms.service ms.devlang ms.topic ms.tgt_pltfrm ms.workload ms.date ms.author
Understand Azure IoT Hub message format | Microsoft Docs
Developer guide - descibes the format and expected content of IoT Hub messages.
iot-hub
.net
dominicbetts
timlt
3fc5f1a3-3711-4611-9897-d4db079b4250
iot-hub
multiple
article
na
na
05/25/2017
dobett

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 and cloud-to-device messages. An IoT Hub message consists of:

  • A set of system properties. Properties that IoT Hub interprets or sets. This set is predetermined.
  • 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.
  • Send cloud-to-device messages.

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
MessageId 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 + {'-', ':',’.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
Sequence number A number (unique per device-queue) assigned by IoT Hub to each cloud-to-device message.
To A destination specified in Cloud-to-Device messages.
ExpiryTimeUtc Date and time of message expiration.
EnqueuedTime Date and time the Cloud-to-Device message was received by IoT Hub.
CorrelationId A string property in a response message that typically contains the MessageId of the request, in request-reply patterns.
UserId An ID used to specify the origin of messages. When messages are generated by IoT Hub, it is set to {iot hub name}.
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. For more information, see Message feedback.
ConnectionDeviceId An ID set by IoT Hub on device-to-cloud messages. It contains the deviceId of the device that sent the message.
ConnectionDeviceGenerationId 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.
ConnectionAuthMethod 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. For more information, see Device to cloud anti-spoofing.

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.

Next steps

For information about message size limits in IoT Hub, see IoT Hub quotas and throttling.

To learn how to create and read IoT Hub messages in various programming languages, see the Get started tutorials.