iot-central-data-export-message-properties.md

title	include file
description	include file
services	iot-central
author	dominicbetts
ms.service	azure-iot-central
ms.topic	include
ms.date	04/25/2025
ms.author	dobett
ms.custom	include file

Message properties

Telemetry messages have properties for metadata and the telemetry payload. The previous snippet shows examples of system messages such as deviceId and enqueuedTime. To learn more about the system message properties, see System properties of device-to-cloud messages.

You can add properties to telemetry messages if you need to add custom metadata to your telemetry messages. For example, you need to add a timestamp when the device creates the message.

The following code snippet shows how to add the iothub-creation-time-utc property to the message when you create it on the device:

Important

The format of this timestamp must be UTC with no timezone information. For example, 2021-04-21T11:30:16Z is valid, while 2021-04-21T11:30:16-07:00 is invalid.

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

---

Property changes format

Each message or record represents changes to device and cloud properties. Information in the exported message includes:

• applicationId: The ID of the IoT Central application.
• messageSource: The source for the message - properties.
• messageType: Either cloudPropertyChange, devicePropertyDesiredChange, or devicePropertyReportedChange.
• deviceId: The ID of the device that sent the telemetry message.
• schema: The name and version of the payload schema.
• enqueuedTime: The time at which IoT Central detected this change.
• templateId: The ID of the device template assigned to the device.
• properties: An array of properties that changed, including the names of the properties and values that changed. The component and module information is included if the property is modeled within a component or an IoT Edge module.
• enrichments: Any enrichments set up on the export.