Vytvoření prostředku Asistivní čtečka a konfigurace ověřování Microsoft Entra

  • Článek

Tento článek vysvětluje, jak vytvořit prostředek Asistivní čtečka pomocí poskytnutého skriptu. Tento skript také nakonfiguruje ověřování Microsoft Entra. Při každém vytvoření prostředku Asistivní čtečka bez ohledu na to, jestli je tento skript nebo na portálu, musí být nakonfigurovaný s oprávněními Microsoft Entra.

Skript pro vás vytvoří a nakonfiguruje všechny potřebné Asistivní čtečka a prostředky Microsoft Entra. Ověřování Microsoft Entra ale můžete nakonfigurovat také pro existující prostředek Asistivní čtečka, pokud jste ho už vytvořili na webu Azure Portal. Skript nejprve hledá existující prostředky Asistivní čtečka a Microsoft Entra ve vašem předplatném a vytvoří je pouze v případě, že ještě neexistují.

Pro některé zákazníky může být potřeba vytvořit několik Asistivní čtečka prostředků, pro vývoj a produkční prostředí nebo pro různé oblasti, ve kterých je vaše služba nasazená. V těchto případech se můžete vrátit a použít skript několikrát k vytvoření různých Asistivní čtečka prostředků a jejich konfiguraci s oprávněními Microsoft Entra.

Oprávnění

Uvedený vlastník vašeho předplatného Azure má všechna požadovaná oprávnění k vytvoření prostředku Asistivní čtečka a konfiguraci ověřování Microsoft Entra.

Pokud nejste vlastníkem, vyžadují se následující oprávnění specifická pro obor:

  • Přispěvatel. Musíte mít přiřazenou alespoň roli Přispěvatel k předplatnému Azure:

    Screenshot of contributor built-in role description.

  • Vývojář aplikací. Musíte mít přiřazenou alespoň roli vývojáře aplikací v ID Microsoft Entra:

    Screenshot of the developer built-in role description.

Další informace najdete v tématu Předdefinované role Microsoft Entra.

Nastavení prostředků PowerShellu

  1. Začněte otevřením Azure Cloud Shellu. Ujistěte se, že je Cloud Shell nastavený na PowerShell v levém horním rozevíracím seznamu nebo zadáním pwsh.

  2. Zkopírujte následující fragment kódu a vložte ho do prostředí.

    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. Spusťte funkci Create-ImmersiveReaderResourcea podle potřeby zadejte zástupné symboly PARAMETER_VALUES>< vlastními hodnotami.

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

    Celý příkaz vypadá přibližně takto. Tady každý parametr umístíme na vlastní řádek, abyste mohli přehledně vidět celý příkaz. Tento příkaz nekopírujte ani nepoužívejte tak, jak je. Zkopírujte a použijte příkaz s vlastními hodnotami. Tento příklad obsahuje fiktivní hodnoty pro <PARAMETER_VALUES>. Vaše hodnoty se můžou lišit, když se objevíte s vlastními názvy těchto hodnot.

    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'
    Parametr Komentáře
    SubscriptionName Název předplatného Azure, které se má použít pro váš prostředek Asistivní čtečka Abyste mohli vytvořit prostředek, musíte mít předplatné.
    ResourceName Musí být alfanumerické a může obsahovat -znak , pokud - není prvním nebo posledním znakem. Délka nesmí překročit 63 znaků.
    ResourceSubdomain Pro váš prostředek Asistivní čtečka je potřeba vlastní subdoména. Subdoménu používá sada SDK při volání služby Asistivní čtečka ke spuštění čtečky. Subdoména musí být globálně jedinečná. Subdoména musí být alfanumerická a může obsahovat -, pokud - není prvním nebo posledním znakem. Délka nesmí překročit 63 znaků. Tento parametr je volitelný, pokud prostředek již existuje.
    ResourceSKU Možnosti: S0 (úroveň Standard) nebo S1 (organizace pro vzdělávací organizace nebo neziskové organizace). Další informace o každé dostupné skladové poště najdete na stránce s cenami služeb Azure AI. Tento parametr je volitelný, pokud prostředek již existuje.
    ResourceLocation Možnosti: australiaeast, brazilsouth, canadacentral, , centraluscentralindia, eastasia, eastusfrancecentraleastus2germanywestcentral, , southeastasiasouthcentralusswedencentralsouthafricanorthnorwayeastswitzerlandnorthwestcentralusuksouthwesteuropeuaenorthwestuswestus2japanwestkoreacentralwestus3jioindiawestnorthcentralusnortheuropeswitzerlandwestjapaneast Tento parametr je volitelný, pokud prostředek již existuje.
    ResourceGroupName Prostředky se vytvářejí ve skupinách prostředků v rámci předplatných. Zadejte název existující skupiny prostředků. Pokud skupina prostředků ještě neexistuje, vytvoří se nový s tímto názvem.
    ResourceGroupLocation Pokud vaše skupina prostředků neexistuje, musíte zadat umístění, ve kterém chcete skupinu vytvořit. Pokud chcete najít seznam umístění, spusťte az account list-locationspříkaz . Použijte vlastnost name (bez mezer) vráceného výsledku. Tento parametr je volitelný, pokud už vaše skupina prostředků existuje.
    AADAppDisplayName Zobrazovaný název aplikace Microsoft Entra. Pokud se nenajde existující aplikace Microsoft Entra, vytvoří se nový s tímto názvem. Tento parametr je volitelný, pokud již aplikace Microsoft Entra existuje.
    AADAppIdentifierUri Identifikátor URI pro aplikaci Microsoft Entra. Pokud se nenajde existující aplikace Microsoft Entra, vytvoří se nový s tímto identifikátorem URI. Například api://MyOrganizationImmersiveReaderAADApp. Tady používáme výchozí předponu api:// schématu Microsoft Entra URI pro zajištění kompatibility se zásadami Microsoft Entra pro používání ověřených domén.
    AADAppClientSecretExpiration Datum nebo datum a čas, po kterém vyprší platnost tajného klíče klienta aplikace Microsoft Entra (heslo) (například 2020-12-31T11:59:59+00:00 nebo 2020-12-31). Tato funkce za vás vytvoří tajný klíč klienta.

    Pokud chcete spravovat tajné kódy klienta aplikace Microsoft Entra po vytvoření tohoto prostředku, přejděte na web Azure Portal a přejděte na domovskou stránku ->Microsoft Entra ID ->App Registrations -> (vaše aplikace) [AADAppDisplayName] ->Certifikáty a tajné kódy oddílu ->Tajné kódy klienta.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Zkopírujte výstup JSON do textového souboru pro pozdější použití. Výstup by měl vypadat následovně.

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

Další krok

Jak spustit Asistivní čtečka