建立沉浸式閱讀程式資源，並設定 Microsoft Entra 驗證

發行項
10/16/2024

本文說明如何使用提供的指令碼，建立沉浸式閱讀程序資源。此指令碼也設定 Microsoft Entra 驗證。每次建立沉浸式閱讀程式資源時，無論是使用此指令碼或在入口網站中進行此操作，都須使用 Microsoft Entra 權限進行設定。

指令碼會為您建立並設定所有必要的沉浸式閱讀程式和 Microsoft Entra 資源。不過，如果您已在 Azure 入口網站中建立 Microsoft Entra 驗證，也可以針對現有沉浸式閱讀程式資源設定 Microsoft Entra 驗證。指令碼會先在您的訂用帳戶中尋找現有的沉浸式閱讀程式與 Microsoft Entra 資源，且若無資源，也會建立這些資源。

對於某些客戶，可能需要針對開發與生產，或也許針對服務部署所在的不同區域，建立多個沉浸式閱讀程式資源。針對這些情況，您可以回頭使用指令碼多次來建立不同的沈浸式閱讀程式資源，並使用 Microsoft Entra 權限加以設定。

權限

列出的 Azure 訂用帳戶擁有者具有建立沉浸式閱讀程式資源及設定 Microsoft Entra 驗證所需的所有必要權限。

如果您不是擁有者，則需要下列範圍特定權限：

參與者。您必須至少有與 Azure 訂用帳戶相關聯的「參與者」角色：
應用程式開發人員。您必須至少有 Microsoft Entra ID 中相關聯的「應用程式開發人員」角色：

如需詳細資訊，請參閱 Microsoft Entra 內建角色。

設定 PowerShell 資源

從開啟 Azure Cloud Shell 開始。確定在左上方下拉式清單中或輸入 pwsh 將 Cloud Shell 設定為 PowerShell。

複製以下程式碼片段並將其貼至殼層。

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 服務定價頁面。如果資源已經存在，此參數是選用的。
資源位置	選項：`australiaeast`、`brazilsouth`、`canadacentral`、`centralindia`、`centralus`、`eastasia`、`eastus`、`eastus2`、`francecentral`、`germanywestcentral`、`japaneast`、`japanwest`、`jioindiawest`、`koreacentral`、`northcentralus`、`northeurope`、`norwayeast`、`southafricanorth`、`southcentralus`、`southeastasia`、`swedencentral`、`switzerlandnorthswitzerlandwest`、`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 資源

後續步驟

意見反應

其他資源