Autenticação do Microsoft Entra com o SDK de Fala

Artigo
09/09/2024

Ao usar o SDK de Fala para acessar o serviço de Fala, há três métodos de autenticação disponíveis: chaves de serviço, um token baseado em chave e ID do Microsoft Entra. Este artigo descreve como configurar um recurso de fala e criar um objeto de configuração do SDK de fala para usar a ID do Microsoft Entra para autenticação.

Este artigo mostra como usar a autenticação do Microsoft Entra com o SDK de fala. Sabe como:

Criar um recurso de Fala
Configurar o recurso de Fala para autenticação do Microsoft Entra
Obter um de acesso do Microsoft Entra
Crie o objeto de configuração SDK apropriado.

Para saber mais sobre os tokens de acesso do Microsoft Entra, incluindo o tempo de vida do token, visite Tokens do Access na plataforma de identidade da Microsoft.

Criar um recurso de Fala

Para criar um recurso de Fala no portal do Azure, consulte este início rápido.

Configurar o recurso de Fala para autenticação do Microsoft Entra

Para configurar seu recurso de fala para autenticação do Microsoft Entra, crie um nome de domínio personalizado e atribua funções.

Criar um nome de domínio personalizado

Siga estas etapas para criar um nome de subdomínio personalizado para os serviços de IA do Azure para seu recurso de Fala.

Atenção

Quando você ativa um nome de domínio personalizado, a operação não é reversível. A única maneira de voltar ao nome regional é criar um novo recurso de fala.

Se o recurso de Fala tiver muitos modelos personalizados associados e projetos criados por meio do Speech Studio, é altamente recomendável tentar a configuração com um recurso de teste antes de modificar o recurso usado na produção.

Para criar um nome de domínio personalizado usando o portal do Azure, siga estas etapas:

Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.
Selecione o recurso de fala necessário.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Rede.
Na guia Firewalls e redes virtuais, selecione Gerar nome de domínio personalizado. Um novo painel direito é exibido com instruções para criar um subdomínio personalizado exclusivo para seu recurso.
No painel Gerar nome de domínio personalizado, insira um nome de domínio personalizado. Seu domínio personalizado completo será parecido com: https://{your custom name}.cognitiveservices.azure.com.

Lembre-se de que, depois de criar um nome de domínio personalizado, ele não pode ser alterado.

Depois de inserir seu nome de domínio personalizado, selecione Salvar.
Após a conclusão da operação, no grupo Gerenciamento de recursos, selecione Chaves e Ponto de extremidade. Confirme se o novo nome do ponto de extremidade do seu recurso começa desta forma: https://{your custom name}.cognitiveservices.azure.com.

Para criar um nome de domínio personalizado usando o PowerShell, confirme se seu computador tem o PowerShell versão 7.x ou posterior com o módulo do Azure PowerShell versão 5.1.0 ou posterior. Para ver as versões dessas ferramentas, siga estas etapas:

Em uma janela do PowerShell, digite:

$PSVersionTable

Confirme se o PSVersion valor é 7.x ou posterior. Para atualizar o PowerShell, siga as instruções em Instalando várias versões do PowerShell.
Em uma janela do PowerShell, digite:

Get-Module -ListAvailable Az

Se nada aparecer, ou se essa versão do módulo do Azure PowerShell for anterior à 5.1.0, siga as instruções em Instalar o módulo do Azure PowerShell para atualizar.

Antes de continuar, execute Connect-AzAccount para criar uma conexão com o Azure.

Verifique se um nome de domínio personalizado está disponível

Verifique se o domínio personalizado que você deseja usar está disponível. O código a seguir confirma que o domínio está disponível usando a operação Verificar Disponibilidade do Domínio na API REST dos serviços do Azure AI.

Nota

O código a seguir não funcionará no Azure Cloud Shell.

$subscriptionId = "Your Azure subscription Id"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
Set-AzContext -SubscriptionId $subscriptionId

# Prepare the OAuth token to use in the request to the Azure AI services REST API.
$Context = Get-AzContext
$AccessToken = (Get-AzAccessToken -TenantId $Context.Tenant.Id).Token
$token = ConvertTo-SecureString -String $AccessToken -AsPlainText -Force

