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

Предварительные условия

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

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

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

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>

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

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

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

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

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

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

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

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

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

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

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

Общие роли, соответствующие этому требованию, являются владельцем, администратором учетной записи или сочетанием администратора доступа пользователей и участника. Для полного объяснения ролей и разрешений, включая те, которые входят в состав других ролей, посетите роли Azure, роли Microsoft Entra, и роли администратора классической подписки в документации по Azure RBAC.

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

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

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

Назначьте роль

Чтобы предоставить пользователю разрешение на управление экземпляром 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"

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

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

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

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

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

Теперь у вас есть экземпляр 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-assigned на false.

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

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

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

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

• Ссылка на az dt
• Набор команд Azure Digital Twins CLI

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

• Написание кода проверки подлинности клиентского приложения