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

發行項
02/21/2024

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

腳本會為您建立及設定所有必要的沉浸式閱讀程式和 Microsoft Entra 資源。不過，如果您已在 Azure 入口網站中建立 Microsoft Entra 驗證，您也可以為現有的沉浸式閱讀程式資源設定 Microsoft Entra 驗證。腳本會先在您的訂用帳戶中尋找現有的沉浸式閱讀程式和 Microsoft Entra 資源，而且只有在這些資源不存在時才會建立它們。

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

權限

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

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

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

如需詳細資訊，請參閱 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 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`、、、、 `eastasiafrancecentraluaenorthuksouthswedencentraljapaneastwestcentralusjapanwestsoutheastasiajioindiawestswitzerlandwestkoreacentralnorthcentraluswestuswestus3eastus2eastuscentralusgermanywestcentralswitzerlandnorthwesteuropenorwayeastcentralindiasouthafricanorthnortheuropesouthcentraluswestus2canadacentral` 如果資源已經存在，這個參數是選擇性的。
resourceGroupName	資源會在訂用帳戶內的資源群組中建立。提供現有資源群組的名稱。如果資源群組尚未存在，則會建立具有此名稱的新群組。
ResourceGroupLocation	如果您的資源群組不存在，您必須提供要在其中建立群組的位置。若要尋找位置清單，請執行 `az account list-locations`。使用傳回結果的名稱屬性（不含空格）。如果您的資源群組已經存在，這個參數是選擇性的。
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 Application Client Secret （password）到期的日期或日期時間（例如'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 資源

後續步驟

其他資源

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