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 de Leitura Avançada e do Microsoft Entra necessários 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 procura os recursos existentes de Leitura Avançada e do Microsoft Entra na sua assinatura e os cria somente se ainda não existem.
Para alguns clientes, pode ser necessário criar vários recursos de Leitura Avançada, para desenvolvimento versus produção, ou talvez para regiões diferentes em que o seu serviço está implantado. 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:
Desenvolvedor de Aplicativo. Você precisa ter pelo menos uma função de Desenvolvedor de Aplicativos associada no Microsoft Entra ID:
Para obter mais informações, confira Funções internas do Microsoft Entra.
Configurar recursos do PowerShell
Comece abrindo o Azure Cloud Shell. Verifique se Cloud Shell está definido como PowerShell no menu suspenso superior esquerdo ou digitando
pwsh.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 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) }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 SubscriptionName Nome da assinatura do Azure a ser usada para o recurso Leitura Avançada. Você deve ter uma assinatura para criar um recurso. ResourceName 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 Leitura Avançada para iniciar 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) ouS1(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.ResourceLocation 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.ResourceGroupName 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. ResourceGroupLocation 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ãoapi://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.
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": "..." }
