Создайте ресурс Иммерсивное чтение и настройте аутентификацию Microsoft Entra

2025-04-10

В этой статье объясняется, как создать ресурс Иммерсивное средство чтения с помощью предоставленного скрипта. Этот скрипт также настраивает проверку подлинности Microsoft Entra. Каждый раз, когда создаётся ресурс 'Иммерсивный читатель', будь то с помощью этого скрипта или на портале, он должен быть настроен с разрешениями Microsoft Entra.

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

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

Разрешения

Указанный владелец подписки Azure имеет все необходимые разрешения для создания ресурса Immersive Reader и настройки аутентификации Microsoft Entra.

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

Участник. Необходимо иметь по крайней мере роль участника, связанную с подпиской Azure:
Разработчик приложений. Необходимо иметь по крайней мере роль разработчика приложений, связанную с идентификатором Microsoft Entra ID:

Дополнительные сведения см. в статье Встроенные роли Microsoft Entra.

Настройка ресурсов PowerShell

Для начала откройте Azure Cloud Shell. Убедитесь, что Cloud Shell имеет значение PowerShell в раскрывающемся списке в верхнем левом углу или введите pwsh.

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

function Create-ImmersiveReaderResource(
    [Parameter(Mandatory=$true, Position=0)] [String] $SubscriptionName,
    [Parameter(Mandatory=$true)] [String] $ResourceName,
    [Parameter(Mandatory=$true)] [String] $ResourceSubdomain,
    [Parameter(Mandatory=$true)] [String] $ResourceSKU,
    [Parameter(Mandatory=$true)] [String] $ResourceLocation,
    [Parameter(Mandatory=$true)] [String] $ResourceGroupName,
    [Parameter(Mandatory=$true)] [String] $ResourceGroupLocation,
    [Parameter(Mandatory=$true)] [String] $AADAppDisplayName,
    [Parameter(Mandatory=$true)] [String] $AADAppIdentifierUri,
    [Parameter(Mandatory=$true)] [String] $AADAppClientSecretExpiration
)
{
    $unused = ''
    if (-not [System.Uri]::TryCreate($AADAppIdentifierUri, [System.UriKind]::Absolute, [ref] $unused)) {
        throw "Error: AADAppIdentifierUri must be a valid URI"
    }

    Write-Host "Setting the active subscription to '$SubscriptionName'"
    $subscriptionExists = Get-AzSubscription -SubscriptionName $SubscriptionName
    if (-not $subscriptionExists) {
        throw "Error: Subscription does not exist"
    }
    az account set --subscription $SubscriptionName

    $resourceGroupExists = az group exists --name $ResourceGroupName
    if ($resourceGroupExists -eq "false") {
        Write-Host "Resource group does not exist. Creating resource group"
        $groupResult = az group create --name $ResourceGroupName --location $ResourceGroupLocation
        if (-not $groupResult) {
            throw "Error: Failed to create resource group"
        }
        Write-Host "Resource group created successfully"
    }

    # Create an Immersive Reader resource if it doesn't already exist
    $resourceId = az cognitiveservices account show --resource-group $ResourceGroupName --name $ResourceName --query "id" -o tsv
    if (-not $resourceId) {
        Write-Host "Creating the new Immersive Reader resource '$ResourceName' (SKU '$ResourceSKU') in '$ResourceLocation' with subdomain '$ResourceSubdomain'"
        $resourceId = az cognitiveservices account create `
                        --name $ResourceName `
                        --resource-group $ResourceGroupName `
                        --kind ImmersiveReader `
                        --sku $ResourceSKU `
                        --location $ResourceLocation `
                        --custom-domain $ResourceSubdomain `
                        --query "id" `
                        -o tsv

        if (-not $resourceId) {
            throw "Error: Failed to create Immersive Reader resource"
        }
        Write-Host "Immersive Reader resource created successfully"
    }

    # Create a Microsoft Entra app if it doesn't already exist
    $clientId = az ad app show --id $AADAppIdentifierUri --query "appId" -o tsv
    if (-not $clientId) {
        Write-Host "Creating new Microsoft Entra app"
        $clientId = az ad app create --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv
        if (-not $clientId) {
            throw "Error: Failed to create Microsoft Entra application"
        }
        Write-Host "Microsoft Entra application created successfully."

        $clientSecret = az ad app credential reset --id $clientId --end-date "$AADAppClientSecretExpiration" --query "password" | % { $_.Trim('"') }
        if (-not $clientSecret) {
            throw "Error: Failed to create Microsoft Entra application client secret"
        }
        Write-Host "Microsoft Entra application client secret created successfully."

        Write-Host "NOTE: To manage your Microsoft Entra application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section" -ForegroundColor Yellow
    }

    # Create a service principal if it doesn't already exist
    $principalId = az ad sp show --id $AADAppIdentifierUri --query "id" -o tsv
    if (-not $principalId) {
        Write-Host "Creating new service principal"
        az ad sp create --id $clientId | Out-Null
        $principalId = az ad sp show --id $AADAppIdentifierUri --query "id" -o tsv

        if (-not $principalId) {
            throw "Error: Failed to create new service principal"
        }
        Write-Host "New service principal created successfully"

        # Sleep for 5 seconds to allow the new service principal to propagate
        Write-Host "Sleeping for 5 seconds"
        Start-Sleep -Seconds 5
    }

    Write-Host "Granting service principal access to the newly created Immersive Reader resource"
    $accessResult = az role assignment create --assignee $principalId --scope $resourceId --role "Cognitive Services Immersive Reader User"
    if (-not $accessResult) {
        throw "Error: Failed to grant service principal access"
    }
    Write-Host "Service principal access granted successfully"

    # Grab the tenant ID, which is needed when obtaining a Microsoft Entra token
    $tenantId = az account show --query "tenantId" -o tsv

    # Collect the information needed to obtain a Microsoft Entra token into one object
    $result = @{}
    $result.TenantId = $tenantId
    $result.ClientId = $clientId
    $result.ClientSecret = $clientSecret
    $result.Subdomain = $ResourceSubdomain

    Write-Host "`nSuccess! " -ForegroundColor Green -NoNewline
    Write-Host "Save the following JSON object to a text file for future reference."
    Write-Host "*****"
    if($clientSecret -ne $null) {

        Write-Host "This function has created a client secret (password) for you. This secret is used when calling Microsoft Entra to fetch access tokens."
        Write-Host "This is the only time you will ever see the client secret for your Microsoft Entra application, so save it now." -ForegroundColor Yellow
    }
    else{
        Write-Host "You will need to retrieve the ClientSecret from your original run of this function that created it. If you don't have it, you will need to go create a new client secret for your Microsoft Entra application. Please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section." -ForegroundColor Yellow
    }
    Write-Host "*****`n"
    Write-Output (ConvertTo-Json $result)
}

