Создание конечных точек в Azure Digital Twins

Эта статья объясняет, как создать конечную точку для событий Azure Digital Twin, используя портал Azure или Azure CLI. Вы также можете управлять конечными точками с API плоскости управления DigitalTwinsEndpoint.

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

Предпосылки

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

Если вы планируете использовать 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.

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

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

Раздел "Сетка событий"
- В случае конечных точек Event Grid поддерживаются только темы Event Grid. Домены Event Grid не поддерживаются как конечные точки.
Event Hubs хаб
Service Bus тема

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

Используйте следующую таблицу, чтобы узнать, какие ресурсы нужно подготовить перед созданием конечной точки.

Тип конечной точки	Требуемые ресурсы (ссылка на инструкции по созданию)
конечная точка Event Grid	тема Event Grid (Схема событий должна быть схемой сетки событий или облачной схемой событий версии 1.0)
Точка подключения Event Hubs	Пространство имен Центров событий Концентратор событий (Необязательно) Правило авторизации для проверки подлинности на основе ключей
Конечная точка службы шины	Пространство имен Service Bus Тема служебной шины (Необязательно) Правило авторизации для проверки подлинности на основе ключей

Создать конечную точку

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

Портал
CLI

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

В меню экземпляра > выберите "Подключить выходные точки". Затем на странице Точки подключений выберите + Создать точку подключения. Это действие открывает страницу Создание конечной точки.
Введите Имя для вашей конечной точки и выберите Тип конечной точки.
Завершите ввод других деталей, которые необходимы для вашего типа конечной точки, включая подписку и описанные раньше ресурсы конечной точки.
1. Для конечных точек Event Hubs и Service Bus выберите тип аутентификации только. Вы можете использовать аутентификацию на основе ключа с заранее созданным правилом авторизации или управляемой идентичностью, назначенной системе или пользователю. Назначаемое системой удостоверение доступно только в том случае, если вы включили удостоверение, назначаемое системой для экземпляра. Дополнительные сведения об использовании параметров проверки подлинности удостоверений см. в разделе " Параметры конечной точки: проверка подлинности на основе удостоверений " далее в этой статье.
Закончите создание вашего конечной точки, выбрав Сохранить.

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

Скриншот уведомления для подтверждения создания конечной точки в портале Azure.

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

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

Теперь топик Event Grid, центр событий или топик Service Bus доступен в качестве конечной точки в Azure Digital Twins под именем, которое вы выбрали для этой конечной точки. Обычно это имя используется в качестве цели маршрута события, который вы можете создать в Создать маршруты и фильтры.

Следующие примеры показывают, как создать конечные точки с помощью команды az dt endpoint create для Azure Digital Twins CLI. Замените заполнители в командах на данные ваших собственных ресурсов.

Чтобы создать конечную точку Event Grid:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Чтобы создать конечную точку Event Hubs (аутентификация на основе ключа):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Чтобы создать конечную точку темы Service Bus (аутентификация на основе ключей):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

После выполнения этих команд раздел сетки событий, концентратор событий или раздел служебной шины доступен в качестве конечной точки в Azure Digital Twins. Конечная точка имеет имя, предоставленное аргументом --endpoint-name . Обычно это имя используется в качестве цели маршрута события, который вы можете создать в Создать маршруты и фильтры.

Параметры конечной точки: Аутентификация на основе идентификации

Этот раздел описывает, как использовать управляемую идентичность для экземпляра Azure Digital Twins, при отправке событий на поддерживаемые маршрутизационные назначений. Настройка управляемой идентичности не требуется для маршрутизации, но она может помочь экземпляру легко получить доступ к другим защищенным ресурсам Microsoft Entra, таким как Event Hubs, назначения Service Bus, и Azure Storage Container. Управляемые идентичности могут быть системно назначенными или пользовательски назначенными.

Остальная часть этого раздела описывает три шага для настройки конечной точки с управляемой идентификацией.

1. Включите управляемую идентичность для экземпляра

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

Портал
CLI

Сначала убедитесь, что вы включили управляемую идентичность для экземпляра Azure Digital Twins.

Кроме того, убедитесь, что у вас есть роль Azure Digital Twins Data Owner на этом экземпляре. Инструкции можно найти в Set up user access permissions.

2. Назначьте роли Azure для идентификатора

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

Это важно

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

Вот минимальные роли, которые должны быть у вашей идентификации в Azure Digital Twins, чтобы получить доступ к конечной точке, в зависимости от типа назначения. Роли с более высокими разрешениями (например, роли владельцев данных) также работают.

Место назначения	Роль Azure
Центры событий Azure	Отправитель данных Azure Event Hubs
Служебная шина Azure	Отправитель данных Azure Service Bus
Контейнер хранилища Azure	Вкладчик данных хранилища Blob

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

Портал
CLI

Чтобы назначить роль для удостоверения, откройте портал Azure в браузере.

Перейдите к вашему ресурсу конечной точки (вашему узлу событий, теме Service Bus или контейнеру хранения), найдя его имя в строке поиска портала.
Выберите Управление доступом (IAM).
Выберите Добавить>Добавить назначение роли, чтобы открыть страницу добавления назначения роли.

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

Настройки	Значение
Роль	Выберите желаемую роль из вариантов.
Назначить доступ к	Управляемая идентичность
Члены	Выберите управляемую личность, назначенную пользователем или системой, для вашего экземпляра Azure Digital Twins, которому назначается роль. Пользовательская идентичность имеет имя, которое вы выбрали при ее создании, а системная идентичность имеет имя, совпадающее с именем вашего экземпляра Azure Digital Twins.

Вы можете добавить параметр --scopes к команде az dt create, чтобы назначить идентификатор одной или нескольким областям с заданной ролью. Используйте эту команду при первом создании экземпляра или позже, передав имя существующего экземпляра.

Вот пример, который создает экземпляр с управляемой идентификацией, назначенной системой, и присваивает этой идентификации пользовательскую роль под названием MyCustomRole в концентраре событий.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

Для получения дополнительных примеров назначения ролей с помощью этой команды, смотрите документацию справки по az dt create.

Вы также можете использовать группу команд az role assignment для создания и управления ролями. Используйте эту команду для поддержки других сценариев, когда вы не хотите группировать назначение роли с командой создания.

3. Создайте конечную точку с аутентификацией на основе идентификации.

После настройки управляемой идентификации для вашего экземпляра Azure Digital Twins и назначения ему соответствующих ролей, создайте конечные точки, которые используют эту идентификацию для аутентификации. Эта опция доступна только для конечных точек типа Event Hubs и Service Bus (она не поддерживается для Event Grid).

Примечание

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

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

Портал
CLI

Начните выполнение общих инструкций, чтобы создать конечную точку Azure Digital Twins.

Когда вы дойдете до этапа заполнения данных, необходимых для вашего типа конечной точки, выберите тип аутентификации: либо Системно назначенный, либо Назначенный пользователем (предварительная версия).

Завершите настройку вашей конечной точки и выберите Save.

Чтобы добавить управляемые идентификаторы на конечную точку, добавьте параметры в команду az dt endpoint create. Для получения дополнительной информации об этой команде см. ссылочную документацию или общие инструкции по созданию конечной точки Azure Digital Twins.

Используйте следующую команду CLI для выбранного вами типа управляемой идентичности.

Команда идентификации, назначенной системой

Чтобы создать конечную точку, которая использует аутентификацию, назначаемую системой, укажите тип аутентификации IdentityBased с параметром --auth-type. Следующий пример иллюстрирует эту функциональность для конечной точки Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

Команда для присвоения идентичности пользователем

Чтобы создать конечную точку, использующую аутентификацию с помощью назначенной пользователем идентичности, укажите идентификатор ресурса назначенной пользователем идентичности с параметром --user. Следующий пример иллюстрирует эту функциональность для конечной точки Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

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

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

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

