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

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

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

Необходимые компоненты

• Вам потребуется учетная запись Azure, которую можно настроить бесплатно.

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

  • Имя экземпляра
  • Группа ресурсов

  Эти сведения можно найти на портале Azure после настройки экземпляра.

  

• Создайте конечную точку с помощью инструкций в статье "Создание конечных точек". В этой статье вы создадите маршрут для отправки данных в эту конечную точку.

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

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

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  

• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

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

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

Примечание.

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

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

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

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

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

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

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

Портал

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

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

Откроется страница Создание маршрута события. Выберите на этой странице по крайней мере следующие параметры.

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

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

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

CLI

Маршрутами можно управлять с помощью команд az dt route для интерфейса командной строки Azure Digital Twins.

Дополнительные сведения об использовании интерфейса командной строки и доступных командах см. в статье о наборе команд командной строки Azure Digital Twins.

Пакет SDK для .NET

В этом разделе объясняется, как создать маршрут события с помощью пакета 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 для C#.

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

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

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

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

Имя фильтра	Description	Схема текста фильтра	Поддерживаемые значения
True / False	Позволяет создать маршрут без фильтрации или отключить маршрут, чтобы события не отправлялись.	<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
Content type	Тип контента значения данных	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
Null	$body.prop != null

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

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

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

Function	Description	Пример
STARTS_WITH(x,y)	Возвращает значение true, если значение x начинается со строки y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(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 Digital Twins, см. в разделе метрики маршрутизации Azure Digital Twins.

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

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

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