Autenticazione di Microsoft Entra con Speech SDK

Quando si usa Speech SDK per accedere al servizio Voce, sono disponibili tre metodi di autenticazione: chiavi di servizio, token basato su chiave e ID Microsoft Entra. Questo articolo descrive come configurare una risorsa Voce e creare un oggetto di configurazione di Speech SDK per l'uso dell'ID Entra di Microsoft per l'autenticazione.

Questo articolo illustra come usare l'autenticazione di Microsoft Entra con Speech SDK. Scopri come:

• Creare una risorsa voce
• Configurare la risorsa Voce per l'autenticazione di Microsoft Entra
• Ottenere un token di accesso di Microsoft Entra
• Creare l'oggetto di configurazione dell'SDK appropriato.

Per altre informazioni sui token di accesso di Microsoft Entra, inclusa la durata dei token, vedere Token di accesso in Microsoft Identity Platform.

Creare una risorsa voce

Per creare una risorsa Voce nella portale di Azure, vedere Ottenere le chiavi per la risorsa

Configurare la risorsa Voce per l'autenticazione di Microsoft Entra

Per configurare la risorsa Voce per l'autenticazione di Microsoft Entra, creare un nome di dominio personalizzato e assegnare ruoli.

Creare un nome di dominio personalizzato

Seguire questa procedura per creare un nome di sottodominio personalizzato per i servizi di intelligenza artificiale di Azure per la risorsa Voce.

Attenzione

Quando si attiva un nome di dominio personalizzato, l'operazione non è reversibile. L'unico modo per tornare al nome dell'area consiste nel creare una nuova risorsa Voce.

Se la risorsa Voce ha molti modelli e progetti personalizzati associati creati tramite Speech Studio, è consigliabile provare la configurazione con una risorsa di test prima di modificare la risorsa usata nell'ambiente di produzione.

Azure portal

Per creare un nome di dominio personalizzato usando il portale di Azure, seguire questa procedura:

1. Passare al portale di Azure e accedere all'account Azure.

2. Selezionare la risorsa Voce necessaria.

3. Nel gruppo Gestione risorse nel riquadro sinistro selezionare Rete.

4. Nella scheda Firewall e reti virtuali selezionare Genera nome di dominio personalizzato. Viene visualizzato un nuovo pannello a destra con le istruzioni per creare un sottodominio personalizzato univoco per la risorsa.

5. Nel pannello Genera nome di dominio personalizzato immettere un nome di dominio personalizzato. Il dominio personalizzato completo sarà simile al seguente: https://{your custom name}.cognitiveservices.azure.com.

   Tenere presente che dopo aver creato un nome di dominio personalizzato, non può essere modificato.

   Dopo aver immesso il nome di dominio personalizzato, selezionare Salva.

6. Al termine dell'operazione, nel gruppo Gestione risorse selezionare Chiavi ed endpoint. Verificare che il nuovo nome endpoint della risorsa inizi in questo modo: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Per creare un nome di dominio personalizzato usando PowerShell, verificare che nel computer sia presente PowerShell versione 7.x o successiva con il modulo Azure PowerShell versione 5.1.0 o successiva. Per visualizzare le versioni di questi strumenti, seguire questa procedura:

1. In una finestra di PowerShell immettere:

   $PSVersionTable

   Verificare che il PSVersion valore sia 7,x o versione successiva. Per aggiornare PowerShell, seguire le istruzioni in Installazione di varie versioni di PowerShell.

2. In una finestra di PowerShell immettere:

   Get-Module -ListAvailable Az

   Se non viene visualizzato alcun elemento o se tale versione del modulo di Azure PowerShell è precedente alla 5.1.0, seguire le istruzioni riportate in Installare il modulo Azure PowerShell per eseguire l'aggiornamento.

Prima di procedere, eseguire Connect-AzAccount per creare una connessione con Azure.

Verificare che sia disponibile un nome di dominio personalizzato

Controllare se il dominio personalizzato che si vuole usare è disponibile. Il codice seguente conferma che il dominio è disponibile usando l'operazione Verifica disponibilità dominio nell'API REST dei servizi di intelligenza artificiale di Azure.

Nota

Il codice seguente non funzionerà in 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 il nome desiderato è disponibile, verrà visualizzata una risposta simile alla seguente:

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

Se il nome è già stato preso, verrà visualizzata la risposta seguente:

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

Creare il nome di dominio personalizzato

Per attivare un nome di dominio personalizzato per la risorsa Voce selezionata, usare il cmdlet Set-AzCognitiveServicesAccount .

Attenzione

Dopo aver eseguito correttamente il codice seguente, si creerà un nome di dominio personalizzato per la risorsa Voce. Tenere presente che questo nome non può essere modificato.

$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

Interfaccia della riga di comando di Azure

Prerequisiti

• Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido per Bash in Azure Cloud Shell.

  

• Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere con l'interfaccia della riga di comando di Azure.

  • Quando richiesto, installare l'estensione dell'interfaccia della riga di comando di Azure al primo uso. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.

  • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Questa sezione richiede la versione più recente dell'interfaccia della riga di comando di Azure. Se si usa Azure Cloud Shell, la versione più recente è già installata.

Verificare che il nome di dominio personalizzato sia disponibile

Controllare se il dominio personalizzato che si vuole usare è gratuito. Usare il metodo Check Domain Availability dall'API REST dei servizi di intelligenza artificiale di Azure.

Copiare il blocco di codice seguente, inserire il nome di dominio personalizzato preferito e salvare nel file subdomain.json.

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

Copiare il file nella cartella corrente o caricarlo in Azure Cloud Shell ed eseguire il comando seguente. Sostituire xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx con l'ID della sottoscrizione di 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 il nome desiderato è disponibile, verrà visualizzata una risposta simile alla seguente:

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

Se il nome è già stato preso, verrà visualizzata la risposta seguente:

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

Attivare un nome di dominio personalizzato

Per usare un nome di dominio personalizzato con la risorsa Voce selezionata, usare il comando az cognitiveservices account update .

Se l'account Azure ha una sola sottoscrizione attiva, è possibile ignorare questo passaggio. Selezionare la sottoscrizione di Azure che contiene la risorsa Voce. Sostituire xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx con l'ID della sottoscrizione di Azure.

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

Impostare il nome di dominio personalizzato sulla risorsa selezionata. Sostituire i valori dei parametri di esempio con quelli effettivi ed eseguire il comando seguente.

Attenzione

Dopo aver completato l'esecuzione del comando seguente, si creerà un nome di dominio personalizzato per la risorsa Voce. Tenere presente che questo nome non può essere modificato.

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

Assegnazione di ruoli

Per l'autenticazione di Microsoft Entra con le risorse voce, è necessario assegnare il ruolo Collaboratore voce servizi cognitivi o Speech User di Servizi cognitivi.

È possibile assegnare ruoli all'utente o all'applicazione usando il portale di Azure o PowerShell.

Ottenere un token di accesso di Microsoft Entra

Per ottenere un token di accesso Microsoft Entra in C#, usare la libreria client di identità di Azure.

Ecco un esempio di uso di Identità di Azure per ottenere un token di accesso Microsoft Entra da un browser interattivo:

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;

Il contesto del token deve essere impostato su "https://cognitiveservices.azure.com/.default".

Per ottenere un token di accesso Microsoft Entra in C++, usare la libreria client di identità di Azure.

Ecco un esempio di uso di Identità di Azure per ottenere un token di accesso Microsoft Entra con l'ID tenant, l'ID client e le credenziali del segreto client:

const std::string tenantId = "Your Tenant ID";
const std::string clientId = "Your Client ID";
const std::string clientSecret = "Your Client Secret";
const std::string tokenContext = "https://cognitiveservices.azure.com/.default";

Azure::Identity::ClientSecretCredential cred(tenantId,
    clientId,
    clientSecret,
    Azure::Identity::ClientSecretCredentialOptions());

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

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

Il contesto del token deve essere impostato su "https://cognitiveservices.azure.com/.default".

Per ottenere un token di accesso Microsoft Entra in Java, usare la libreria client di identità di Azure.

Ecco un esempio di uso di Identità di Azure per ottenere un token di accesso Microsoft Entra da un browser:

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

Il contesto del token deve essere impostato su "https://cognitiveservices.azure.com/.default".

Per ottenere un token di accesso Microsoft Entra in Java, usare la libreria client di identità di Azure.

Ecco un esempio di uso di Identità di Azure per ottenere un token di accesso Microsoft Entra da un browser interattivo:

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

Trovare esempi che ottengono un token di accesso Microsoft Entra negli esempi di codice di Microsoft Identity Platform.

