Skip to content
IoT Service

Message routing

Message routing helps in sending device messages to various endpoints.

AWS Rules

Rules can be used to capture the messages sent to a topic, parse and send the messages to various delivery endpoints.

Topics in the rule are created by appending the groupId to the topicSuffix, {groupId}/{topicSuffix}.

Allowed topicSuffix patterns:

  • {groupId}/#
  • {groupId}/+
  • {groupId}/gps
  • {groupId}/gps/+ (or) {groupId}/gps/#

# - Indicates several sub-topics

+ - indicates single topic

Wildcard CharacterMatchesDescription
#All strings at and below its level in the topic hierarchy.Must be the last character in the topic filter. Must be the only character in its level of the topic hierarchy. Can be used in a topic filter that also contains the + wildcard character.
+Any string in the level that contains the character.Must be the only character in its level of the topic hierarchy.Can be used in multiple levels of a topic filter.

Examples for wildcards

  • {groupId}/# captures messages published to {groupId}/gps, {groupId}/command, {groupId}/command/alert, but not messages published to {groupId}.
  • {groupId}/+/command captures messages published to {groupId}/alert/command and {groupId}/gps/command.

A topic in a publish or subscribe request can have no more than 7 forward slashes (/).

Delivery Endpoints

Supported Endpoints

  • AWS SQS (URL format:https://sqs.us.amazonaws.com//iot-{groupId}-{ruleName})
  • Topics (Topic format: iot-telemetry-{groupId}-{ruleName})
  • Data Ocean

The delivery endpoint will be created based on the group’s delivery endpoint.

Message Parsing

  • Messages can be encoded to base64 format.

Limitations

Maximum number of rules created per group - 5.

Azure Routes

Routes serve the purpose of capturing inbound messages and subsequently forwarding them to delivery endpoints. Before routing to endpoints, messages could be filtered based on their body content or specific properties.

Delivery Endpoints

Supported Endpoints

  • EventHub Endpoint (URL Format: Endpoint=sb://{EventHubName}.servicebus.windows.net/;EntityPath=iot-{groupId}-{routeName})
  • Data Ocean

Limitations

Maximum number of routes allowed per group - 5

Filtering

The following is an example of a message and how it could be filtered:

{
  "message": {
    "systemProperties": {
      "contentType": "application/json",
      "contentEncoding": "UTF-8"
    },
    "appProperties": {
      "processingPath": "cold",
      "messageName": "temperature"
    },
    "body": {
       "Weather": {
            "Temperature": 50,
            "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            }]}
     }
  }
}

Query condition based on message body

$body.Weather.HistoricalData[0].Month = 'Feb'

The following system property ($.ct=application%2Fjson&$.ce=utf-8) should be added in inbound message in order to route the messages based on the message body to event hubs. The messages will not be delivered if the system property is not added.

Query condition based on system properties

$contentType = 'application/json'

For more information on system properties, refer to Azure system properties.

Query condition based on application properties

messageName = ‘temperature’