Create event routes and filters in Azure Digital Twins
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.
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
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.
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.
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
- To enable a route that has no specific filtering, use a filter value of
- For details on any other type of filter, see the Filter events section below
- To disable the route so that no events are sent, use a filter value of
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.
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.
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.
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, not necessarily the casing defined in the twin's model.
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:
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||
|Type||The type of event flowing through your digital twin instance||
||Here are the possible event type values:
|Source||Name of Azure Digital Twins instance||
||Here are the possible host name values:
|Subject||A description of the event in the context of the event source above||
||Here are the possible subject values:
For notifications: The subject is
or a URI format for subjects, which are uniquely identified by multiple parts or IDs:
For telemetry: The subject is the component path (if the telemetry is emitted from a twin component), such as
|Data schema||DTDL model ID||
||For telemetry: The data schema is the model ID of the twin or the component that emits the telemetry. For example,
For notifications (create/delete): Data schema can be accessed in the notification body at
For notifications (update): Data schema can be accessed in the notification body at
|Content type||Content type of data value||
||The content type is
|Spec version||The version of the event schema you're using||
||The version must be
|Notification body||Reference any property in the
||See Event notifications for examples of notifications. Any property in the
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:
The following operators are supported when defining route filters:
|Logical||AND, OR, ( )||
|Comparison||<, <=, >, >=, =, !=||
The following functions are supported when defining route filters:
|STARTS_WITH(x,y)||Returns true if the value
|ENDS_WITH(x,y)||Returns true if the value
|CONTAINS(x,y)||Returns true if the value
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.
Read about the different types of event messages you can receive: