Создание маршрутов событий и фильтров в Azure Digital Twins

2025-04-23

В этой статье описывается процесс создания маршрутов событий с помощью портала Azure, azure CLI az dt route commands, API плоскости событий и пакета SDK для .NET (C#).

Маршрутизация уведомлений о событиях из Azure Digital Twins в подчиненные службы или подключенные вычислительные ресурсы — это двухэтапный процесс: создание конечных точек, а затем создание маршрутов событий для отправки данных в эти конечные точки. В этой статье рассматривается второй шаг, настройка маршрутов для управления тем, какие события доставляются конечным точкам Azure Digital Twin. Чтобы продолжить работу с этой статьей, конечные точки должны быть уже созданы.

Предварительные условия

Вам нужна учетная запись Azure, которую можно настроить бесплатно.
Вам нужен экземпляр Azure Digital Twins в подписке Azure. Если у вас еще нет экземпляра, его можно создать, выполнив действия, описанные в разделе "Настройка экземпляра и проверка подлинности". Держите под рукой следующие значения, использованные в процессе настройки, — они понадобятся далее в статье.
- Имя экземпляра
- Группа ресурсов
Эти сведения можно найти на портале Azure после настройки экземпляра.
Создайте конечную точку с помощью инструкций в статье "Создание конечных точек". В этой статье вы создадите маршрут для отправки данных в эту конечную точку.

Затем выполните следующие инструкции, если вы планируете использовать Azure CLI при выполнении этого руководства.

Подготовка среды к работе с Azure CLI

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".
Если вы предпочитаете локально запускать справочные команды CLI, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье о запуске Azure CLI в контейнере Docker.
- Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login . Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".
- Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье "Использование расширений и управление ими" с помощью Azure CLI.
- Запустите az version , чтобы найти установленные версии и зависимые библиотеки. Чтобы обновить до последней версии, выполните az upgrade.

Создание маршрута событий

После создания конечной точки необходимо определить маршрут событий для фактической отправки данных в конечную точку. Эти маршруты позволяют разработчикам подключать поток событий во всей системе и в подчиненных службах. Один маршрут позволяет выбрать несколько уведомлений и типов событий. Дополнительные сведения о маршрутах событий см. в статье "Маршрутизация событий Azure Digital Twins".

Примечание.

Прежде чем перейти к созданию маршрута, необходимо создать хотя бы одну конечную точку, как описано в предварительных требованиях .

Если вы только недавно развернули конечные точки, убедитесь, что их развертывание завершено, перед тем как пытаться использовать их для нового маршрута событий. Если развертывание маршрута завершается сбоем из-за неготовности конечных точек, подождите несколько минут и повторите попытку.

Если вы работаете над написанием скрипта для этого потока, вам следует учесть развертывание, добавив 2–3 минуты времени ожидания, чтобы конечный сервис успел завершить развертывание, прежде чем переходить к настройке маршрута.

Определение маршрута может содержать следующие элементы.

Имя маршрута, которое вы хотите использовать
Имя конечной точки, которое вы хотите использовать
Фильтр, определяющий, какие события отправляются в конечную точку
- Чтобы отключить маршрут таким образом, чтобы события не отправлялись, используйте значение фильтра false
- Чтобы включить маршрут без какой-либо специальной фильтрации, используйте значение фильтра true
- Дополнительные сведения о любом другом типе фильтра см. в разделе "События фильтра "

Если имя маршрута отсутствует, сообщения не направляются за пределами Azure Digital Twins. Если есть имя маршрута и фильтр true, все сообщения направляются в конечную точку. Если добавлено имя маршрута и другой фильтр, сообщения фильтруются на основе фильтра.

Маршруты событий можно создавать с помощью портала Azure, API плоскости событий или команд az dt route CLI. Далее в этом разделе рассматривается процесс создания.

Чтобы создать маршрут событий, перейдите на страницу сведений для экземпляра Azure Digital Twins на портале Azure. Вы можете найти экземпляр, введя его имя в строку поиска портала.

В меню экземпляра выберите пункт Маршруты событий. Затем на следующей странице маршрутов событий нажмите кнопку +Создать маршрут событий.

На открывающейся странице "Создание маршрута события " выберите по крайней мере:

Имя маршрута в поле "Имя"
Конечная точка, которую вы хотите использовать для создания маршрута

Чтобы маршрут был включен, необходимо также добавить фильтр маршрутов событий по крайней мере true. (При выходе из значения false по умолчанию создается маршрут, но в него не отправляются события.) Для этого переключите переключатель для расширенного редактора , чтобы включить его, и напишите true в поле фильтра .

По завершении нажмите кнопку "Сохранить ", чтобы создать маршрут событий.

В этом разделе показано, как создать маршрут событий с помощью пакета SDK для .NET (C#).

CreateOrReplaceEventRouteAsync — это вызов пакета SDK, который используется для добавления маршрута событий. Ниже приведен пример использования:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Совет

Все функции пакета SDK имеют синхронные и асинхронные версии.

Пример кода пакета SDK для маршрута событий

В следующем примере метода показано, как создать, перечислить и удалить маршрут событий с помощью пакета SDK для .NET:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Отфильтровать события

Как описано ранее, маршруты имеют поле фильтра. Если значение фильтра в маршруте равно false, события не отправляются в конечную точку.

После включения минимального фильтра trueконечные точки получат различные типы событий из Azure Digital Twins:

Телеметрия, активируемая цифровыми двойниками с помощью API службы Azure Digital Twins
Уведомления об изменении свойств двойников, срабатывающие при изменении свойств для любого двойника в экземпляре Azure Digital Twins.
События жизненного цикла, срабатывающие при создании либо удалении двойников или связей.

Чтобы ограничить типы отправляемых событий, определите более конкретный фильтр.

Примечание.

Фильтры чувствительны к регистру и должны точно совпадать с регистром полезных данных. Для фильтров телеметрии регистр символов в фильтре должен совпадать с регистром символов в телеметрии, отправленной устройством.

Портал
API

Чтобы добавить фильтр событий при создании маршрута событий, используйте раздел "Добавление фильтра маршрутов событий" страницы "Создание маршрута события ".

Можно выбрать один из базовых фильтров или использовать расширенные фильтры для создания собственных настраиваемых фильтров.

Использование базовых фильтров

Чтобы использовать основные фильтры, разверните параметр "Типы событий " и установите флажки, соответствующие событиям, которые нужно отправить в конечную точку.

При этом автоматически заполняется текстовое поле фильтра с текстом выбранного фильтра:

Использование расширенных фильтров

Вы также можете использовать параметр расширенного фильтра для записи собственных пользовательских фильтров.

Чтобы создать маршрут событий с расширенными параметрами фильтра, переключите переключатель для расширенного редактора , чтобы включить его. Затем можно написать собственные фильтры событий в поле фильтра :

Вы можете использовать API плоскости данных маршрутов событий для записи пользовательских фильтров. Чтобы добавить фильтр, можно использовать PUT-запрос в https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 со следующим телом:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Поддерживаемые фильтры маршрутов

Ниже перечислены поддерживаемые фильтры маршрутов.

Имя фильтра	Описание	Схема текста фильтра	Поддерживаемые значения
Истина / Ложь	Позволяет создать маршрут без фильтрации или отключить маршрут, чтобы события не отправлялись.	`<true/false>`	`true` = маршрут включен без фильтрации `false` = маршрут отключен
Тип	Тип события, передаваемого через ваш экземпляр цифрового двойника	`type = '<event-type>'`	Ниже приведены возможные значения типов событий: `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`
Источник	Имя экземпляра Azure Digital Twins	`source = '<host-name>'`	Ниже приведены возможные значения имени узла: Для уведомлений: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Для телеметрии: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Тема	Описание события в контексте источника события	`subject = '<subject>'`	Ниже приведены возможные значения тем: Для уведомлений: тема `<twin-ID>` или формат URI для тем, которые уникально идентифицируются несколькими частями либо идентификаторами: `<twin-ID>/relationships/<relationship-ID>` Для телеметрии: объект — это путь компонента (если данные телеметрии передаются из компонента двойника), например `comp1.comp2`. Если данные телеметрии не передаются из компонента, поле темы пусто.
Схема данных	Идентификатор модели DTDL	`dataschema = '<model-dtmi-ID>'`	Для телеметрии: схема данных — это идентификатор модели двойника или компонента, генерирующего данные телеметрии. Например: `dtmi:example:com:floor4;2` Для уведомлений (создание и удаление): схему данных можно получить в тексте уведомления `$body.$metadata.$model`. Для уведомлений (обновление): схема данных доступна в теле уведомления `$body.modelId`
Тип контента	Тип содержимого значения данных	`datacontenttype = '<content-type>'`	Тип контента — `application/json`.
Версия спецификации	Версия схемы событий, которую вы используете	`specversion = '<version>'`	Версия должна быть `1.0`. Это значение указывает схему CloudEvents версии 1.0
Содержимое уведомления	Ссылка на любое свойство в поле `data` уведомления	`$body.<property>`	Примеры уведомлений см. в уведомлениях о событиях . На любое свойство в поле `data` можно ссылаться с помощью `$body`

Примечание.

В настоящее время служба Azure Digital Twins не поддерживает фильтрацию событий на основе полей в массиве. Это ограничение включает фильтрацию по свойствам в patch разделе уведомления об изменении цифрового двойника.

Следующие типы данных поддерживаются в качестве значений, возвращаемых ссылками на предыдущие данные:

Тип данных	Пример
Строка	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Целое число	`$body.errorCode > 200`
Двойной	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Недействительный	`$body.prop != null`

При определении фильтров маршрутов поддерживаются следующие операторы:

Семья	Операторы	Пример
Логичный	И, ИЛИ, ( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
Сравнение	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

При определении фильтров маршрутов поддерживаются следующие функции:

Функция	Описание	Пример
НАЧИНАЕТСЯ_С(x, y)	Возвращает значение true, если значение `x` начинается со строки `y`.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ЗАКАНЧИВАЕТСЯ_НА(x,y)	Возвращает значение true, если значение `x` оканчивается строкой `y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTAINS(x,y)	Возвращает значение true, если значение `x` содержит строку `y`.	`CONTAINS(subject, '<twin-ID>')`

При реализации или обновлении фильтра изменение может занять несколько минут, чтобы отразиться в конвейере данных.

Мониторинг маршрутов событий

Метрики маршрутизации, такие как количество, задержка и частота сбоев, можно просмотреть на портале Azure.

Сведения о просмотрах и управлении метриками с помощью Azure Monitor см. Анализ метрик с помощью инструмента Azure Monitor metrics explorer. Полный список метрик маршрутизации, доступных для Azure Digital Twins, см. в разделе "Метрики маршрутизации".

Следующие шаги

Ознакомьтесь со сведениями о различных типах сообщений о событиях, которые можно получить:

Уведомления о событиях

Поделиться через

Создание маршрутов событий и фильтров в Azure Digital Twins

Предварительные условия

Подготовка среды к работе с Azure CLI

Создание маршрута событий

Отфильтровать события

Использование базовых фильтров

Использование расширенных фильтров

Поддерживаемые фильтры маршрутов

Мониторинг маршрутов событий

Следующие шаги

Обратная связь

Дополнительные ресурсы