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:
Desenvolvedor de Aplicativos. Você precisa ter pelo menos uma função de desenvolvedor de aplicativos associada no Microsoft Entra ID:
Para obter mais informações, veja Funções incorporadas do Microsoft Entra.
Configurar recursos do PowerShell
Comece abrindo o Azure Cloud Shell. Verifique se o Cloud Shell está definido como PowerShell no menu suspenso superior esquerdo ou digitando
pwsh.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 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 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 SubscriptionName Nome da assinatura do Azure a ser usada para seu recurso do Leitor Imersivo. Você deve ter uma assinatura para criar um recurso. ResourceName 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) ouS1(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.ResourceLocation Opções: , , , , centralindiacentralus,westus3eastus2westeuropewestcentralusuksouthuaenorthswitzerlandwestswitzerlandnorthswedencentralsoutheastasiakoreacentralnorthcentralusjapanwestnortheuropegermanywestcentralnorwayeasteastussouthafricanortheastasiawestus2westussouthcentralusjioindiawestfrancecentraljapaneast.canadacentralbrazilsouthaustraliaeastEste parâmetro é 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 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.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. 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 doapi://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 do cliente para você. Para gerenciar seus segredos de cliente de aplicativo Microsoft Entra depois de criar este recurso, visite o portal do Azure e vá para Início ->ID do Microsoft Entra ->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 ser semelhante à seguinte.
{ "TenantId": "...", "ClientId": "...", "ClientSecret": "...", "Subdomain": "..." }
