Merge pull request #187959 from jlorich/iot-improved-details-on-message-body

improve clarity around message body and content type

Author: PRMerger12

articles/iot-hub/iot-hub-amqp-support.md

@@ -5,7 +5,7 @@ author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 04/30/2019
+ms.date: 04/21/2022
 ms.author: kgremban
 ms.custom:  [amqp, mqtt]
 ---
@@ -316,6 +316,8 @@ while True:
 
 You can also send telemetry messages from a device by using AMQP. The device can optionally provide a dictionary of application properties, or various message properties, such as message ID.
 
+To route messages based on message body, you must set the `content_type` property to be `application/json;charset=utf-8`.  To learn more about routing messages either based on message properties or message body, please see the [IoT Hub message routing query syntax documentation](iot-hub-devguide-routing-query-syntax.md).
+
 The following code snippet uses the [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python) to send device-to-cloud messages from a device.
 
 ```python
@@ -331,7 +333,7 @@ msg_props = uamqp.message.MessageProperties()
 msg_props.message_id = str(uuid.uuid4())
 msg_props.creation_time = None
 msg_props.correlation_id = None
-msg_props.content_type = None
+msg_props.content_type = 'application/json;charset=utf-8'
 msg_props.reply_to_group_id = None
 msg_props.subject = None
 msg_props.user_id = None

articles/iot-hub/iot-hub-devguide-messages-construct.md

@@ -5,14 +5,14 @@ author: ash2017
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 11/19/2021
+ms.date: 2/7/2022
 ms.author: asrastog
 ms.custom: ['Role: Cloud Development', 'Role: IoT Device']
 ---
 
 # 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](iot-hub-devguide-messages-d2c.md) and [cloud-to-device](iot-hub-devguide-messages-c2d.md) messages. 
+To support seamless interoperability across protocols, IoT Hub defines a common set of messaging features that are available in all device-facing protocols. These can be used in both [device-to-cloud message routing](iot-hub-devguide-messages-d2c.md) and [cloud-to-device messages](iot-hub-devguide-messages-c2d.md). 
 
 [!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-partial.md)]
 
@@ -24,7 +24,9 @@ An IoT Hub message consists of:
 
 * 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.
+* A message body, which can be any type of data.
+
+Each device protocol implements setting properties in different ways.  Please see the related [MQTT](./iot-hub-mqtt-support.md) and [AMQP](./iot-hub-amqp-support.md) developer guides for details.
 
 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.
 
@@ -42,6 +44,22 @@ Device-to-cloud messaging with IoT Hub has the following characteristics:
 
 For more information about how to encode and decode messages sent using different protocols, see [Azure IoT SDKs](iot-hub-devguide-sdks.md).
 
+> [!NOTE]
+> Each IoT Hub protocol provides a message content type property which is respected when routing data to custom endpoints.  To have your data properly handled at the destination (for example, JSON being treated as a parsable string instead of Base64 encoded binary data), you must provide the appropriate content type and charset for the message.
+>
+
+To use your message body in an IoT Hub routing query you must provide a valid JSON object for the message and set the content type property of the message to `application/json;charset=utf-8`.
+
+A valid, routable message body may look like the following:
+
+```json
+{
+    "timestamp": "2022-02-08T20:10:46Z",
+    "tag_name": "spindle_speed",
+    "tag_value": 100
+}
+```
+
 ## System Properties of **D2C** IoT Hub messages
 
 | Property | Description  |User Settable?|Keyword for </br>routing query|