Tam Ekran Okuyucu kaynağı oluşturma ve Microsoft Entra kimlik doğrulamayı yapılandırma

  • Makale

Bu makalede, sağlanan betiği kullanarak bir Tam Ekran Okuyucu kaynağının nasıl oluşturulacağı açıklanmaktadır. Bu betik, Microsoft Entra kimlik doğrulamayı da yapılandırıyor. İster bu betikle ister portalda olsun, bir Tam Ekran Okuyucu kaynağı her oluşturulduğunda Microsoft Entra izinleriyle yapılandırılması gerekir.

Betik, sizin için tüm gerekli Tam Ekran Okuyucu ve Microsoft Entra kaynaklarını oluşturur ve yapılandırr. Bununla birlikte, Azure portalında zaten oluşturduysanız mevcut bir Tam Ekran Okuyucu kaynağı için Microsoft Entra kimlik doğrulamasını da yapılandırabilirsiniz. Betik önce aboneliğinizdeki mevcut Tam Ekran Okuyucu ve Microsoft Entra kaynaklarını arar ve bunları yalnızca henüz yoksa oluşturur.

Bazı müşteriler için, geliştirme ve üretim için veya hizmetinizin dağıtıldığı farklı bölgeler için birden çok Tam Ekran Okuyucu kaynağı oluşturmanız gerekebilir. Bu gibi durumlarda, farklı Tam Ekran Okuyucu kaynakları oluşturmak ve bunları Microsoft Entra izinleriyle yapılandırmak için betiği birden çok kez kullanabilirsiniz.

İzinler

Azure aboneliğinizin listelenen Sahibi, bir Tam Ekran Okuyucu kaynağı oluşturmak ve Microsoft Entra kimlik doğrulamasını yapılandırmak için gerekli tüm izinlere sahiptir.

Sahip değilseniz, aşağıdaki kapsama özgü izinler gereklidir:

  • Katkıda bulunan. Azure aboneliğiyle ilişkilendirilmiş en az bir Katkıda Bulunan rolüne sahip olmanız gerekir:

    Screenshot of contributor built-in role description.

  • Uygulama Geliştirici. Microsoft Entra Id ile ilişkili en az bir Uygulama Geliştirici rolüne sahip olmanız gerekir:

    Screenshot of the developer built-in role description.

Daha fazla bilgi için bkz. Microsoft Entra yerleşik roller.

PowerShell kaynaklarını ayarlama

  1. Azure Cloud Shell'i açarak başlayın. Cloud Shell'in sol üstteki açılan listede veya yazarak pwshPowerShell olarak ayarlandığından emin olun.

  2. Aşağıdaki kod parçacığını kopyalayıp kabuğa yapıştırın.

    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. işlevini Create-ImmersiveReaderResourceçalıştırın ve< 'PARAMETER_VALUES>' yer tutucularını kendi değerlerinize uygun şekilde sağlayın.

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

    Tam komut aşağıdakine benzer şekilde görünür. Burada, komutun tamamını görebilmeniz için her parametreyi kendi satırına yerleştiriyoruz. Bu komutu olduğu gibi kopyalamayın veya kullanmayın. komutunu kopyalayın ve kendi değerlerinizle kullanın. Bu örnekte için <PARAMETER_VALUES>sahte değerler vardır. Bu değerler için kendi adlarınızla geldiğinizde sizinki farklı olabilir.

    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'
    Parametre Açıklamalar
    SubscriptionName Tam Ekran Okuyucu kaynağınız için kullanılacak Azure aboneliğinin adı. Kaynak oluşturmak için bir aboneliğiniz olmalıdır.
    ResourceName Alfasayısal olmalıdır ve ilk veya son karakter olmadığı sürece - öğesini içerebilir-. Uzunluk 63 karakteri aşamaz.
    ResourceSubdomain Tam Ekran Okuyucu kaynağınız için özel bir alt etki alanı gereklidir. Alt etki alanı SDK tarafından okuyucuyu başlatmak için Tam Ekran Okuyucu hizmeti çağrılırken kullanılır. Alt etki alanı genel olarak benzersiz olmalıdır. Alt etki alanı alfasayısal olmalıdır ve ilk veya son karakter olmadığı sürece - öğesini içerebilir-. Uzunluk 63 karakteri aşamaz. Kaynak zaten varsa bu parametre isteğe bağlıdır.
    ResourceSKU Seçenekler: S0 (Standart katman) veya S1 (Eğitim/Kar Amacı Gütmeyen kuruluşlar). Kullanılabilir SKU'lar hakkında daha fazla bilgi edinmek için Azure yapay zeka hizmetleri fiyatlandırma sayfamızı ziyaret edin. Kaynak zaten varsa bu parametre isteğe bağlıdır.
    ResourceLocation Seçenekler: australiaeast, brazilsouth, , canadacentral, centralindia, centralus, eastasia, eastus, eastus2, francecentral, germanywestcentral, japanwestjapaneast, jioindiawestkoreacentral, southafricanorthnortheuropesouthcentralusnorthcentralusnorwayeastsoutheastasia, swedencentral, switzerlandnorth, , switzerlandwest, uaenorth, , uksouth, , westcentraluswesteuropewestuswestus2westus3 Kaynak zaten varsa bu parametre isteğe bağlıdır.
    ResourceGroupName Kaynaklar abonelikler içindeki kaynak gruplarında oluşturulur. Mevcut bir kaynak grubunun adını belirtin. Kaynak grubu henüz yoksa, bu ada sahip yeni bir grup oluşturulur.
    ResourceGroupLocation Kaynak grubunuz yoksa, grubun oluşturulacağı konumu sağlamanız gerekir. Konumların listesini bulmak için komutunu çalıştırın az account list-locations. Döndürülen sonucun name özelliğini (boşluksuz) kullanın. Kaynak grubunuz zaten varsa bu parametre isteğe bağlıdır.
    AADAppDisplayName Microsoft Entra uygulamasının görünen adı. Mevcut bir Microsoft Entra uygulaması bulunamazsa, bu ada sahip yeni bir uygulama oluşturulur. Microsoft Entra uygulaması zaten varsa bu parametre isteğe bağlıdır.
    AADAppIdentifierUri Microsoft Entra uygulaması için URI. Mevcut bir Microsoft Entra uygulaması bulunamazsa, bu URI'ye sahip yeni bir uygulama oluşturulur. Örneğin, api://MyOrganizationImmersiveReaderAADApp. Burada, doğrulanmış etki alanlarını kullanmanın Microsoft Entra ilkesiyle uyumluluk için varsayılan Microsoft Entra URI şeması ön ekini api:// kullanıyoruz.
    AADAppClientSecretExpiration Microsoft Entra Uygulama İstemciSi Gizli Anahtarınızın (parola) süresinin sona erdiği tarih veya tarih saat (örneğin, '2020-12-31T11:59:59+00:00' veya '2020-12-31'). Bu işlev sizin için bir istemci gizli dizisi oluşturur.

    Bu kaynağı oluşturduktan sonra Microsoft Entra uygulaması istemci gizli dizilerinizi yönetmek için Azure portalını ziyaret edin ve Giriş ->Microsoft Entra Kimliği ->Uygulama Kayıtları -> (uygulamanız) [AADAppDisplayName] ->Sertifikalar ve Gizli Diziler bölümü ->İstemci Gizli Dizileri bölümüne gidin.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. JSON çıkışını daha sonra kullanmak üzere bir metin dosyasına kopyalayın. Çıkış aşağıdaki gibi görünmelidir.

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

Sonraki adım

Tam Ekran Okuyucu başlatma