Создание конечных точек в 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 (чтобы найти экземпляр, введите его имя на панели поиска портала).

1. В меню экземпляра выберите пункт Конечные точки. Откроется страница Конечные точки. Выберите + Создать конечную точку. Для этого откроется страница "Создание конечной точки ", в которой будут заполнены поля, описанные ниже.

   

2. Укажите имя конечной точки и выберите тип конечной точки.

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

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

   

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

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

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

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

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

CLI

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

Чтобы создать конечную точку типа "Сетка событий", выполните следующую команду:

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>

Чтобы создать конечную точку типа "Концентратор событий" (проверка подлинности на основе ключей), выполните следующую команду:

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>

Чтобы создать конечную точку раздела служебной шины (проверка подлинности на основе ключей), выполните следующую команду:

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, таким как Центры событий, служебная шина назначения и контейнер служба хранилища Azure. Управляемые удостоверения могут быть назначаемыми системой или назначаемыми пользователем.

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

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

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

Портал

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

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

CLI

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

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

2. Назначение ролей Azure удостоверениям

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

Внимание

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

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

Назначение	Роль Azure
Центры событий Azure	Отправитель данных Центров событий Azure
Служебная шина Azure	Отправитель данных Служебной шины Azure
Контейнер хранилища Azure	Участник данных хранилища BLOB-объектов

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

Портал

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

1. Перейдите к ресурсу конечной точки (концентратору событий, разделу служебной шины или контейнеру хранилища), выполнив поиск по имени на панели поиска портала.

2. Выберите Управление доступом (IAM) .

3. Выберите Добавить>Добавить назначение ролей, чтобы открыть страницу "Добавление назначения ролей".

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

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

   

CLI

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

Ниже приведен пример создания экземпляра с управляемым удостоверением, назначаемого системой, и назначает это удостоверение настраиваемой роли, вызываемой 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.

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

3. Создание конечной точки с проверкой подлинности на основе удостоверений

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

Примечание.

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

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

Портал

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

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

Завершите настройку конечной точки и нажмите кнопку Сохранить.

CLI

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

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

Команда удостоверения, назначаемая системой

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

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 . В приведенном ниже примере эта функция показана для конечной точки Центров событий.

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 или интерфейса командной строки 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, чтобы подготовиться к настройке подключения конечной точки в следующем разделе.

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

Создание маркера SAS

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

Портал

1. Для начала перейдите в свою учетную запись хранения на портале Azure (чтобы ее найти, введите ее имя на панели поиска портала).

2. На странице учетной записи хранения щелкните ссылку Подписанный URL-адрес на левой панели навигации, чтобы начать настройку маркера SAS.

   

3. На странице подписанного URL-адреса выберите необходимые параметры в разделах Допустимые службы и Допустимые типы ресурсов. Необходимо выбрать по крайней мере одно поле в каждой категории. В разделе Допустимые разрешения выберите Запись (при необходимости можно также выбрать другие разрешения).

4. Задайте необходимые значения для остальных параметров.

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

   

6. Это приведет к созданию нескольких значений SAS и строка подключения в нижней части той же страницы под выбранными параметрами. Прокрутите вниз, чтобы просмотреть значения, и используйте значок Копировать в буфер обмена, чтобы скопировать значение маркера SAS. Сохраните его для последующего использования.

CLI

1. Получите ключи учетной записи хранения с помощью следующей команды и скопируйте значение любого из ключей:

   az storage account keys list --account-name <storage-account-name>
   

2. Выберите дату окончания срока действия и создайте маркер 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, тип ресурса object, а также разрешение write.

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

Создание конечной точки недоставленного сообщения

Портал

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

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

CLI

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

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

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

Совет

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

Кроме того, можно создавать конечные точки недоставленных букв с помощью API плоскости управления Azure Digital Twins вместо интерфейса командной строки. Для этого просмотрите документацию 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"
}

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

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