Запустите функцию Create-ImmersiveReaderResource, подставив вместо заполнителей "<PARAMETER_VALUES>" свои значения.

Create-ImmersiveReaderResource -SubscriptionName '<SUBSCRIPTION_NAME>' -ResourceName '<RESOURCE_NAME>' -ResourceSubdomain '<RESOURCE_SUBDOMAIN>' -ResourceSKU '<RESOURCE_SKU>' -ResourceLocation '<RESOURCE_LOCATION>' -ResourceGroupName '<RESOURCE_GROUP_NAME>' -ResourceGroupLocation '<RESOURCE_GROUP_LOCATION>' -AADAppDisplayName '<MICROSOFT_ENTRA_DISPLAY_NAME>' -AADAppIdentifierUri '<MICROSOFT_ENTRA_IDENTIFIER_URI>' -AADAppClientSecretExpiration '<MICROSOFT_ENTRA_CLIENT_SECRET_EXPIRATION>'

Полная команда выглядит примерно так: Здесь мы помещаем каждый параметр в собственную строку для ясности, чтобы увидеть всю команду. Не следует копировать или использовать эту команду в том виде, в котором она здесь представлена. Скопируйте и используйте команду с собственными значениями. В этом примере имеются фиктивные значения для <PARAMETER_VALUES>. Ваш может отличаться, так как вы придумали собственные имена для этих значений.

Create-ImmersiveReaderResource
    -SubscriptionName 'MyOrganizationSubscriptionName'
    -ResourceName 'MyOrganizationImmersiveReader'
    -ResourceSubdomain 'MyOrganizationImmersiveReader'
    -ResourceSKU 'S0'
    -ResourceLocation 'westus2'
    -ResourceGroupName 'MyResourceGroupName'
    -ResourceGroupLocation 'westus2'
    -AADAppDisplayName 'MyOrganizationImmersiveReaderAADApp'
    -AADAppIdentifierUri 'api://MyOrganizationImmersiveReaderAADApp'
    -AADAppClientSecretExpiration '2021-12-31'

Параметр	Комментарии
Название подписки	Имя подписки Azure, которая будет использоваться для вашего ресурса иммерсивного средства чтения. Для создания ресурса необходимо иметь подписку.
ИмяРесурса	Должен быть буквенно-цифровым и может содержать `-`, если `-` не является первым или последним символом. Длина не может превышать 63 символов.
ПоддоменРесурса	Для ресурса иммерсивного средства чтения требуется пользовательский поддомен. Поддомен используется пакетом SDK при вызове службы иммерсивного ридера для его запуска. Поддомен должен быть глобально уникальным. Поддомен должен быть буквенно-цифровым и может содержать `-`, если `-` не является первым или последним символом. Длина не может превышать 63 символов. Этот параметр является необязательным, если ресурс уже существует.
ResourceSKU	Доступные варианты: `S0` (стандартный уровень) или `S1` (образование/некоммерческие организации). Чтобы узнать больше о каждом доступном SKU, посетите нашу страницу цен на службы искусственного интеллекта Azure. Этот параметр является необязательным, если ресурс уже существует.
Расположение ресурса	Параметры: `australiaeast`, `brazilsouth`, `canadacentral`, `centralindia`, `centralus`, `eastasia`, `eastus`, `eastus2`, `francecentral`, `germanywestcentral`, `japaneast`, `japanwest`, `jioindiawest`, `koreacentral`, `northcentralus`, `northeurope`, `norwayeast`, `southafricanorth`, `southcentralus`, `southeastasia`, `swedencentral`, `switzerlandnorth`, `switzerlandwest`, `uaenorth`, `uksouth`, `westcentralus`, `westeurope`, `westus`, `westus2`, `westus3`. Этот параметр является необязательным, если ресурс уже существует.
ИмяГруппыРесурсов	Ресурсы создаются в группах ресурсов в рамках подписок. Укажите имя существующей группы ресурсов. Если группа ресурсов еще не существует, создается новая группа ресурсов с этим именем.
РасположениеГруппыРесурсов	Если группа ресурсов не существует, необходимо указать расположение для её создания. Выполните `az account list-locations` для получения списка расположений. Используйте свойство Имя (без пробелов) возвращаемого результата. Этот параметр является необязательным, если группа ресурсов уже существует.
AADAppDisplayName	Отображаемое имя приложения Microsoft Entra. Если существующее приложение Microsoft Entra не найдено, создается новый с этим именем. Этот параметр необязателен, если приложение Microsoft Entra уже существует.
Идентификатор URI приложения AAD	URI для приложения Microsoft Entra. Если существующее приложение Microsoft Entra не найдено, создается новое с этим унифицированным указателем ресурса (URI). Например, `api://MyOrganizationImmersiveReaderAADApp`. Здесь мы используем префикс `api://` схемы URI Microsoft Entra по умолчанию для совместимости с политикой Microsoft Entra для использования проверенных доменов.
Истечение срока действия клиента AAD App Secret	Дата или дата и время, после которой истекает срок действия клиентского секрета приложения Microsoft Entra (пароля) (например, "2020-12-31T11:59:59+00:00" или "2020-12-31"). Эта функция создает секретный ключ клиента для вас.

Чтобы управлять секретами клиента приложения Microsoft Entra после создания этого ресурса, перейдите на портал Azure и выберите Home ->Microsoft Entra ID ->Регистрация приложений -> (ваше приложение) [AADAppDisplayName] ->Сертификаты и секреты ->Секреты клиента раздела.

Скопируйте выходные данные JSON в текстовый файл для последующего использования. Полученный результат должен выглядеть примерно так:
```
{
  "TenantId": "...",
  "ClientId": "...",
  "ClientSecret": "...",
  "Subdomain": "..."
}
```

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

Как запустить Иммерсивный режим чтения

Поделиться через

Создайте ресурс Иммерсивное чтение и настройте аутентификацию Microsoft Entra

Разрешения

Настройка ресурсов PowerShell

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

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

Дополнительные ресурсы