Autenticación de Microsoft Entra con el SDK de voz

Si se usa el SDK de voz para acceder al servicio de voz, hay tres métodos de autenticación disponibles: claves de servicio, un token basado en claves y Microsoft Entra ID. En este artículo se describe cómo configurar un recurso de voz y crear un objeto de configuración del SDK de voz para usar Microsoft Entra ID para la autenticación.

En este artículo se muestra cómo usar la autenticación de Microsoft Entra con el SDK de voz. Aprenderá a:

• Crear un recurso de voz.
• Configurar el recurso de voz para la autenticación de Microsoft Entra
• Obtener un token de acceso de Microsoft Entra
• Crear el objeto de configuración del SDK adecuado.

Para obtener más información sobre los tokens de acceso de Microsoft Entra, incluyendo la duración del token, visite Tokens de acceso en la Plataforma de identidad de Microsoft.

Creación de un recurso de voz

Para crear un recurso de voz en Azure Portal, consulte este inicio rápido.

Configurar el recurso de voz para la autenticación de Microsoft Entra

Para configurar un recurso de voz para la autenticación de Microsoft Entra, cree un nombre de dominio personalizado y asigne roles.

Creación de un nombre de dominio personalizado

Siga estos pasos para crear un nombre de subdominio personalizado para servicios de Azure AI para el recurso de Voz.

Precaución

Cuando se habilita un nombre de dominio personalizado, la operación no es reversible. La única manera de volver a establecer el nombre regional es crear un recurso de voz nuevo.

Si el recurso de voz tiene muchos modelos y proyectos personalizados asociados creados mediante Speech Studio, se recomienda encarecidamente probar la configuración en un recurso de prueba antes de modificar el usado en producción.

Azure Portal

Para crear un nombre de dominio personalizado desde Azure Portal, siga estos pasos:

1. Vaya a Azure Portal e inicie sesión con su cuenta de Azure.

2. Seleccione el recurso de voz necesario.

3. En el grupo Administración de recursos del panel izquierdo, seleccione Redes.

4. En la pestaña Firewalls y redes virtuales, seleccione Generate Custom Domain Name (Generar nombre de dominio personalizado). En el lado derecho aparece un panel con instrucciones para crear un subdominio personalizado único para el recurso.

5. En el panel Generate Custom Domain Name (Generar nombre de dominio personalizado), escriba un nombre de dominio personalizado. El dominio personalizado completo tiene el siguiente aspecto: https://{your custom name}.cognitiveservices.azure.com.

   Recuerde que después de crear un nombre de dominio personalizado, no se puede cambiar.

   Después de haber escrito su nombre de dominio personalizado, seleccione Guardar.

6. Una vez finalizada la operación, en el grupo Administración de recursos, seleccione Keys and Endpoint (Claves y punto de conexión). Confirme que el nuevo nombre del punto de conexión del recurso empieza de esta manera: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Para crear un nombre de dominio personalizado con PowerShell, confirme que el equipo tiene la versión 7.x o posterior de PowerShell con la versión 5.1.0 o posterior del módulo de Azure PowerShell. Para ver las versiones de estas herramientas, siga estos pasos:

1. En una ventana de PowerShell, escriba:

   $PSVersionTable

   Confirme que el valor de PSVersion es 7.x o posterior. Para actualizar PowerShell, siga las instrucciones de Instalación de distintas versiones de PowerShell.

2. En una ventana de PowerShell, escriba:

   Get-Module -ListAvailable Az

   Si no aparece nada, o si esa versión del módulo de Azure PowerShell es anterior a 5.1.0, siga las instrucciones de Instalación del módulo de Azure PowerShell para actualizarla.

Antes de continuar, ejecute Connect-AzAccount para crear una conexión con Azure.

Comprobación de que un nombre de dominio personalizado está disponible

Compruebe si el dominio personalizado que quiere usar está disponible. En el código siguiente se usa la operación Check Domain Availability de la API de REST de los servicios de Azure AI para confirmar que el dominio está disponible.

Nota:

El siguiente código no funcionará en 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

Si el nombre que quiere usar está disponible, recibirá una respuesta similar a la siguiente:

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

Si el nombre ya está en uso, obtendrá la siguiente respuesta:

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

Creación del nombre de dominio personalizado

Para activar un nombre de dominio personalizado para el recurso de voz seleccionado, use el cmdlet Set-AzCognitiveServicesAccount.

Precaución

Una vez que el código siguiente se ejecute correctamente, se creará un nombre de dominio personalizado para el recurso de voz. Recuerde que este nombre no se puede cambiar.

$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

CLI de Azure

Requisitos previos

• Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

  

• Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

  • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

  • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

  • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

En esta sección necesitará la versión más reciente de la CLI de Azure. Si usa Azure Cloud Shell, ya está instalada la versión más reciente.

Comprobación de que el nombre de dominio personalizado está disponible

Compruebe si el dominio personalizado que quiere utilizar está libre. Use el método Check Domain Availability de la API de REST de los servicios de Azure AI.

