Compartilhar via

Crie um recurso de Leitura Avançada e configure a autenticação do Microsoft Entra

Este artigo explica como criar um recurso de Leitura Avançada usando o script fornecido. Esse script também configura a autenticação do Microsoft Entra. Cada vez que um recurso de Leitura Avançada é criado, seja com esse script ou no portal, ele precisa ser configurado com permissões do Microsoft Entra.

O script cria e configura todos os recursos necessários do Leitor Imersivo e do Microsoft Entra para você. No entanto, você também pode configurar a autenticação do Microsoft Entra para um recurso de Leitura Avançada existente se já criou um no portal do Azure. O script primeiro verifica se já existem recursos do Leitor Imersivo e do Microsoft Entra na sua assinatura, e os cria apenas se eles ainda não existirem.

Para alguns clientes, pode ser necessário criar vários recursos do Immersive Reader, tanto para desenvolvimento quanto para produção, ou talvez para diferentes regiões onde o seu serviço está implementado. Nesses casos, você pode voltar e usar o script várias vezes para criar diferentes recursos de Leitura Avançada e configurá-los com permissões do Microsoft Entra.

Permissões

O Proprietário listado de sua assinatura do Azure tem todas as permissões necessárias para criar um recurso de Leitura Avançada 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:

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

    Captura de tela da descrição da função incorporada de colaborador.

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

    Captura de tela da descrição da função integrada do desenvolvedor.

Para obter mais informações, confira Funções internas do Microsoft Entra.

Configurar recursos do PowerShell

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

  2. Copie e cole o seguinte snippet 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, fornecendo os espaços reservados "<PARAMETER_VALUES>" com 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 é semelhante ao seguinte. Aqui, colocamos cada parâmetro em uma linha própria para maior clareza, para que você possa ver todo o comando. Não copie nem use esse comando no momento. Copie e use o comando acima com seus próprios valores. Este exemplo tem valores fictícios para os <PARAMETER_VALUES>. O seu poderá ser diferente, pois você criará nomes próprios 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
    Nome da Assinatura Nome da assinatura do Azure a ser usada para seu recurso Leitor Imersivo. Você deve ter uma assinatura para criar um recurso.
    NomeDoRecurso Precisa ter caracteres alfanuméricos e pode conter -, desde que o - não seja o primeiro nem o último caractere. O comprimento não pode exceder 63 caracteres.
    ResourceSubdomain Um subdomínio personalizado é necessário para o recurso Leitura Avançada. O subdomínio é usado pelo SDK ao chamar o serviço Immersive Reader para acessar o Leitor. O subdomínio deve ser globalmente exclusivo. O subdomínio precisa ter caracteres alfanuméricos e pode conter -, desde que - não seja o primeiro nem o último caractere. O comprimento não pode exceder 63 caracteres. Esse parâmetro será opcional se o recurso já existir.
    ResourceSKU Opções: S0 (camada Standard) ou S1 (organizações de educação/organizações sem fins lucrativos). Para saber mais sobre cada SKU disponível, visite nossa página de preços dos serviços de IA do Azure. Esse parâmetro será 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. Esse parâmetro será 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 grupo de recursos não existir, você precisará fornecer um local no qual criar o grupo. Para encontrar uma lista de locais, execute az account list-locations. Use a propriedade Name (sem espaços) do resultado retornado. Esse parâmetro será opcional se o grupo de recursos já existir.
    AADAppDisplayName O nome de exibição do aplicativo Microsoft Entra. Se um aplicativo existente do Microsoft Entra não for encontrado, um novo com esse nome será criado. Esse parâmetro será opcional se o aplicativo do Microsoft Entra já existir.
    AADAppIdentifierUri O URI do aplicativo do 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 de esquema padrão api:// do URI do Microsoft Entra para compatibilidade com a política do Microsoft Entra de uso de domínios verificados.
    AADAppClientSecretExpiration A data ou o datetime após a qual o seu Segredo do Cliente (senha) do Aplicativo do Microsoft Entra expira (por exemplo, “2020-12-31T11:59:59+00:00” ou “2020-12-31”). Essa função cria um segredo do cliente para você.

    Para gerenciar seus segredos do cliente do aplicativo do Microsoft Entra depois de criar esse recurso, visite o portal do Azure e acesse Página Inicial->Microsoft Entra ID->Registros de Aplicativo-> (seu aplicativo) [AADAppDisplayName] ->seção Certificados e Segredos->seção Segredos do Cliente.

    Captura de tela 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 parecer com o seguinte.

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

Próxima etapa

Como iniciar o Leitor Imersivo

  • Last updated on