Создание маршрутов событий и фильтров в 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 в поле фильтра .
По завершении нажмите кнопку Сохранить, чтобы создать маршрут событий.
События фильтра
Как упоминалось выше, у маршрутов есть поле Фильтр. Если значение фильтра на маршруте — false, события отправляться в конечную точку не будут.
После включения минимального фильтра trueконечные точки получат различные типы событий из Azure Digital Twins:
- Данные телеметрии, запущенные цифровыми двойниками с помощью API службы Azure Digital Twins
- Уведомления об изменении свойств двойников, срабатывающие при изменении свойств для любого двойника в экземпляре Azure Digital Twins.
- События жизненного цикла, срабатывающие при создании либо удалении двойников или связей.
Чтобы ограничить типы отправляемых событий, определите более конкретный фильтр.
Примечание.
Фильтры чувствительны к регистру и должны соответствовать регистру полезных данных. Для фильтров телеметрии это означает, что регистр должен соответствовать регистру телеметрии, отправленной устройством.
Чтобы добавить фильтр событий при создании маршрута событий, используйте раздел "Добавление фильтра маршрутов событий" страницы "Создание маршрута события".
Можно выбрать один из базовых фильтров или использовать расширенные фильтры для создания собственных настраиваемых фильтров.
Использование базовых фильтров
Чтобы использовать базовые фильтры, разверните параметр Типы событий и установите флажки, соответствующие событиям, которые вы хотите отправить в конечную точку.
Это приведет к автоматическому заполнению текстового поля фильтра с текстом выбранного фильтра:
Использование расширенных фильтров
Вы также можете использовать параметр расширенного фильтра для записи собственных пользовательских фильтров.
Чтобы создать маршрут событий с параметрами расширенного фильтра, переместите переключатель параметра Расширенный редактор, чтобы его включить. Затем можно записать собственные фильтры событий в поле Фильтр:
Поддерживаемые фильтры маршрутов
Ниже перечислены поддерживаемые фильтры маршрутов.
| Имя фильтра | Description | Схема текста фильтра | Поддерживаемые значения |
|---|---|---|---|
| True / False | Позволяет создать маршрут без фильтрации или отключить маршрут, чтобы события не отправлялись. | <true/false> |
true = маршрут включен без фильтрации false = маршрут отключен |
| Тип | Тип события, передаваемого через ваш экземпляр цифрового двойника | type = '<event-type>' |
Ниже приведены возможные значения типов событий: Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.UpdateMicrosoft.DigitalTwins.Relationship.CreateMicrosoft.DigitalTwins.Relationship.UpdateMicrosoft.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.
Следующие шаги
Ознакомьтесь со сведениями о различных типах сообщений о событиях, которые можно получить: