Создание конечных точек в Azure Digital Twins
В этой статье объясняется, как создать конечную точку для событий Azure Digital Twin с помощью портал Azure или Azure CLI. Вы также можете управлять конечными точками с помощью API уровня управления DigitalTwinsEndpoint.
Маршрутизация уведомлений о событиях из Azure Digital Twins в подчиненные службы или подключенные вычислительные ресурсы — это двухэтапный процесс: создание конечных точек, а затем создание маршрутов событий для отправки данных в эти конечные точки. В этой статье рассматривается первый шаг, настройка конечных точек, которые могут получать события. Позже можно создать маршруты событий, которые указывают, какие события, созданные Azure Digital Twins, доставляются в конечные точки.
Необходимые компоненты
Вам потребуется учетная запись 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.
Создание необходимых ресурсов
Эти службы — это поддерживаемые типы конечных точек, которые можно создать для вашего экземпляра:
- Раздел "Сетка событий"
- Для конечных точек Сетки событий поддерживаются только разделы сетки событий. Домены сетки событий не поддерживаются в качестве конечных точек.
- Концентратор событий
- Раздел служебной шины
Чтобы связать конечную точку с Azure Digital Twins, раздел сетки событий, концентратор событий или раздел служебная шина, который вы используете для конечной точки, необходимо уже существовать.
Используйте следующую диаграмму, чтобы узнать, какие ресурсы должны быть настроены перед созданием конечной точки.
| Тип конечной точки | Необходимые ресурсы (связанные с инструкциями по созданию) |
|---|---|
| Конечная точка Сетки событий | Раздел "Сетка событий" *схема события должна быть схемой сетки событий или облачной схемой событий версии 1.0 |
| Конечная точка Концентраторов событий | Пространство имен Центров событий Концентратор событий (Необязательно.) Правило авторизации для проверки подлинности на основе ключей |
| конечная точка служебная шина | пространство имен служебная шина Раздел служебной шины (Необязательно.) Правило авторизации для проверки подлинности на основе ключей |
Создание конечной точки
После создания ресурсов конечной точки их можно использовать для конечной точки Azure Digital Twins.
Чтобы создать новую конечную точку, перейдите на страницу своего экземпляра на портале Azure (чтобы найти экземпляр, введите его имя на панели поиска портала).
В меню экземпляра выберите пункт Конечные точки. Откроется страница Конечные точки. Выберите + Создать конечную точку. Для этого откроется страница "Создание конечной точки ", в которой будут заполнены поля, описанные ниже.
Укажите имя конечной точки и выберите тип конечной точки.
Заполните другие сведения, необходимые для типа конечной точки, включая подписку и ресурсы конечной точки, описанные ранее.
- Для центров событий и служебная шина конечных точек необходимо выбрать тип проверки подлинности. Вы можете использовать проверку подлинности на основе ключей с предварительно созданным правилом авторизации или назначаемой системой или назначаемой пользователем управляемой идентификацией. Дополнительные сведения об использовании параметров проверки подлинности удостоверений см. в разделе "Параметры конечной точки: проверка подлинности на основе удостоверений".
Чтобы завершить создание конечной точки, нажмите Сохранить.
После создания конечной точки можно убедиться в том, что она действительно создана, проверив значок уведомления на верхней панели портала Azure:
Если создать конечную точку не удалось, просмотрите сообщение об ошибке и повторите попытку через несколько минут.
Созданную конечную точку также можно просмотреть на странице Конечные точки для экземпляра Azure Digital Twins.
Теперь раздел "Сетка событий", концентратор событий или служебная шина раздел доступен в качестве конечной точки в Azure Digital Twins под именем, выбранном для конечной точки. Обычно это имя используется в качестве целевого объекта маршрута событий, который можно создать в разделе "Создание маршрутов и фильтров".
Параметры конечной точки: проверка подлинности на основе удостоверений
В этом разделе описывается, как использовать управляемое удостоверение для экземпляра Azure Digital Twins при переадресации событий в поддерживаемые назначения маршрутизации. Настройка управляемого удостоверения не требуется для маршрутизации, но она может помочь экземпляру легко получить доступ к другим защищенным ресурсам Microsoft Entra, таким как Центры событий, служебная шина назначения и контейнер служба хранилища Azure. Управляемые удостоверения могут быть назначаемыми системой или назначаемыми пользователем.
Остальная часть этого раздела содержит три шага по настройке конечной точки с управляемым удостоверением.
1. Включение управляемого удостоверения для экземпляра
Используйте приведенные ниже вкладки для инструкций, которые соответствуют предпочтительному интерфейсу.
Сначала убедитесь, что вы включили управляемое удостоверение для экземпляра Azure Digital Twins.
Кроме того, убедитесь, что у вас есть роль владельца данных Azure Digital Twins в экземпляре. Инструкции см. в разделе "Настройка разрешений доступа пользователей".
2. Назначение ролей Azure удостоверениям
После создания управляемого удостоверения для экземпляра Azure Digital Twins необходимо назначить ему соответствующие роли для проверки подлинности с различными типами конечных точек для маршрутизации событий в поддерживаемые назначения. В этом разделе описаны параметры роли и способы их назначения управляемому удостоверению.
Важно!
Обязательно выполните этот шаг. Без этого удостоверение не сможет получить доступ к конечным точкам и событиям.
Ниже приведены минимальные роли, необходимые удостоверению Azure Digital Twins для доступа к конечной точке в зависимости от типа назначения. Также будут работать роли с более высоким уровнем разрешений (например, роли владельца данных).
| Назначение | Роль Azure |
|---|---|
| Центры событий Azure | Отправитель данных Центров событий Azure |
| Служебная шина Azure | Отправитель данных Служебной шины Azure |
| Контейнер хранилища Azure | Участник данных BLOB-объектов хранилища |
Используйте приведенные ниже вкладки, чтобы назначить роль с помощью предпочитаемого интерфейса.
Чтобы назначить роль удостоверению, откройте портал Azure в окне браузера.
Перейдите к ресурсу конечной точки (концентратору событий, разделу служебной шины или контейнеру хранилища), выполнив поиск по имени на панели поиска портала.
Выберите Управление доступом (IAM) .
Выберите Добавить>Добавить назначение ролей, чтобы открыть страницу "Добавление назначения ролей".
Назначьте нужную роль управляемому удостоверению экземпляра Azure Digital Twins, используя приведенные ниже сведения. Подробные инструкции см. в статье Назначение ролей Azure с помощью портала Microsoft Azure.
Параметр Значение Роль Выберите нужную роль из параметров. Назначить доступ для Управляемое удостоверение Участники Выберите управляемое удостоверение, назначаемое пользователем или назначаемое системой, для экземпляра Azure Digital Twins, которому назначена роль. Удостоверение, назначаемое пользователем, будет иметь имя, выбранное при создании удостоверения, а назначаемое системой удостоверение будет иметь имя, соответствующее имени экземпляра Azure Digital Twins. 
3. Создание конечной точки с проверкой подлинности на основе удостоверений
После настройки управляемого удостоверения для экземпляра Azure Digital Twins и назначения ему соответствующих ролей можно создать конечные точки, использующие удостоверение для проверки подлинности. Этот параметр доступен только для конечных точек центров событий и служебная шина типов (он не поддерживается для сетки событий).
Примечание.
Вы не можете изменить конечную точку, которая уже была создана с помощью удостоверения на основе ключа, чтобы изменить проверку подлинности на основе удостоверений. При создании конечной точки необходимо выбрать тип проверки подлинности.
Используйте приведенные ниже вкладки, чтобы создать конечную точку с помощью предпочтительного интерфейса.
Начните с общих инструкций по созданию конечной точки Azure Digital Twins.
Когда вы получите на шаге завершения сведений, необходимых для типа конечной точки, выберите назначенный системой или назначаемый пользователем (предварительная версия) для типа проверки подлинности.
Завершите настройку конечной точки и нажмите кнопку Сохранить.
Рекомендации по отключению управляемых удостоверений
Так как удостоверение управляется отдельно от конечных точек, которые его используют, важно учитывать, как повлияют любые изменения в удостоверении или его ролях на конечные точки в вашем экземпляре Azure Digital Twins. Если удостоверение отключено или была удалена роль, необходимая для конечной точки, такая конечная точка может стать недоступной и поток событий будет нарушен.
Чтобы продолжить использовать конечную точку, для которой было настроено уже отключенное управляемое удостоверение, необходимо удалить конечную точку и Создать ее повторно с другим типом проверки подлинности. На возобновление доставки в конечную точку после такого изменения может потребоваться до часа.
Параметры конечной точки: недоставка
Когда конечная точка не может доставить событие в течение определенного периода времени или по истечении определенного количества попыток доставки, она может отправить недоставленное событие в учетную запись хранения. Этот процесс называется перемещением в очередь недоставленных сообщений.
Необходимые ресурсы хранилища можно настроить с помощью портала Azure или интерфейса командной строки Azure Digital Twins. Однако чтобы создать конечную точку с поддержкой недоставленных букв, вам потребуется использовать ИНТЕРФЕЙС командной строки Azure Digital Twins или API плоскости управления.
Дополнительные сведения о недоставленных письмах см. в статье "Конечные точки" и "Маршруты событий". Инструкции по настройке конечной точки с недоставкой сообщений см. далее в этом разделе.
Настройка ресурсов хранилища
Прежде чем задать параметры расположения недоставленных сообщений, необходимо настроить в учетной записи Azure учетную запись хранения с контейнером.
Позже при создании конечной точки вы укажете универсальный код ресурса (URI) для этого контейнера. Расположение недоставленных сообщений будет передано конечной точке в качестве универсального кода ресурса (URI) контейнера с маркером SAS. Этому маркеру требуется разрешение write для контейнера назначения в учетной записи хранения. Полный формируемый URI недоставленной буквы SAS будет иметь следующий формат https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>:
Выполните приведенные ниже действия по настройке этих ресурсов хранилища в учетной записи Azure, чтобы подготовиться к настройке подключения конечной точки в следующем разделе.
- Выполните действия, описанные в статье "Создание учетной записи хранения" для создания учетной записи хранения в подписке Azure. Запишите имя учетной записи хранения для последующего использования.
- Выполните действия, описанные в разделе "Создание контейнера", чтобы создать контейнер в новой учетной записи хранения. Запишите имя контейнера для последующего использования.
Создание маркера SAS
Затем создайте маркер SAS для учетной записи хранения, который конечная точка будет использовать для доступа к ней.
Для начала перейдите в свою учетную запись хранения на портале Azure (чтобы ее найти, введите ее имя на панели поиска портала).
На странице учетной записи хранения щелкните ссылку Подписанный URL-адрес на левой панели навигации, чтобы начать настройку маркера SAS.
На странице подписанного URL-адреса выберите необходимые параметры в разделах Допустимые службы и Допустимые типы ресурсов. Необходимо выбрать по крайней мере одно поле в каждой категории. В разделе Допустимые разрешения выберите Запись (при необходимости можно также выбрать другие разрешения).
Задайте необходимые значения для остальных параметров.
По завершении нажмите кнопку Создать SAS и строку подключения, чтобы создать маркер SAS.
Это приведет к созданию нескольких значений SAS и строка подключения в нижней части той же страницы под выбранными параметрами. Прокрутите вниз, чтобы просмотреть значения, и используйте значок Копировать в буфер обмена, чтобы скопировать значение маркера SAS. Сохраните его для последующего использования.
Создание конечной точки недоставленного сообщения
Чтобы создать конечную точку с поддержкой недоставленных букв, необходимо использовать команды CLI или API уровня управления для создания конечной точки, а не портал Azure.
Инструкции по созданию этой конечной точки с помощью Azure CLI см. на вкладку CLI для этого раздела.
Схема хранилища сообщений
После настройки конечной точки с недоставкой сообщений недоставленные сообщения будут храниться в следующем формате в учетной записи хранения:
<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"
}
Следующие шаги
Для реальной передачи данных из Azure Digital Twins в конечную точку необходимо определить маршрут событий. Эти маршруты позволяют разработчикам подключать поток событий во всей системе и в подчиненных службах. Один маршрут позволяет выбрать несколько уведомлений и типов событий. Продолжайте создавать маршрут событий к конечной точке в разделе "Создание маршрутов и фильтров".