你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

创建沉浸式阅读器资源并配置 Microsoft Entra 身份验证

项目
09/04/2024

本文介绍如何使用提供的脚本创建沉浸式阅读器资源。此脚本还配置 Microsoft Entra 身份验证。每当创建沉浸式阅读器资源时，无论是使用此脚本还是在门户中创建，都必须使用 Microsoft Entra 权限进行配置。

此脚本会为你创建和配置所有必要的沉浸式阅读器和 Microsoft Entra 资源。不过，你也可以为现有的沉浸式阅读器资源配置 Microsoft Entra 身份验证（如果你已在 Azure 门户中创建了一个）。该脚本首先会查找订阅中的现有沉浸式阅读器和 Microsoft Entra 资源，并且仅在它们不存在时进行创建。

对于某些客户，可能必须创建多个沉浸式阅读器资源，以用于开发和生产，或者可能用于部署服务的不同区域。对于这些情况，可以返回并多次使用该脚本来创建不同的沉浸式阅读器资源，并使用 Microsoft Entra 权限对其进行配置。

权限

列出的 Azure 订阅的“所有者”具有创建沉浸式阅读器资源和配置 Microsoft Entra 身份验证所需的全部权限。

如果你不是所有者，则需要以下特定于范围的权限：

参与者。至少需要具有与 Azure 订阅关联的参与者角色：
应用程序开发人员：需要在 Microsoft Entra ID 中至少关联应用程序开发人员角色：

有关详细信息，请参阅 Microsoft Entra 内置角色。

设置 PowerShell 资源

首先打开 Azure Cloud Shell。请确保在左上角下拉列表中或通过键入 pwsh，将 Cloud Shell 设置为 PowerShell。

将以下代码片段复制并粘贴到 shell 中。

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 an 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'

参数	注释
SubscriptionName	要用于沉浸式阅读器资源的 Azure 订阅的名称。为了创建资源，必须拥有订阅。
ResourceName	必须为字母数字，可以包含 `-`，但 `-` 不能是第一个或最后一个字符。长度不能超过 63 个字符。
ResourceSubdomain	沉浸式阅读器资源需要自定义子域。当调用沉浸式阅读器服务以启动阅读器时，SDK 将使用该子域。该子域必须在全局中独一无二。子域必须为字母数字，可以包含 `-`，但 `-` 不能是第一个或最后一个字符。长度不能超过 63 个字符。如果该资源已存在，则可以选择此参数。
ResourceSKU	选项：`S0`（标准层）或 `S1`（教育/非盈利组织）。若要详细了解每个可用的 SKU，请访问我们的 Azure AI 服务定价页面。如果该资源已存在，则可以选择此参数。
ResourceLocation	选项：`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`。如果该资源已存在，则可以选择此参数。
ResourceGroupName	资源是在订阅中的资源组中创建的。提供现有资源组的名称。如果资源组尚不存在，则会创建一个具有该名称的新资源组。
ResourceGroupLocation	如果资源组尚不存在，则需要提供一个用于创建组的位置。要查找位置列表，请运行 `az account list-locations`。使用返回结果的 name 属性（无空格）。如果资源组已存在，则可以选择此参数。
AADAppDisplayName	Microsoft Entra 应用程序显示名称。如果未找到现有的 Microsoft Entra 应用程序，则会创建一个具有此名称的新应用程序。如果 Microsoft Entra 应用程序已存在，则可以选择此参数。
AADAppIdentifierUri	Microsoft Entra 应用程序的 URI。如果未找到现有的 Microsoft Entra 应用程序，则会创建一个具有此 URI 的新应用程序。例如 `api://MyOrganizationImmersiveReaderAADApp`。在这里，我们使用默认的 Microsoft Entra URI 方案前缀 `api://` 以与使用已验证域的 Microsoft Entra 策略兼容。
AADAppClientSecretExpiration	Microsoft Entra 应用程序客户端密码（密码）的有效期截止日期或日期/时间（例如“2020-12-31T11:59:59+00:00”或“2020-12-31”）。此函数将为你创建客户端密码。

若要在创建此资源后管理 Microsoft Entra 应用程序客户端密码，请访问 Azure 门户，然后转到“主页”->“Microsoft Entra ID”->“应用注册”->“(你的应用) [AADAppDisplayName]”->“证书和密码”部分 ->“客户端密码”部分。

将 JSON 输出复制到某个文本文件供稍后使用。输出应如下所示。

{
  "TenantId": "...",
  "ClientId": "...",
  "ClientSecret": "...",
  "Subdomain": "..."
}

下一步

如何启动沉浸式阅读器

通过

创建沉浸式阅读器资源并配置 Microsoft Entra 身份验证

权限

设置 PowerShell 资源

下一步

反馈

其他资源