| title | titleSuffix | description | author | ms.author | ms.date | ms.topic | ms.service |
|---|---|---|---|---|---|---|---|
Manage endpoints and routes (portal) |
Azure Digital Twins |
See how to set up and manage endpoints and event routes for Azure Digital Twins data using the Azure portal. |
baanders |
baanders |
7/22/2020 |
how-to |
digital-twins |
[!INCLUDE digital-twins-route-selector.md]
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.
Alternatively, you can also manage endpoints and routes with the Event Routes APIs, the SDKs, or the Azure Digital Twins CLI. For a version of this article that uses these mechanisms instead of the portal, see How-to: Manage endpoints and routes (APIs and CLI).
- You'll need an Azure account (you can set one up for free here)
- 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 How-to: 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.
:::image type="content" source="media/how-to-manage-routes-portal/search-field-portal.png" alt-text="Screenshot of Azure portal search bar.":::
Select your instance from the results to see the details page for your instance:
:::image type="content" source="media/how-to-manage-routes-portal/instance-details.png" alt-text="Screenshot of ADT instance details." border="false":::
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.
To link an endpoint to Azure Digital Twins, the event grid topic, event hub, or Service Bus that you're using for the endpoint needs to exist already.
Prerequisite: Create an event grid topic by following the steps in the Create a custom topic section of the Event Grid Custom events quickstart.
Once you have created the topic, you can link it to Azure Digital Twins from your Azure Digital Twins instance's page in the Azure portal (you can find the instance by entering its name into the portal search bar).
From the instance menu, select Endpoints. Then from the Endpoints page that follows, select + Create an endpoint.
On the Create an Endpoint page that opens up, you can create an endpoint of type Event Grid by selecting the corresponding radio button. Complete the other details: enter a name for your endpoint in the Name field, choose your Subscription from the dropdown, and choose your pre-created Event Grid Topic from the third dropdown.
Then, create your endpoint by hitting Save.
:::image type="content" source="media/how-to-manage-routes-portal/create-endpoint-event-grid.png" alt-text="Screenshot of creating an endpoint of type Event Grid.":::
You can verify that the endpoint is successfully created by checking the notification icon in the top Azure portal bar:
:::image type="content" source="media/how-to-manage-routes-portal/create-endpoint-notifications.png" alt-text="Screenshot of notification to verify the creation of endpoint." border="false":::
You can also view the endpoint that was created back on the Endpoints page for your Azure Digital Twins instance.
If the endpoint creation fails, observe the error message and retry after a few minutes.
Now, the event grid topic is available as an endpoint inside of Azure Digital Twins, under the name specified in the Name field. You will typically use that name as the target of an event route, which you'll create later in this article.
Prerequisites:
- You'll need an Event Hubs namespace and an event hub. Create both of these by following the steps in the Event Hubs Create an event hub quickstart.
- You'll need an authorization rule. To create this, refer to the Event Hubs Authorizing access to Event Hubs resources using Shared Access Signatures article.
Go to the details page for your Azure Digital Twins instance in the Azure portal (you can find it by entering its name into the portal search bar).
From the instance menu, select Endpoints. Then from the Endpoints page that follows, select + Create an endpoint.
On the Create an Endpoint page that opens up, you can create an endpoint of type Event Hub by selecting the corresponding radio button. Enter a name for your endpoint in the Name field. Then select your Subscription, and your pre-created Event hub namespace, Event Hub, and Authorization rule from the respective dropdowns.
Then, create your endpoint by hitting Save.
:::image type="content" source="media/how-to-manage-routes-portal/create-endpoint-event-hub.png" alt-text="Screenshot of creating an endpoint of type Event Hubs.":::
You can verify that the endpoint is successfully created by checking the notification icon in the top Azure portal bar.
If the endpoint creation fails, observe the error message and retry after a few minutes.
Now, the Event hub is available as an endpoint inside of Azure Digital Twins, under the name specified in the Name field. You will typically use that name as the target of an event route, which you'll create later in this article.
Prerequisites:
- You'll need a Service Bus namespace and a Service Bus topic. Create both of these by following the steps in the Service Bus Create topics and subscriptions quickstart. You do not need to complete the Create subscriptions to the topic section.
- You'll need an Authorization rule. To create this, refer to the Service Bus Authentication and authorization article.
Go to the details page for your Azure Digital Twins instance in the Azure portal (you can find it by entering its name into the portal search bar).
From the instance menu, select Endpoints. Then from the Endpoints page that follows, select + Create an endpoint.
On the Create an Endpoint page that opens up, you can create an endpoint of type Service Bus by selecting the corresponding radio button. Enter a name for your endpoint in the Name field. Then select your Subscription, and your pre-created Service Bus namespace, Service Bus topic, and Authorization rule from the respective dropdowns.
Then, create your endpoint by hitting Save.
:::image type="content" source="media/how-to-manage-routes-portal/create-endpoint-service-bus.png" alt-text="Screenshot of creating an endpoint of type Service Bus.":::
You can verify that the endpoint is successfully created by checking the notification icon in the top Azure portal bar.
If the endpoint creation fails, observe the error message and retry after a few minutes.
Now, the Service Bus topic is available as an endpoint inside of Azure Digital Twins, under the name specified in the Name field. You will typically use that name as the target of an event route, which you'll create later in this article.
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.
In order to create an endpoint with dead-lettering enabled, you must use the ARM APIs to create your endpoint, rather than the Azure portal.
For instructions on how to do this with the APIs, see the APIs and CLI version of this article.
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. Read more about event routes in Concepts: 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 you're unable to set up the route because the endpoints aren't ready, wait a few minutes and try again.
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.
- To disable the route so that no events are sent, use a filter value of
A single route can allow multiple notifications and event types to be selected.
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 would like 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.
:::image type="content" source="media/how-to-manage-routes-portal/create-event-route-no-filter.png" alt-text="Screenshot of creating event route for your instance." lightbox="media/how-to-manage-routes-portal/create-event-route-no-filter.png":::
When finished, hit 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 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.
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.
:::row::: :::column::: :::image type="content" source="media/how-to-manage-routes-portal/create-event-route-filter-basic-1.png" alt-text="Screenshot of creating an event route with a basic filter. Selecting the checkboxes of the events."::: :::column-end::: :::column::: :::column-end::: :::row-end:::
This will auto-populate the filter text box with the text of the filter you've selected:
:::row::: :::column::: :::image type="content" source="media/how-to-manage-routes-portal/create-event-route-filter-basic-2.png" alt-text="Screenshot of creating an event route with a basic filter. Showing the auto-populated filter text after selecting the events."::: :::column-end::: :::column::: :::column-end::: :::row-end:::
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:
:::row::: :::column::: :::image type="content" source="media/how-to-manage-routes-portal/create-event-route-filter-advanced.png" alt-text="Screenshot of creating an event route with an advanced filter."::: :::column-end::: :::column::: :::column-end::: :::row-end:::
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.
[!INCLUDE digital-twins-route-filters]
[!INCLUDE digital-twins-route-metrics]
Read about the different types of event messages you can receive: