Partilhar via

Criar um recurso de Leitor Imersivo e configurar a autenticação do Microsoft Entra

Este artigo explica como criar um recurso de leitor imersivo usando o script fornecido. Este script também configura a autenticação do Microsoft Entra. Cada vez que um recurso Immersive Reader é criado, seja com este script ou no portal, ele deve ser configurado com permissões do Microsoft Entra.

O script cria e configura todos os recursos necessários do Immersive Reader e do Microsoft Entra para você. No entanto, você também pode configurar a autenticação do Microsoft Entra para um recurso de Leitor Imersivo existente, se já tiver criado um no portal do Azure. O script primeiro procura os recursos existentes do Immersive Reader e do Microsoft Entra em sua assinatura e os cria somente se ainda não existirem.

Para alguns clientes, pode ser necessário criar vários recursos do Immersive Reader, para desenvolvimento versus produção, ou talvez para diferentes regiões onde seu serviço é implantado. Para esses casos, você pode voltar e usar o script várias vezes para criar diferentes recursos do Immersive Reader e configurá-los com permissões do Microsoft Entra.

Permissões

O Proprietário listado da sua assinatura do Azure tem todas as permissões necessárias para criar um recurso de Leitor Imersivo e configurar a autenticação do Microsoft Entra.

Se você não for um proprietário, as seguintes permissões específicas do escopo serão necessárias:

  • Contribuidor: Você precisa ter pelo menos uma função de Colaborador associada à assinatura do Azure:

    Captura de ecrã da descrição da função incorporada do colaborador.

  • Desenvolvedor de Aplicativos. Você precisa ter pelo menos uma função de desenvolvedor de aplicativos associada no Microsoft Entra ID:

    Captura de ecrã da descrição da função incorporada do programador.

Para obter mais informações, veja Funções incorporadas do Microsoft Entra.

Configurar recursos do PowerShell

  1. Comece abrindo o Azure Cloud Shell. Verifique se o Cloud Shell está definido como PowerShell no menu suspenso superior esquerdo ou digitando pwsh.

  2. Copie e cole o seguinte trecho de código no 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 a 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. Execute a função Create-ImmersiveReaderResource, substituindo os espaços reservados '<PARAMETER_VALUES>' pelos seus próprios valores, conforme apropriado.

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

    O comando completo se parece com o seguinte. Aqui colocamos cada parâmetro em sua própria linha para clareza, para que você possa ver todo o comando. Não copie nem use este comando no estado em que se encontra. Copie e use o comando com seus próprios valores. Este exemplo tem valores fictícios para o <PARAMETER_VALUES>. O seu pode ser diferente, pois você cria seus próprios nomes para esses valores.

    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'
    Parâmetro Comentários
    NomeDaAssinatura Nome da assinatura do Azure a ser usada para seu recurso do Leitor Imersivo. Você deve ter uma assinatura para criar um recurso.
    Nome do Recurso Deve ser alfanumérico e pode conter -, desde que o - não seja o primeiro ou o último caractere. O comprimento não pode exceder 63 caracteres.
    Subdomínio de Recursos É necessário um subdomínio personalizado para o recurso Leitor Imersivo. O subdomínio é usado pelo SDK ao chamar o serviço Leitor Imersivo para iniciar o Leitor. O subdomínio deve ser globalmente exclusivo. O subdomínio deve ser alfanumérico e pode conter -, desde que o - não seja o primeiro ou o último caractere. O comprimento não pode exceder 63 caracteres. Este parâmetro é opcional se o recurso já existir.
    ResourceSKU Opções: S0 (Nível padrão) ou S1 (Educação/Organizações sem fins lucrativos). Para saber mais sobre cada SKU disponível, visite nossa página de preços de serviços de IA do Azure. Este parâmetro é opcional se o recurso já existir.
    Localização de Recursos Opções: 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. Este parâmetro é opcional se o recurso já existir.
    NomeDoGrupoDeRecursos Os recursos são criados em grupos de recursos dentro de assinaturas. Forneça o nome de um grupo de recursos existente. Se o grupo de recursos ainda não existir, um novo com esse nome será criado.
    LocalizaçãoDoGrupoDeRecursos Se o seu grupo de recursos não existir, você precisará fornecer um local para criar o grupo. Para encontrar uma lista de locais, execute az account list-locations. Use a propriedade name (sem espaços) do resultado retornado. Este parâmetro é opcional se o seu grupo de recursos já existir.
    Nome de Exibição do Aplicação AAD O nome de exibição da aplicação Microsoft Entra. Se um aplicativo existente do Microsoft Entra não for encontrado, um novo com esse nome será criado. Este parâmetro é opcional se o aplicativo Microsoft Entra já existir.
    AADAppIdentifierUri O URI do aplicativo Microsoft Entra. Se um aplicativo existente do Microsoft Entra não for encontrado, um novo com esse URI será criado. Por exemplo, api://MyOrganizationImmersiveReaderAADApp. Aqui estamos usando o prefixo padrão do esquema de URI do Microsoft Entra para compatibilidade com a política do api:// Microsoft Entra de usar domínios verificados.
    AADAppClientSecretExpiration A data ou data/hora após a qual o segredo do cliente do aplicativo Microsoft Entra (senha) expira (por exemplo, '2020-12-31T11:59:59+00:00' ou '2020-12-31'). Esta função cria um segredo de cliente para si.

    Para gerir os segredos de cliente da aplicação Microsoft Entra depois de criar este recurso, visite o portal do Azure e vá para Início ->ID do Microsoft Entra ->Registros de Aplicativos -> (o seu aplicativo) [AADAppDisplayName] ->Seção Certificados e Segredos ->Seção Segredos de Cliente.

    Captura de ecrã do painel Certificados e Segredos do portal do Azure.

  4. Copie a saída JSON em um arquivo de texto para uso posterior. A saída deve ser semelhante à seguinte.

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

Próximo passo

Como iniciar o Immersive Reader

  • Last updated on