Examine Azure Digital Twins service configuration
The initial setup for a new Azure Digital Twins instance consists of two parts:
- Create the Azure Digital Twins service instance.
- Set up user access permissions: Azure users will need to have the Azure Digital Twins Data Owner role on the Azure Digital Twins instance to be able to manage the Azure Digital Twins service and its data.
To set up user access permissions in Azure Digital Twins, you will need access to an Azure account that can assign user access permissions for the subscription that you are working in. The account must have role assignments that include the following permissions:
- Create and manage Azure resources.
- Manage user access to Azure resources (including granting and delegating permissions).
Common roles that meet this requirement are Owner, Account admin, or the combination of User Access Administrator and Contributor.
Create the Azure Digital Twins service instance with the Azure portal
Your Azure Digital Twins instance can be created in the Azure portal by using the + Create a resource menu option, and selecting Azure Digital Twins.
When creating your Azure Digital Twins instance, you will need to provide the following:
- Subscription: The Azure subscription that you are using.
- Resource group: A resource group in which to deploy the instance.
- Location: An Azure Digital Twins-enabled region for the deployment.
Azure Digital Twins is not currently available in all regions. For more details on regional support, visit Azure products available by region Azure Digital Twins.
- Resource name: A name for your Azure Digital Twins instance.
This following image shows the Basics tab, which contains the fields required to create the Azure Digital Twins instance.
You can also assign the Azure Digital Twins Owner Role when creating the Azure Digital Twins instance. We examine the user access requirement in more detail in the Set up user access permissions section.
Other resource tabs
The following resource configuration tabs are also available when creating your Azure Digital Twins instance.
- Networking: On this tab, you can enable private endpoints with Azure Private Link to eliminate public network exposure to your instance.
- Advanced: On this tab, you can enable a system-managed identity for your instance that can be used when forwarding events to endpoints.
- Tags: On this tab, you can add tags to your instance to help you organize it among your Azure resources.
Set up user access permissions
Azure Digital Twins uses Azure Active Directory (Azure AD) for role-based access control (RBAC). This means that before a user can make data plane calls to your Azure Digital Twins instance (access the data), that user needs to be assigned a role with appropriate permissions. For Azure Digital Twins, this role is Azure Digital Twins Data Owner.
This role is different from the Azure AD Owner role, which can also be assigned at the scope of the Azure Digital Twins instance. These are two distinct management roles, and Azure AD Owner does not grant access to data plane features that are granted with Azure Digital Twins Data Owner.
With your Azure Digital Twins instance open in the Azure portal, you can use Access control (IAM), to configure role assignments.
The Add role assignment page provides the following fields:
- Role: Select Azure Digital Twins Data Owner from the dropdown menu
- Assign access to: Use User, group or service principal
- Select: Search for the name or email address of the user to assign. When you select the result, the user will show up in a Selected members section.
As noted previously, this page must be completed by a user with sufficient permissions in the Azure subscription.
Configure endpoints and routes
In Azure Digital Twins, you can route event notifications to downstream services or connected compute resources. This routing 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.
You can manage Azure Digital Twins endpoints and routes in the Azure portal, with the Event Routes APIs, the SDKs, or the Azure Digital Twins CLI.
Create an endpoint for Azure Digital Twins
Azure Digital Twins supports the endpoint types listed below. The endpoint must exist before you can link to it.
- Event Grid
- Event Hubs
- Service Bus
Use the following chart to see what resources should be set up before creating your endpoint.
Event Grid endpoint
Event Grid Topic
Event Hubs endpoint
Event Hubs namespace Event Hubs (Optional) authorization rule for key-based authentication
Service Bus endpoint
Service Bus namespace Service Bus topic (Optional) authorization rule for key-based authentication
Once you have created the endpoint resources, you can use them for an Azure Digital Twins endpoint.
To create your endpoint in the Azure portal, open your Azure Digital Twins blade, and then select Endpoints from the left-side menu.
In addition to the name and type of your endpoint, you will also need to specify your subscription and select the endpoint resource.
For Event Hubs and Service Bus endpoints, you must also 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.
Once created, the endpoint 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.
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.
An event route definition contains 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.
A single route can allow multiple notifications and event types to be selected.
To create an event route in the Azure portal, on the left-side menu of your Azure Digital Twins blade, select Event routes, and then, on the Event routes page, select + Create an 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 enabling the minimal filter of true, endpoints will receive various 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.
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.
To use the basic filters, expand the Event types option and select the checkboxes corresponding to the events you'd like to send to your endpoint.
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:
Here are the supported route filters. The detail in the Filter text schema column is the text that can be entered into the filter box.
Filter text schema
True / False
Allows creating a route with no filtering, or disabling a route so no events are sent.
true = route is enabled with no filtering false = route is disabled
The type of event flowing through your digital twin instance.
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
Name of Azure Digital Twins instance.
Here are the possible hostname values:
A description of the event in the context of the event source above.
Here are the possible subject values:
For notifications: The subject is
<twinid> 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 comp1.comp2. If the telemetry is not emitted from a component, then its subject field is empty.
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 of data value.
The content type is application/json
The version of the event schema you are using.
The version must be 1.0. This indicates the CloudEvents schema version 1.0
Reference any property in the data field of a notification.
Any property in the data field can be referenced using
The following data types are supported as values returned by references to the data above:
$body.errorCode > 200
$body.temperature <= 5.5
$body.poweredOn = true
$body.prop != null
The following operators are supported when defining route filters:
AND, OR, ( )
(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
<, <=, >, >=, =, !=
$body.temperature <= 5.5
The following functions are supported when defining route filters:
Returns true if the value x starts with the string y.
Returns true if the value x ends with the string y.
Returns true if the value x contains the string y.
When you implement or update a filter, the change may take a few minutes to be reflected in the data pipeline.