Per i linguaggi di programmazione in cui non è disponibile una libreria client di Microsoft Identity Platform, è possibile richiedere direttamente un token di accesso.

Ottenere l'ID risorsa Voce

È necessario l'ID risorsa Voce per effettuare chiamate SDK usando l'autenticazione Microsoft Entra.

Nota

Per Riconoscimento finalità usare l'ID risorsa di stima LUIS.

Azure portal

Per ottenere l'ID risorsa nel portale di Azure:

1. Passare al portale di Azure e accedere all'account Azure.
2. Selezionare una risorsa voce.
3. Nel gruppo Gestione risorse nel riquadro sinistro selezionare Proprietà.
4. Copiare l'ID risorsa

PowerShell

Per ottenere l'ID risorsa con PowerShell, verificare di avere PowerShell versione 7.x o successiva con il modulo Azure PowerShell versione 5.1.0 o successiva. Per visualizzare le versioni di questi strumenti, seguire questa procedura:

1. In una finestra di PowerShell immettere:

   $PSVersionTable

   Verificare che il PSVersion valore sia 7,x o versione successiva. Per aggiornare PowerShell, seguire le istruzioni in Installazione di varie versioni di PowerShell.

2. In una finestra di PowerShell immettere:

   Get-Module -ListAvailable Az

   Se non viene visualizzato alcun elemento o se tale versione del modulo di Azure PowerShell è precedente alla 5.1.0, seguire le istruzioni riportate in Installare il modulo Azure PowerShell per eseguire l'aggiornamento.

Connect-AzAccount Eseguire ora per creare una connessione 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

Creare l'oggetto di configurazione di Speech SDK

Con un token di accesso Microsoft Entra è ora possibile creare un oggetto di configurazione di Speech SDK.

Il metodo di fornire il token e il metodo per costruire l'oggetto Speech SDK Config corrispondente varia in base all'oggetto in uso.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Per SpeechRecognizergli oggetti , SpeechSynthesizerIntentRecognizer, , ConversationTranscriber compilare il token di autorizzazione dall'ID risorsa e dal token di accesso Microsoft Entra e quindi usarlo per creare un SpeechConfig oggetto .

string resourceId = "Your Resource ID";
string aadToken = "Your Azure AD access token";
string region =  "Your Speech Region";

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

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

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and AAD 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 AAD 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 AAD access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)

TranslationRecognizer

TranslationRecognizerPer , compilare il token di autorizzazione dall'ID risorsa e dal token di accesso Microsoft Entra e quindi usarlo per creare un SpeechTranslationConfig oggetto .

string resourceId = "Your Resource ID";
string aadToken = "Your Azure AD access token";
string region =  "Your Speech Region";

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

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

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and AAD 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 AAD 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 AAD access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
translationConfig = SpeechTranslationConfig(auth_token=authorizationToken, region=region)

DialogService Connessione or

Per l'oggetto DialogServiceConnection , compilare il token di autorizzazione dall'ID risorsa e dal token di accesso di Microsoft Entra e quindi usarlo per creare un CustomCommandsConfigBotFrameworkConfig oggetto o .

string resourceId = "Your Resource ID";
string aadToken = "Your Azure AD access token";
string region =  "Your Speech Region";
string appId = "Your app ID";

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

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Azure AD access token";
std::string region = "Your Speech Region";
std::string appId = "Your app Id";

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

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

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and AAD access token.
String authorizationToken = "aad#" + resourceId + "#" + token;
CustomCommandsConfig dialogServiceConfig = CustomCommandsConfig.fromAuthorizationToken(appId, authorizationToken, region);

DialogService Connessione or non è attualmente supportato in Python

VoiceProfileClient

Per usare con l'autenticazione VoiceProfileClient Microsoft Entra, usare il nome di dominio personalizzato creato in precedenza.

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

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

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

std::string customDomainName = "Your Custom Name";
std::string aadToken = "Your Azure AD 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 AAD access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
speechConfig->SetAuthorizationToken(authorizationToken);

String aadToken = "Your Azure AD 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 AAD access token.
String authorizationToken = "aad#" + resourceId + "#" + token;

speechConfig.setAuthorizationToken(authorizationToken);

Non VoiceProfileClient è disponibile con Speech SDK per Python.

Nota

non ConversationTranslator supporta l'autenticazione di Microsoft Entra.