Параметры конечной точки: Отправка в недоставленную очередь

Если конечная точка не может доставлять событие в течение определенного периода времени или количества попыток, он может отправить событие без выполнения в учетную запись хранения. Этот процесс известен как обработка "мертвых писем".

Вы можете настроить необходимые ресурсы хранения, используя портал Azure или CLI Azure Digital Twins. Однако для создания конечной точки с включенной функцией обработки "dead-lettering" вам необходимо использовать Azure Digital Twins CLI или control plane APIs.

Чтобы узнать больше о dead-lettering, см. Конечные точки и маршруты событий. Инструкции по настройке конечной точки с недоставленной буквой см. в остальной части этого раздела.

Настройте ресурсы хранения

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

При создании конечной точки вы предоставляете URI этого контейнера. Местоположение для непринятых сообщений предоставляется конечной точке в виде URI контейнера с токеном SAS. Этот токен требует разрешения write на контейнер назначения в рамках учетной записи хранения. Полностью сформированный SAS URI "мертвого письма" имеет следующий формат: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

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

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

Создание токена SAS

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

Портал
CLI

Перейдите к своей учетной записи хранилища в портале Azure (вы можете найти её по имени с помощью строки поиска портала).
На странице учетной записи хранения выберите ссылку "Безопасность и сеть" и "Подпись общего доступа"> в левой панели навигации, чтобы начать настройку маркера SAS.
На странице с общим доступом подписи в разделе «Разрешенные службы» и «Разрешенные типы ресурсов» выберите настройки, которые хотите. Необходимо выбрать по крайней мере одно поле в каждой категории. Под Разрешённые разрешения выберите Запись. Вы также можете выбрать другие разрешения.
Установите желаемые значения для оставшихся настроек.
Когда вы закончите, выберите Создать маркер SAS и строку подключения, чтобы создать маркер SAS.
Выполнение этого процесса создает несколько значений SAS и строк подключения в нижней части той же страницы под выбранными параметрами. Прокрутите вниз, чтобы просмотреть значения, и используйте значок Копировать в буфер обмена для копирования значения SAS токен. Сохраните его для последующего использования.

Чтобы получить ключи вашей учетной записи хранилища, используйте следующую команду и скопируйте значение одного из ваших ключей.
```
az storage account keys list --account-name <storage-account-name>
```
Выберите дату окончания срока действия и создайте маркер SAS для учетной записи хранения с помощью следующей команды:
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
Вывод этой команды — SAS токен. Скопируйте значение токена SAS для последующего использования.

Примечание

Пример набора параметров в предыдущей команде включает в себя службы "blob", "file", "queue" и "table" (--services bfqt), тип ресурса "object" (--resource-types o), и разрешения "write" (--permissions w).

Дополнительные сведения о команде az storage account generate-sas и его параметрах см. в справочнике по Azure CLI.

Создайте конечную точку для писем с ошибками

Портал
CLI

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

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

Чтобы создать конечную точку с включенной функцией отправки в мертвую очередь, добавьте параметр --deadletter-sas-uri к команде az dt endpoint create, которая создает конечную точку.

Значение параметра — это URI службы SAS для сообщений-отказников, состоящий из имени учетной записи хранения, имени контейнера и токена SAS, которые вы собрали в предыдущем разделе. Этот параметр создаёт конечную точку с аутентификацией на основе ключа. Вот как выглядит этот параметр:

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Подсказка

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

Вы также можете создавать конечные точки сбоя с помощью API плоскости управления Azure Digital Twins вместо CLI. Чтобы сделать это, ознакомьтесь с документацией DigitalTwinsEndpoint, чтобы узнать, как структурировать запрос и добавить параметры невостребованных сообщений.

Схема хранения сообщений

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

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

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

Ниже приведен пример сообщения о недоставленной букве для уведомления о создании двойника:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

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

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

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

Были ли сведения на этой странице полезными?

Last updated on 2025-06-19