Previous

Next

Examine Azure Digital Twins service configuration

Completed

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.

Note

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.

Note

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.

Note

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.

Note

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.

Endpoint type

Required resources

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.

Note

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.

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 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.

Basic 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.

Advanced filters

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 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 = '<eventType>'

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 = '<hostname>'

Here are the possible hostname values: For notifications: <yourDigitalTwinInstance>.api.<yourRegion>.digitaltwins.azure.net For telemetry: <yourDigitalTwinInstance>.api.<yourRegion>.digitaltwins.azure.net/<twinId>

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 <twinid> or a URI format for subjects, which are uniquely identified by multiple parts or IDs: <twinid>/relationships/<relationshipid> 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 = '<contentType>'

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>

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, '<twinID>')

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, '<twinID>')

Note

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

Continue