Create event routes and filters in Azure Digital Twins

This article walks you through the process of creating event routes using the Azure portal, Azure CLI az dt route commands, Event Routes data plane APIs, and the .NET (C#) SDK.

Routing event notifications from Azure Digital Twins to downstream services or connected compute resources is a two-step process: create endpoints, then create event routes to send data to those endpoints. This article covers the second step, setting up routes to control which events are delivered to which Azure Digital Twin endpoints. To proceed with this article, you should have endpoints already created.

Prerequisites

• You'll need an Azure account, which can be set up for free

• You'll need an Azure Digital Twins instance in your Azure subscription. If you don't have an instance already, you can create one using the steps in Set up an instance and authentication. Have the following values from setup handy to use later in this article:

  • Instance name
  • Resource group

  You can find these details in the Azure portal after setting up your instance.

  

• Create an endpoint using the instructions in Create endpoints. In this article, you'll create a route to send data to that endpoint.

Next, follow the instructions below if you intend to use the Azure CLI while following this guide.

Prepare your environment for the Azure CLI

• Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Create an event route

After creating an endpoint, you'll need to define an event route to actually send data to the endpoint. These routes let developers wire up event flow, throughout the system and to downstream services. A single route can allow multiple notifications and event types to be selected. Read more about event routes in Endpoints and event routes.

Note

Make sure you've created at least one endpoint as described in the Prerequisites before you move on to creating a route.

If you've only recently deployed your endpoints, validate that they're finished deploying before attempting to use them for a new event route. If route deployment fails because the endpoints aren't ready, wait a few minutes and try again.

If you are scripting this flow, you may want to account for this by building in 2-3 minutes of wait time for the endpoint service to finish deploying before moving on to route setup.

A route definition can contain these elements:

• The route name you want to use
• The name of the endpoint you want to use
• A filter that defines which events are sent to the endpoint
  • To disable the route so that no events are sent, use a filter value of false
  • To enable a route that has no specific filtering, use a filter value of true
  • For details on any other type of filter, see the Filter events section below

If there's no route name, no messages are routed outside of Azure Digital Twins. If there's a route name and the filter is true, all messages are routed to the endpoint. If there's a route name and a different filter is added, messages will be filtered based on the filter.

Event routes can be created with the Azure portal, EventRoutes data plane APIs, or az dt route CLI commands. The rest of this section walks through the creation process.

Portal

To create an event route, go to the details page for your Azure Digital Twins instance in the Azure portal (you can find the instance by entering its name into the portal search bar).

From the instance menu, select Event routes. Then from the Event routes page that follows, select + Create an event route.

On the Create an event route page that opens up, choose at minimum:

• A name for your route in the Name field
• The Endpoint you want to use to create the route

For the route to be enabled, you must also Add an event route filter of at least true. (Leaving the default value of false will create the route, but no events will be sent to it.) To do so, toggle the switch for the Advanced editor to enable it, and write true in the Filter box.

When finished, select the Save button to create your event route.

CLI

Routes can be managed using the az dt route commands for the Azure Digital Twins CLI.

For more information about using the CLI and what commands are available, see Azure Digital Twins CLI command set.

.NET SDK

This section shows how to create an event route using the .NET (C#) SDK.

CreateOrReplaceEventRouteAsync is the SDK call that is used to add an event route. Here's an example of its usage:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Tip

All SDK functions come in synchronous and asynchronous versions.

Event route sample SDK code

The following sample method shows how to create, list, and delete an event route with the C# SDK:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Filter events

As described above, routes have a filter field. If the filter value on your route is false, no events will be sent to your endpoint.

After you've enabled a minimal filter of true, endpoints will receive different kinds of events from Azure Digital Twins:

• Telemetry fired by digital twins using the Azure Digital Twins service API
• Twin property change notifications, fired on property changes for any twin in the Azure Digital Twins instance
• Life-cycle events, fired when twins or relationships are created or deleted

You can restrict the types of events being sent by defining a more-specific filter.

Note

Filters are case-sensitive and need to match the payload case. For telemetry filters, this means that the casing needs to match the casing in the telemetry sent by the device.

Portal

To add an event filter while you're creating an event route, use the Add an event route filter section of the Create an event route page.

You can either select from some basic common filter options, or use the advanced filter options to write your own custom filters.

Use the basic filters

To use the basic filters, expand the Event types option and select the checkboxes corresponding to the events you want to send to your endpoint.

Doing so will autopopulate the filter text box with the text of the filter you've selected:

Use the advanced filters

You can also use the advanced filter option to write your own custom filters.

To create an event route with advanced filter options, toggle the switch for the Advanced editor to enable it. You can then write your own event filters in the Filter box:

API

You can use the Event Routes data plane APIs to write custom filters. To add a filter, you can use a PUT request to https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 with the following body:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Supported route filters

Here are the supported route filters.

Filter name	Description	Filter text schema	Supported values
True / False	Allows creating a route with no filtering, or disabling a route so no events are sent	<true/false>	true = route is enabled with no filtering false = route is disabled
Type	The type of event flowing through your digital twin instance	type = '<event-type>'	Here are the possible event type values: Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.Update Microsoft.DigitalTwins.Relationship.Create Microsoft.DigitalTwins.Relationship.Update Microsoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry
Source	Name of Azure Digital Twins instance	source = '<host-name>'	Here are the possible host name values: For notifications: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net For telemetry: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Subject	A description of the event in the context of the event source above	subject = '<subject>'	Here are the possible subject values: For notifications: The subject is <twin-ID> or a URI format for subjects, which are uniquely identified by multiple parts or IDs: <twin-ID>/relationships/<relationship-ID> For telemetry: The subject is the component path (if the telemetry is emitted from a twin component), such as comp1.comp2. If the telemetry isn't emitted from a component, then its subject field is empty.
Data schema	DTDL model ID	dataschema = '<model-dtmi-ID>'	For telemetry: The data schema is the model ID of the twin or the component that emits the telemetry. For example, dtmi:example:com:floor4;2 For notifications (create/delete): Data schema can be accessed in the notification body at $body.$metadata.$model. For notifications (update): Data schema can be accessed in the notification body at $body.modelId
Content type	Content type of data value	datacontenttype = '<content-type>'	The content type is application/json
Spec version	The version of the event schema you're using	specversion = '<version>'	The version must be 1.0. This value indicates the CloudEvents schema version 1.0
Notification body	Reference any property in the data field of a notification	$body.<property>	See Event notifications for examples of notifications. Any property in the data field can be referenced using $body

Note

Azure Digital Twins currently doesn't support filtering events based on fields within an array. This includes filtering on properties within a patch section of a digital twin change notification.

The following data types are supported as values returned by references to the data above:

Data type	Example
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
Integer	$body.errorCode > 200
Double	$body.temperature <= 5.5
Bool	$body.poweredOn = true
Null	$body.prop != null

The following operators are supported when defining route filters:

Family	Operators	Example
Logical	AND, OR, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Comparison	<, <=, >, >=, =, !=	$body.temperature <= 5.5

The following functions are supported when defining route filters:

Function	Description	Example
STARTS_WITH(x,y)	Returns true if the value x starts with the string y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	Returns true if the value x ends with the string y.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	Returns true if the value x contains the string y.	CONTAINS(subject, '<twin-ID>')

When you implement or update a filter, the change may take a few minutes to be reflected in the data pipeline.

Monitor event routes

Routing metrics such as count, latency, and failure rate can be viewed in the Azure portal.

For information about viewing and managing metrics with Azure Monitor, see Get started with metrics explorer. For a full list of routing metrics available for Azure Digital Twins, see Azure Digital Twins routing metrics.

Next steps

Read about the different types of event messages you can receive:

• Event notifications