Copie el bloque de código siguiente, inserte el nombre de dominio personalizado que prefiera y guárdelo en el archivo subdomain.json.

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

Copie el archivo en la carpeta actual o cárguelo en Azure Cloud Shell y ejecute el siguiente comando. Reemplace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx con la identificación de su suscripción de 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

Si el nombre que quiere usar está disponible, recibirá una respuesta similar a la siguiente:

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

Si el nombre ya está en uso, obtendrá la siguiente respuesta:

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

Activación de un nombre de dominio personalizado

Para usar un nombre de dominio personalizado para el recurso de voz seleccionado, use el comando az cognitiveservices account update

(Si su cuenta de Azure solo tiene una suscripción activa, puede omitir este paso.) Seleccione la suscripción de Azure que contiene el recurso de Voz. Reemplace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx con la identificación de su suscripción de Azure.

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

Establezca el nombre de dominio personalizado en el recurso seleccionado. Reemplace los valores de ejemplo de los parámetros por los reales y ejecute el siguiente comando.

Precaución

Después de ejecutar correctamente el siguiente comando, se creará un nombre de dominio personalizado para el recurso de voz. Recuerde que este nombre no se puede cambiar.

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

Asignación de roles

Para la autenticación de Microsoft Entra con recursos de voz, es preciso que asigne los roles Colaborador de voz de Cognitive Services o Usuario de voz de Cognitive Services.

Se pueden asignar roles tanto al usuario como a la aplicación mediante Azure Portal o PowerShell.

Obtener un token de acceso de Microsoft Entra

Para obtener un token de acceso de Microsoft Entra en C#, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra desde un explorador interactivo:

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:

El contexto del token debe establecerse en "https://cognitiveservices.azure.com/.default".

Para obtener un token de acceso de Microsoft Entra en C++, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra con el identificador de inquilino, el identificador de cliente y las credenciales de secreto de 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:

El contexto del token debe establecerse en "https://cognitiveservices.azure.com/.default".

Para obtener un token de acceso de Microsoft Entra en Java, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra desde un explorador:

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:

El contexto del token debe establecerse en "https://cognitiveservices.azure.com/.default".

Para obtener un token de acceso de Microsoft Entra en Python, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra desde un explorador interactivo:

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

Busque ejemplos que obtengan un token de acceso de Microsoft Entra en la plataforma de identidad de Microsoft.

En el caso de los lenguajes de programación en los que no haya ninguna plataforma de identidad de Microsoft disponible, se puede solicitar directamente un token de acceso.

Obtención del identificador de recurso de Voz

Necesita el identificador de recurso de voz para realizar llamadas SDK mediante la autenticación de Microsoft Entra.

Nota:

En el caso de Reconocimiento de la intención, use el identificador de recursos de predicción de LUIS.

Azure Portal

Para obtener el identificador de recurso en Azure Portal:

1. Vaya a Azure Portal e inicie sesión con su cuenta de Azure.
2. Seleccione un recurso de Voz.
3. En el grupo Administración de recursos del panel izquierdo, seleccione Propiedades.
4. Copie el identificador de recurso.

PowerShell

Para obtener el identificador de recurso mediante PowerShell, confirme que tiene la versión 7.x de PowerShell, o cualquier versión posterior, con la versión 5.1.0 del módulo de Azure PowerShell, o cualquier versión posterior. Para ver las versiones de estas herramientas, siga estos pasos:

1. En una ventana de PowerShell, escriba:

   $PSVersionTable

   Confirme que el valor de PSVersion es 7.x o posterior. Para actualizar PowerShell, siga las instrucciones de Instalación de distintas versiones de PowerShell.

2. En una ventana de PowerShell, escriba:

   Get-Module -ListAvailable Az

   Si no aparece nada, o si esa versión del módulo de Azure PowerShell es anterior a 5.1.0, siga las instrucciones de Instalación del módulo de Azure PowerShell para actualizarla.

Ahora ejecute Connect-AzAccount para crear una conexión con 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

Creación del objeto de configuración del SDK de Voz

Con un token de acceso de Microsoft Entra, ahora se puede crear un objeto de configuración del SDK de voz.

El método de proporcionar el token y el método para construir el SDK de Voz correspondiente Config objeto varía según el objeto que use.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer y ConversationTranscriber

En el caso de los objetos SpeechRecognizer, SpeechSynthesizer, IntentRecognizer y ConversationTranscriber compile el token de autorización a partir del identificador de recurso y del token de acceso de Microsoft Entra y, después, úselo para crear un objeto SpeechConfig.

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)

TranslationRecognizer

En el caso de TranslationRecognizer, compile el token de autorización a partir del identificador de recurso y del token de acceso de Microsoft Entra y, después, úselo para crear un objeto SpeechTranslationConfig.

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 VoiceProfileClient con la autenticación de Microsoft Entra, utilice el nombre de dominio personalizado creado anteriormente.

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);

VoiceProfileClient no está disponible con el SDK de Voz para Python.

Nota:

El ConversationTranslator no admite la autenticación de Microsoft Entra.