Manage endpoints and routes in Azure Digital Twins

In Azure Digital Twins, you can route event notifications to downstream services or connected compute resources. This is done by first setting up endpoints that can receive the events. You can then create event routes that specify which events generated by Azure Digital Twins are delivered to which endpoints.

This article walks you through the process of creating endpoints and routes using the Azure portal, the REST APIs, the .NET (C#) SDK, and the Azure Digital Twins CLI.

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. Log into the portal and search for the name of your instance in the portal search bar.

Screenshot of Azure portal search bar.

Select your instance from the results to see these details in the Overview for your instance:

Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The name and resource group are highlighted.

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.

    Launch Cloud Shell in a new window

  • If you prefer, install the Azure CLI to run CLI reference commands.

    • 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 additional sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install Azure CLI extensions 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 endpoint for Azure Digital Twins

These are the supported types of endpoints that you can create for your instance:

For more information on the different endpoint types, see Choose between Azure messaging services.

This section explains how to create an endpoint using the Azure portal or the Azure CLI. You can also manage endpoints with the DigitalTwinsEndpoint control plane APIs.

Prerequisite: Create endpoint resources

To link an endpoint to Azure Digital Twins, the event grid topic, event hub, or Service Bus topic that you're using for the endpoint needs to exist already.

Use the following chart to see what resources should be set up before creating your endpoint.

Endpoint type Required resources (linked to creation instructions)
Event Grid endpoint event grid topic
Event Hubs endpoint Event Hubs namespace

event hub

(Optional) authorization rule for key-based authentication
Service Bus endpoint Service Bus namespace

Service Bus topic

(Optional) authorization rule for key-based authentication

Create the endpoint

Once you have created the endpoint resources, you can use them for an Azure Digital Twins endpoint.

To create a new endpoint, go to your instance's page in the Azure portal (you can find the instance by entering its name into the portal search bar).

  1. From the instance menu, select Endpoints. Then from the Endpoints page that follows, select + Create an endpoint. This will open the Create an endpoint page, where you'll fill in the fields in the following steps.

    Screenshot of creating an endpoint of type Event Grid in the Azure portal.

  2. Enter a Name for your endpoint and choose the Endpoint type.

  3. Complete the other details that are required for your endpoint type, including your subscription and the endpoint resources described above.

    1. For Event Hub and Service Bus endpoints only, you must select an Authentication type. You can use key-based authentication with a pre-created authorization rule, or identity-based authentication if you'll be using the endpoint with a managed identity for your Azure Digital Twins instance.
  4. Finish creating your endpoint by selecting Save.

Important

In order to successfully use identity-based authentication for your endpoint, you'll need to create a managed identity for your instance by following the steps in Route events with a managed identity.

After creating your endpoint, you can verify that the endpoint was successfully created by checking the notification icon in the top Azure portal bar:

Screenshot of the notification to verify the creation of an endpoint in the Azure portal.

If the endpoint creation fails, observe the error message and retry after a few minutes.

You can also view the endpoint that was created back on the Endpoints page for your Azure Digital Twins instance.

Now the event grid, event hub, or Service Bus topic is available as an endpoint inside of Azure Digital Twins, under the name you chose for the endpoint. You'll typically use that name as the target of an event route, which you'll create later in this article.

Create an endpoint with dead-lettering

When an endpoint can't deliver an event within a certain time period or after trying to deliver the event a certain number of times, it can send the undelivered event to a storage account. This process is known as dead-lettering.

You can set up the necessary storage resources using the Azure portal or the Azure Digital Twins CLI. However, to create an endpoint with dead-lettering enabled, you'll need use the Azure Digital Twins CLI or control plane APIs.

To learn more about dead-lettering, see Event routes. For instructions on how to set up an endpoint with dead-lettering, continue through the rest of this section.

Set up storage resources

Before setting the dead-letter location, you must have a storage account with a container set up in your Azure account.

You'll provide the URI for this container when creating the endpoint later. The dead-letter location will be provided to the endpoint as a container URI with a SAS token. That token needs write permission for the destination container within the storage account. The fully formed dead letter SAS URI will be in the format of: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Follow the steps below to set up these storage resources in your Azure account, to prepare to set up the endpoint connection in the next section.

  1. Follow the steps in Create a storage account to create a storage account in your Azure subscription. Make a note of the storage account name to use it later.
  2. Follow the steps in Create a container to create a container within the new storage account. Make a note of the container name to use it later.
Create a SAS token

Next, create a SAS token for your storage account that the endpoint can use to access it.

  1. Start by navigating to your storage account in the Azure portal (you can find it by name with the portal search bar).

  2. In the storage account page, choose the Shared access signature link in the left navigation bar to start setting up the SAS token.

    Screenshot of the storage account page in the Azure portal.

  3. On the Shared access signature page, under Allowed services and Allowed resource types, select whatever settings you want. You'll need to select at least one box in each category. Under Allowed permissions, choose Write (you can also select other permissions if you want).

  4. Set whatever values you want for the remaining settings.

  5. When you're finished, select the Generate SAS and connection string button to generate the SAS token.

    Screenshot of the storage account page in the Azure portal showing all the setting selection to generate a SAS token.

  6. This will generate several SAS and connection string values at the bottom of the same page, underneath the setting selections. Scroll down to view the values, and use the Copy to clipboard icon to copy the SAS token value. Save it to use later.

    Screenshot of the storage account page in the Azure portal highlighting how to copy the SAS token to use in the dead-letter secret.

Create the dead-letter endpoint

In order to create an endpoint with dead-lettering enabled, you must use the CLI commands or control plane APIs to create your endpoint, rather than the Azure portal.

For instructions on how to do this with the Azure CLI, switch to the CLI tab for this section.

Message storage schema

Once the endpoint with dead-lettering is set up, dead-lettered messages will be stored in the following format in your storage account:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Dead-lettered messages will match the schema of the original event that was intended to be delivered to your original endpoint.

Here is an example of a dead-letter message for a twin create notification:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Create an event route

To actually send data from Azure Digital Twins to an endpoint, you'll need to define an event route. 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 Routing Azure Digital Twins events.

Prerequisite: You need to create endpoints as described earlier in this article before you can move on to creating a route. You can proceed to creating an event route once your endpoints are finished setting up.

Note

If you have 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 is no route name, no messages are routed outside of Azure Digital Twins. If there is a route name and the filter is true, all messages are routed to the endpoint. If there is 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.

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 this, toggle the switch for the Advanced editor to enable it, and write true in the Filter box.

Screenshot of creating an event route for your instance in the Azure portal.

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

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 enabling the minimal filter of true, endpoints will receive a variety 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, not necessarily the casing defined in the twin's model.

To add an event filter while you are 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.

Screenshot of creating an event route with a basic filter in the Azure portal, highlighting the checkboxes of the events.

This will auto-populate the filter text box with the text of the filter you've selected:

Screenshot of creating an event route with a basic filter in the Azure portal, highlighting the auto-populated filter text after selecting the events.

Use the advanced filters

Alternatively, you can 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:

Screenshot of creating an event route with an advanced filter in the Azure portal.

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 is not 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 are using specversion = '<version>' The version must be 1.0. This 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

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.

From the portal homepage, search for your Azure Digital Twins instance to pull up its details. Select the Metrics option from the Azure Digital Twins instance's navigation menu on the left to bring up the Metrics page.

Screenshot showing the metrics page for Azure Digital Twins.

From here, you can view the metrics for your instance and create custom views.

For more on viewing Azure Digital Twins metrics, see View metrics with Azure Monitor.

Next steps

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