# Prepare and send the request to the Azure AI services REST API.
$uri = "https://management.azure.com/subscriptions/" + $subscriptionId + `
    "/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18"
$body = @{
subdomainName = $subdomainName
type = "Microsoft.CognitiveServices/accounts"
}
$jsonBody = $body | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/json" -Authentication Bearer `
    -Token $token -Body $jsonBody | Format-List

Se o nome desejado estiver disponível, você verá uma resposta como esta:

isSubdomainAvailable : True
reason               :
type                 :
subdomainName        : my-custom-name

Se o nome já tiver sido usado, você verá a seguinte resposta:

isSubdomainAvailable : False
reason               : Sub domain name 'my-custom-name' is already used. Please pick a different name.
type                 :
subdomainName        : my-custom-name

Crie o seu nome de domínio personalizado

Para ativar um nome de domínio personalizado para o recurso de Fala selecionado, use o cmdlet Set-AzCognitiveServicesAccount .

Atenção

Depois que o código a seguir for executado com êxito, você criará um nome de domínio personalizado para seu recurso de fala. Lembre-se que este nome não pode ser alterado.

$resourceGroup = "Resource group name where Speech resource is located"
$speechResourceName = "Your Speech resource name"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
$subscriptionId = "Your Azure subscription Id"
Set-AzContext -SubscriptionId $subscriptionId

# Set the custom domain name to the selected resource.
# WARNING: THIS CANNOT BE CHANGED OR UNDONE!
Set-AzCognitiveServicesAccount -ResourceGroupName $resourceGroup `
    -Name $speechResourceName -CustomSubdomainName $subdomainName

Pré-requisitos

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Esta seção requer a versão mais recente da CLI do Azure. Se você estiver usando o Azure Cloud Shell, a versão mais recente já está instalada.

Verifique se o nome de domínio personalizado está disponível

Verifique se o domínio personalizado que você deseja usar é gratuito. Use o método Verificar Disponibilidade de Domínio da API REST dos serviços de IA do Azure.

Copie o seguinte bloco de código, insira seu nome de domínio personalizado preferido e salve no arquivo subdomain.json.

{
    "subdomainName": "custom domain name",
    "type": "Microsoft.CognitiveServices/accounts"
}

Copie o arquivo para sua pasta atual ou carregue-o no Azure Cloud Shell e execute o seguinte comando. Substitua xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx pelo seu ID da subscrição do Azure.

az rest --method post --url "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18" --body @subdomain.json

Se o nome desejado estiver disponível, você verá uma resposta como esta:

{
  "isSubdomainAvailable": true,
  "reason": null,
  "subdomainName": "my-custom-name",
  "type": null
}

Se o nome já tiver sido usado, você verá a seguinte resposta:

{
  "isSubdomainAvailable": false,
  "reason": "Sub domain name 'my-custom-name' is already used. Please pick a different name.",
  "subdomainName": "my-custom-name",
  "type": null
}

Ativar um nome de domínio personalizado

Para usar um nome de domínio personalizado com o recurso Speech selecionado, use o comando az cognitiveservices account update .

(Se sua conta do Azure tiver apenas uma assinatura ativa, você poderá ignorar esta etapa.) Selecione a assinatura do Azure que contém o recurso de Fala. Substitua xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx pelo seu ID da subscrição do Azure.

az account set --subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Defina o nome de domínio personalizado para o recurso selecionado. Substitua os valores dos parâmetros de exemplo pelos reais e execute o seguinte comando.

Atenção

Após a execução bem-sucedida do comando a seguir, você criará um nome de domínio personalizado para seu recurso de fala. Lembre-se que este nome não pode ser alterado.

az cognitiveservices account update --name my-speech-resource-name --resource-group my-resource-group-name --custom-domain my-custom-name

Atribuir funções

Para autenticação do Microsoft Entra com recursos de Fala, você precisa atribuir a função de Colaborador de Fala dos Serviços Cognitivos ou Usuário de Fala dos Serviços Cognitivos.

Você pode atribuir funções ao usuário ou aplicativo usando o portal do Azure ou o PowerShell.

Obter um de acesso do Microsoft Entra

Para obter um token de acesso do Microsoft Entra em C#, use a Biblioteca de Cliente do Azure Identity.

Veja um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra de um navegador interativo:

TokenRequestContext context = new Azure.Core.TokenRequestContext(new string[] { "https://cognitiveservices.azure.com/.default" });
InteractiveBrowserCredential browserCredential = new InteractiveBrowserCredential();
var browserToken = browserCredential.GetToken(context);
string aadToken = browserToken.Token;

Nota

O contexto do token deve ser definido como "https://cognitiveservices.azure.com/.default".

Para obter um token de acesso do Microsoft Entra em C++, use a Biblioteca de Cliente do Azure Identity.

Eis um exemplo de utilização da Identidade do Azure para obter um token de acesso do Microsoft Entra com o seu ID de inquilino, ID de cliente e credenciais de segredo do cliente:

const std::string tokenContext = "https://cognitiveservices.azure.com/.default";

Azure::Identity::DefaultAzureCredential();

Azure::Core::Credentials::TokenRequestContext context;
context.Scopes.push_back(tokenContext);

auto token = cred.GetToken(context, Azure::Core::Context());

Nota

O contexto do token deve ser definido como "https://cognitiveservices.azure.com/.default".

Para obter um token de acesso do Microsoft Entra em Java, use a Biblioteca de Cliente do Azure Identity.

Veja um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra de um navegador:

TokenRequestContext context = new TokenRequestContext();
context.addScopes("https://cognitiveservices.azure.com/.default");

InteractiveBrowserCredentialBuilder builder = new InteractiveBrowserCredentialBuilder();
InteractiveBrowserCredential browserCredential = builder.build();

AccessToken browserToken = browserCredential.getToken(context).block();
String token = browserToken.getToken();

Nota

O contexto do token deve ser definido como "https://cognitiveservices.azure.com/.default".

Para obter um token de acesso do Microsoft Entra em Python, use a Biblioteca de Cliente do Azure Identity.

Veja um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra de um navegador interativo:

from azure.identity import  InteractiveBrowserCredential
ibc = InteractiveBrowserCredential()
aadToken = ibc.get_token("https://cognitiveservices.azure.com/.default")

Encontre exemplos que obtêm um token de acesso do Microsoft Entra em exemplos de código da plataforma de identidade da Microsoft.

Para linguagens de programação em que uma biblioteca de cliente da plataforma de identidade da Microsoft não está disponível, você pode solicitar diretamente um token de acesso.

Obter o ID do recurso de Fala

Você precisa de sua ID de recurso de fala para fazer chamadas SDK usando a autenticação do Microsoft Entra.

Nota

Para reconhecimento de intenção, use seu ID de recurso de previsão LUIS.

Portal do Azure
PowerShell

Para obter a ID do recurso no portal do Azure:

Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.
Selecione um recurso de fala.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Propriedades.
Copie o ID do recurso

Para obter a ID do recurso usando o PowerShell, confirme se você tem o PowerShell versão 7.x ou posterior com o módulo do Azure PowerShell versão 5.1.0 ou posterior. Para ver as versões dessas ferramentas, siga estas etapas:

Em uma janela do PowerShell, digite:

$PSVersionTable

Confirme se o PSVersion valor é 7.x ou posterior. Para atualizar o PowerShell, siga as instruções em Instalando várias versões do PowerShell.
Em uma janela do PowerShell, digite:

Get-Module -ListAvailable Az

Se nada aparecer, ou se essa versão do módulo do Azure PowerShell for anterior à 5.1.0, siga as instruções em Instalar o módulo do Azure PowerShell para atualizar.

Agora execute Connect-AzAccount para criar uma conexão com o Azure.

Connect-AzAccount
$subscriptionId = "Your Azure subscription Id"
$resourceGroup = "Resource group name where Speech resource is located"
$speechResourceName = "Your Speech resource name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
Set-AzContext -SubscriptionId $subscriptionId

# Get the Speech resource 
$resource = Get-AzCognitiveServicesAccount -Name $speechResourceName -ResourceGroupName $resourceGroup

# Get the resource ID:
$resourceId = resource.Id

Criar o objeto de configuração do SDK de Fala

Com um token de acesso do Microsoft Entra, agora você pode criar um objeto de configuração do SDK de fala.

O método de fornecimento do token e o método para construir o objeto Speech SDK Config correspondente varia de acordo com o objeto que você está usando.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Para SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber objetos, crie o token de autorização a partir da ID do recurso e do token de acesso do Microsoft Entra e use-o para criar um SpeechConfig objeto.

string resourceId = "Your Resource ID";
string aadToken = "Your Microsoft Entra access token";
string region =  "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
var speechConfig = SpeechConfig.FromAuthorizationToken(authorizationToken, region);

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Microsoft Entra access token";
std::string region = "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
auto speechConfig = SpeechConfig::FromAuthorizationToken(authorizationToken, region);

String resourceId = "Your Resource ID";
String region = "Your Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;
SpeechConfig speechConfig = SpeechConfig.fromAuthorizationToken(authorizationToken, region);

resourceId = "Your Resource ID"
region = "Your Region"
# You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)

TraduçãoRecognizer

Para o TranslationRecognizer, crie o token de autorização a partir da ID do recurso e do token de acesso do Microsoft Entra e use-o para criar um SpeechTranslationConfig objeto.

string resourceId = "Your Resource ID";
string aadToken = "Your Microsoft Entra access token";
string region =  "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
var speechConfig = SpeechTranslationConfig.FromAuthorizationToken(authorizationToken, region);

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Microsoft Entra access token";
std::string region = "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
auto speechConfig = SpeechTranslationConfig::FromAuthorizationToken(authorizationToken, region);

String resourceId = "Your Resource ID";
String region = "Your Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;
SpeechTranslationConfig translationConfig = SpeechTranslationConfig.fromAuthorizationToken(authorizationToken, region);

resourceId = "Your Resource ID"
region = "Your Region"

# You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
translationConfig = SpeechTranslationConfig(auth_token=authorizationToken, region=region)

VoiceProfileClient

Para usar a autenticação com o VoiceProfileClient Microsoft Entra, use o nome de domínio personalizado criado acima.

string customDomainName = "Your Custom Name";
string hostName = $"https://{customDomainName}.cognitiveservices.azure.com/";
string token = "Your Microsoft Entra access token";

var config =  SpeechConfig.FromHost(new Uri(hostName));

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
config.AuthorizationToken = authorizationToken;

std::string customDomainName = "Your Custom Name";
std::string aadToken = "Your Microsoft Entra access token";

auto speechConfig = SpeechConfig::FromHost("https://" + customDomainName + ".cognitiveservices.azure.com/");

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
speechConfig->SetAuthorizationToken(authorizationToken);

String aadToken = "Your Microsoft Entra access token";
String customDomainName = "Your Custom Name";
String hostName = "https://" + customDomainName + ".cognitiveservices.azure.com/";
SpeechConfig speechConfig = SpeechConfig.fromHost(new URI(hostName));

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;

speechConfig.setAuthorizationToken(authorizationToken);

O VoiceProfileClient não está disponível com o Speech SDK for Python.

Nota

O ConversationTranslator não suporta a autenticação do Microsoft Entra.

Partilhar via

Autenticação do Microsoft Entra com o SDK de Fala

Criar um recurso de Fala

Configurar o recurso de Fala para autenticação do Microsoft Entra

Criar um nome de domínio personalizado

Verifique se um nome de domínio personalizado está disponível

Crie o seu nome de domínio personalizado

Pré-requisitos

Verifique se o nome de domínio personalizado está disponível

Ativar um nome de domínio personalizado

Atribuir funções

Obter um de acesso do Microsoft Entra

Obter o ID do recurso de Fala

Criar o objeto de configuração do SDK de Fala

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

TraduçãoRecognizer

VoiceProfileClient

Comentários

Recursos adicionais