Membuat sumber daya Immersive Reader dan Mengonfigurasi autentikasi Azure Active Directory

Dalam artikel ini, kami memberikan skrip yang akan membuat sumber daya Immersive Reader dan mengonfigurasi autentikasi Azure Active Directory (AAD). Setiap kali sumber daya Immersive Reader dibuat, baik dengan skrip ini atau di portal, sumber daya Immersive Reader juga harus dikonfigurasi dengan izin Azure Active Directory. Skrip ini akan membantu Anda dengan hal itu.

Skrip ini didesain untuk membuat dan mengonfigurasi semua sumber daya Immersive Reader dan Azure Active Directory yang diperlukan untuk Anda semua dalam satu langkah. Namun, Anda juga dapat mengonfigurasi autentikasi Azure Active Directory untuk sumber daya Immersive Reader yang ada, jika misalnya, Anda telah membuat sumber daya Immersive Reader di portal Microsoft Azure.

Untuk beberapa pelanggan, mungkin perlu membuat beberapa sumber daya Immersive Reader, untuk pengembangan vs. produksi, atau mungkin untuk beberapa wilayah berbeda tempat layanan Anda disebarkan. Untuk kasus tersebut, Anda dapat kembali dan menggunakan skrip beberapa kali untuk membuat sumber daya Immersive Reader yang berbeda dan mengonfigurasinya dengan izin Azure Active Directory.

Skrip didesain untuk menjadi fleksibel. Skrip pertama-tama akan mencari sumber daya Immersive Reader dan Azure Active Directory yang ada di langganan Anda, dan membuatnya hanya jika diperlukan bila belum ada. Jika ini pertama kalinya Anda membuat sumber daya Immersive Reader, skrip akan melakukan semua yang dibutuhkan. Jika Anda ingin menggunakan skrip hanya untuk mengonfigurasi Azure Active Directory untuk sumber daya Immersive Reader yang sudah ada yang dibuat di portal, skrip juga akan melakukannya. Skrip juga dapat digunakan untuk membuat dan mengonfigurasi beberapa sumber daya Immersive Reader.

Menyiapkan lingkungan PowerShell

  1. Mulai dengan membuka Azure Cloud Shell. Pastikan Azure Cloud Shell diatur ke PowerShell di menu turun 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="ImmersiveReaderAAD",
        [Parameter(Mandatory=$true)] [String] $AADAppIdentifierUri,
        [Parameter(Mandatory=$true)] [String] $AADAppClientSecret,
        [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 Azure Active Directory 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 Azure Active Directory app"
            $clientId = az ad app create --password $AADAppClientSecret --end-date "$AADAppClientSecretExpiration" --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv
    
            if (-not $clientId) {
                throw "Error: Failed to create Azure Active Directory app"
            }
            Write-Host "Azure Active Directory app created successfully."
            Write-Host "NOTE: To manage your Active Directory app client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Azure Active Directory -> App Registrations -> $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 "objectId" -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 "objectId" -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 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 an Azure AD token
        $tenantId = az account show --query "tenantId" -o tsv
    
        # Collect the information needed to obtain an Azure AD token into one object
        $result = @{}
        $result.TenantId = $tenantId
        $result.ClientId = $clientId
        $result.ClientSecret = $AADAppClientSecret
        $result.Subdomain = $ResourceSubdomain
    
        Write-Host "Success! " -ForegroundColor Green -NoNewline
        Write-Host "Save the following JSON object to a text file for future reference:"
        Write-Output (ConvertTo-Json $result)
    }
    
  3. Jalankan fungsi Create-ImmersiveReaderResource, berikan tempat penampung '<PARAMETER_VALUES>' di bawah ini dengan nilai Anda sendiri sebagaimana mestinya.

    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 '<AAD_APP_DISPLAY_NAME>' -AADAppIdentifierUri '<AAD_APP_IDENTIFIER_URI>' -AADAppClientSecret '<AAD_APP_CLIENT_SECRET>' -AADAppClientSecretExpiration '<AAD_APP_CLIENT_SECRET_EXPIRATION>'
    

    Perintah lengkap akan terlihat seperti berikut ini. Di sini kami telah 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 di atas dengan nilai Anda sendiri. Contoh ini memiliki nilai semu untuk '<PARAMETER_VALUES>' di atas. Anda akan berbeda, karena akan menemukan 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 'https://MyOrganizationImmersiveReaderAADApp'
        -AADAppClientSecret 'SomeStrongPassword'
        -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 berupa alfanumerik, dan boleh 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 boleh 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). Kunjungi halaman harga Azure Cognitive Services kami untuk mempelajari selengkapnya tentang setiap SKU yang tersedia. Parameter ini opsional jika sumber daya sudah ada.
    ResourceLocation Opsi: eastus, eastus2, southcentralus, westus, westus2, australiaeast, southeastasia, centralindia, japaneast, northeurope, uksouth, westeurope. 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, yang baru dengan nama ini akan 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 Azure Active Directory. Jika aplikasi Azure Active Directory yang ada tidak ditemukan, yang baru dengan nama ini akan dibuat. Parameter ini opsional jika aplikasi Azure Active Directory sudah ada.
    AADAppIdentifierUri URI untuk aplikasi Azure Active Directory. Jika aplikasi Azure Active Directory yang ada tidak ditemukan, yang baru dengan URI ini akan dibuat. Contohnya,https://immersivereaderaad-mycompany.
    AADAppClientSecret Kata sandi yang Anda buat yang akan digunakan nanti untuk mengautentikasi saat memperoleh token untuk meluncurkan Immersive Reader. Kata sandi harus setidaknya 16 karakter, mengandung setidaknya 1 karakter khusus, dan mengandung setidaknya 1 karakter numerik. Untuk mengelola rahasia klien aplikasi Azure Active Directory setelah Anda membuat sumber daya ini, kunjungi https://portal.azure.com dan buka Beranda -> Azure Active Directory -> Pendaftaran Aplikasi -> [AADAppDisplayName] -> Blade Sertifikat dan Rahasia -> Rahasia Klien (seperti yang ditunjukkan pada cuplikan layar "Kelola rahasia aplikasi Azure Active Directory Anda" di bawah).
    AADAppClientSecretExpiration Tanggal atau tanggalwaktu setelah [AADAppClientSecret] Anda akan kedaluwarsa (mis. '2020-12-31T11:59:59+00:00' atau '2020-12-31').

    Mengelola rahasia aplikasi Azure Active Directory Anda

    Sertifikat Portal Azure dan blade Rahasia

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

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

Langkah berikutnya