Настройка экземпляра Azure Digital Twins и аутентификация (CLI)

  • Статья

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

Полная настройка для нового экземпляра Azure Digital Twins состоит из двух частей:

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

Важно!

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

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

  • Используйте среду 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.

Настройка сеанса CLI

Чтобы начать работу с Azure Digital Twins в ИНТЕРФЕЙСЕ командной строки, первое, что необходимо сделать, — войти в систему и задать контекст ИНТЕРФЕЙСА командной строки в подписке для этого сеанса. Выполните следующие команды в окне КОМАНДНОй строки:

az login
az account set --subscription "<your-Azure-subscription-ID>"

Совет

В команде выше вы также можете использовать имя подписки вместо идентификатора.

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

az provider register --namespace 'Microsoft.DigitalTwins'

Затем вы добавите расширение Интернета вещей Microsoft Azure для Azure CLI, чтобы включить команды для взаимодействия с Azure Digital Twins и другими службами Интернета вещей. Выполните следующую команду, чтобы убедиться, что используется последняя версия расширения:

az extension add --upgrade --name azure-iot

Теперь вы готовы к работе с Azure Digital Twins в Azure CLI.

Это можно проверить в любой момент, выполнив команду az dt --help, чтобы вывести список доступных команд Azure Digital Twins верхнего уровня.

Создание экземпляра Azure Digital Twins

В этом разделе вы создадите новый экземпляр Azure Digital Twins с помощью команды CLI. Вам потребуется указать следующее:

  • Группа ресурсов, в которой будет развернут экземпляр. Если у вас еще нет существующей группы ресурсов, можно создать ее с помощью этой команды: 
    az group create --location <region> --name <name-for-your-resource-group>
  • Регион для развертывания. Чтобы узнать, какие регионы поддерживают Azure Digital Twins, посетите страницу Доступность продуктов Azure по регионам.
  • Имя экземпляра. Если у вашей подписки есть другой экземпляр Azure Digital Twins в регионе, который уже использует указанное имя, вам будет предложено выбрать другое имя.

Для создания экземпляра используйте эти значения в команде az dt:

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>

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

Создание экземпляра с управляемым удостоверением

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

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

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

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

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

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned

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

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

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>

Проверка успешности и получение важных значений

Если экземпляр был создан успешно, результат в интерфейсе командной строки выглядит примерно так, выходные данные о созданном ресурсе:

Screenshot of the Cloud Shell window with successful creation of a resource group and Azure Digital Twins instance in the Azure portal.

Обратите внимание на выходные параметры hostName, name и resourceGroup для группы Azure Digital Twins. Эти значения важны, и их может потребоваться использовать при продолжении работы с экземпляром Azure Digital Twins, чтобы настроить проверку подлинности и связанные ресурсы Azure. Если другие пользователи буду заниматься программированием в экземпляре, вы должны использовать эти значения совместно с ними.

Совет

Эти свойства, а также все остальные свойства экземпляра можно просмотреть в любое время, запустив az dt show --dt-name <your-Azure-Digital-Twins-instance>.

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

Настройка прав доступа пользователей

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

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

Примечание.

Эта роль отличается от роли владельца идентификатора Microsoft Entra, которая также может быть назначена в область экземпляра Azure Digital Twins. Это две отдельные роли с правами управления, и Владелец не предоставляет доступ к функциям плоскости данных, предоставляемым Владельцем данных Azure Digital Twins.

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

Предварительные условия: требования к предоставлению разрешений

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

  • создание ресурсов Azure и управление ими;
  • управление доступом пользователей к ресурсам Azure (включая предоставление и делегирование разрешений).

Общие роли, отвечающие этому требованию: Владелец или Администратор учетной записи либо сочетание ролей Администратор доступа пользователей и Участник. Полное описание ролей и разрешений, включая разрешения, включенные в другие роли, посетите роли Azure, роли Записи Майкрософт и роли администратора классической подписки в документации по Azure RBAC.

Чтобы узнать роль, назначенную вам в подписке, перейдите на страницу подписки на портале Azure (используя представленную ссылку или поиск по строке Подписки в поле поиска на портале). Найдите имя используемой подписки и просмотрите свою роль в столбце Моя роль:

Screenshot of the Subscriptions page in the Azure portal, showing user as an owner.

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

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

Назначение роли

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

Используйте следующую команду, чтобы назначить роль (ее должен запускать пользователь с достаточными разрешениями в подписке Azure). Для выполнения команды необходимо передать имя участника-пользователя в учетной записи Microsoft Entra для пользователя, которому должна быть назначена роль. В большинстве случаев это значение будет соответствовать электронной почте пользователя в учетной записи Microsoft Entra.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"

Результат этой команды выводит сведения о назначении ролей, созданном для пользователя.

Примечание.

Если эта команда возвращает ошибку, в которой указано, CLI не может найти пользователя или субъект-службу в базе данных Graph

Назначьте роль с помощью Идентификатора объекта пользователя. Это можно сделать для пользователей с личными учетными записями Майкрософт (MSAS).

Используйте страницу портал Azure пользователей Microsoft Entra, чтобы выбрать учетную запись пользователя и открыть ее сведения. Скопируйте идентификатор объекта пользователя:

Screenshot of the user page in Azure portal highlighting the GUID in the 'Object ID' field.

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

Проверка успешного выполнения

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

Затем просмотрите все назначенные роли в разделе назначения ролей управления доступом (IAM>). Назначение роли должно отображаться в списке.

Screenshot of the role assignments for an Azure Digital Twins instance in the Azure portal.

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

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

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

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

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

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

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned

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

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false

Команды назначаемых пользователем удостоверений

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

az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

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

az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

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

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

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

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

Проверьте отдельные вызовы API REST в экземпляре с помощью команд CLI Azure Digital Twins:

См. раздел о том, как подключить клиентское приложение к экземпляру с помощью кода проверки подлинности: