Membuat sumber daya Pembaca Imersif dan mengonfigurasi autentikasi Microsoft Entra

  • Artikel

Artikel ini menjelaskan cara membuat sumber daya Pembaca Imersif dengan menggunakan skrip yang disediakan. Skrip ini juga mengonfigurasi autentikasi Microsoft Entra. Setiap kali sumber daya Pembaca Imersif dibuat, baik dengan skrip ini atau di portal, sumber daya tersebut harus dikonfigurasi dengan izin Microsoft Entra.

Skrip membuat dan mengonfigurasi semua sumber daya Pembaca Imersif dan Microsoft Entra yang diperlukan untuk Anda. Namun, Anda juga dapat mengonfigurasi autentikasi Microsoft Entra untuk sumber daya Pembaca Imersif yang ada, jika Anda sudah membuatnya di portal Azure. Skrip pertama-tama mencari sumber daya Pembaca Imersif dan Microsoft Entra yang ada di langganan Anda, dan membuatnya hanya jika belum ada.

Untuk beberapa pelanggan, mungkin perlu membuat beberapa sumber daya Pembaca Imersif, untuk pengembangan versus produksi, atau mungkin untuk wilayah yang berbeda tempat layanan Anda disebarkan. Untuk kasus tersebut, Anda dapat kembali dan menggunakan skrip beberapa kali untuk membuat sumber daya Pembaca Imersif yang berbeda dan membuatnya dikonfigurasi dengan izin Microsoft Entra.

Izin

Pemilik langganan Azure Anda yang tercantum memiliki semua izin yang diperlukan untuk membuat sumber daya Pembaca Imersif dan mengonfigurasi autentikasi Microsoft Entra.

Jika Anda bukan pemilik, izin khusus cakupan berikut diperlukan:

  • Kontributor. Anda harus memiliki setidaknya peran Kontributor yang terkait dengan langganan Azure:

    Screenshot of contributor built-in role description.

  • Pengembang Aplikasi. Anda harus memiliki setidaknya peran Pengembang Aplikasi yang terkait dalam ID Microsoft Entra:

    Screenshot of the developer built-in role description.

Untuk informasi selengkapnya, lihat Peran bawaan Microsoft Entra.

Menyiapkan sumber daya PowerShell

  1. Mulai dengan membuka Azure Cloud Shell. Pastikan Cloud Shell diatur ke PowerShell di menu dropdown tangan kiri atas atau dengan mengetik pwsh.

  2. Salin dan tempel cuplikan kode berikut ke dalam 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)
}

  3. Jalankan fungsi Create-ImmersiveReaderResource, menyediakan tempat penampung '<PARAMETER_VALUES>' dengan nilai Anda sendiri yang sesuai.

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

    Perintah lengkap terlihat seperti berikut ini. Di sini kita menempatkan setiap parameter pada barisnya sendiri untuk kejelasan, sehingga Anda dapat melihat seluruh perintah. Jangan menyalin atau menggunakan perintah ini apa adanya. Salin dan gunakan perintah dengan nilai Anda sendiri. Contoh ini memiliki nilai dummy untuk <PARAMETER_VALUES>. Anda mungkin berbeda, karena Anda datang dengan nama Anda sendiri untuk nilai-nilai ini.

    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'
    Parameter Komentar
    SubscriptionName Nama langganan Azure yang akan digunakan untuk sumber daya Immersive Reader Anda. Anda harus memiliki langganan untuk membuat sumber daya.
    ResourceName Harus alfanumerik, dan dapat berisi -, selama - bukan karakter pertama atau terakhir. Panjang tidak boleh melebihi 63 karakter.
    ResourceSubdomain Subdomain kustom diperlukan untuk sumber daya Immersive Reader Anda. Subdomain digunakan oleh SDK saat memanggil layanan Immersive Reader untuk meluncurkan Pembaca. Subdomain harus unik secara global. Subdomain harus alfanumerik, dan dapat berisi -, selama - bukan karakter pertama atau terakhir. Panjang tidak boleh melebihi 63 karakter. Parameter ini opsional jika sumber daya sudah ada.
    ResourceSKU Opsi: S0 (Tingkat standar) atau S1 (Organisasi Pendidikan/Nirlaba). Untuk mempelajari selengkapnya tentang setiap SKU yang tersedia, kunjungi halaman harga layanan Azure AI kami. Parameter ini opsional jika sumber daya sudah ada.
    ResourceLocation Opsi: 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. Parameter ini opsional jika sumber daya sudah ada.
    ResourceGroupName Sumber daya dibuat dalam grup sumber daya dalam langganan. Berikan nama grup sumber daya yang ada. Jika grup sumber daya belum ada, grup sumber daya baru dengan nama ini dibuat.
    ResourceGroupLocation Jika grup sumber daya tidak ada, Anda perlu menyediakan lokasi untuk membuat grup. Untuk menemukan daftar lokasi, jalankan az account list-locations. Gunakan properti nama (tanpa spasi) dari hasil yang dihasilkan. Parameter ini opsional jika grup sumber daya Anda sudah ada.
    AADAppDisplayName Nama tampilan aplikasi Microsoft Entra. Jika aplikasi Microsoft Entra yang ada tidak ditemukan, aplikasi baru dengan nama ini dibuat. Parameter ini bersifat opsional jika aplikasi Microsoft Entra sudah ada.
    AADAppIdentifierUri URI untuk aplikasi Microsoft Entra. Jika aplikasi Microsoft Entra yang ada tidak ditemukan, aplikasi baru dengan URI ini dibuat. Contohnya, api://MyOrganizationImmersiveReaderAADApp. Di sini kita menggunakan awalan api:// skema Microsoft Entra URI default untuk kompatibilitas dengan kebijakan Microsoft Entra menggunakan domain terverifikasi.
    AADAppClientSecretExpiration Tanggal atau tanggalwaktu setelah Rahasia Klien Aplikasi (kata sandi) Microsoft Entra Anda kedaluwarsa (misalnya, '2020-12-31T11:59:59+00:00' atau '2020-12-31'). Fungsi ini membuat rahasia klien untuk Anda.

    Untuk mengelola rahasia klien aplikasi Microsoft Entra setelah Anda membuat sumber daya ini, kunjungi portal Azure dan bukaberanda ->Microsoft Entra ID ->Pendaftaran Aplikasi -> (aplikasi Anda) [AADAppDisplayName] ->Bagian Sertifikat dan Rahasia ->Rahasia Klien.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Salin output JSON ke dalam file teks untuk digunakan nanti. Output akan terlihat seperti di bawah ini.

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

Langkah selanjutnya

Cara meluncurkan Pembaca Imersif