Microsoft Entra-autentisering med Speech SDK

När du använder Speech SDK för att komma åt Speech-tjänsten finns det tre tillgängliga autentiseringsmetoder: tjänstnycklar, en nyckelbaserad token och Microsoft Entra-ID. Den här artikeln beskriver hur du konfigurerar en Speech-resurs och skapar ett Speech SDK-konfigurationsobjekt för att använda Microsoft Entra-ID för autentisering.

Den här artikeln visar hur du använder Microsoft Entra-autentisering med Speech SDK. Du lär dig att:

• Skapa en Speech-resurs
• Konfigurera Speech-resursen för Microsoft Entra-autentisering
• Hämta en Microsoft Entra-åtkomsttoken
• Skapa rätt SDK-konfigurationsobjekt.

Mer information om Microsoft Entra-åtkomsttoken, inklusive tokenlivslängd, finns i Åtkomsttoken i Microsofts identitetsplattform.

Skapa en Speech-resurs

Information om hur du skapar en Speech-resurs i Azure Portal finns i den här snabbstarten.

Konfigurera Speech-resursen för Microsoft Entra-autentisering

Om du vill konfigurera din Speech-resurs för Microsoft Entra-autentisering skapar du ett anpassat domännamn och tilldelar roller.

Skapa ett anpassat domännamn

Följ de här stegen för att skapa ett anpassat underdomännamn för Azure AI-tjänster för din Speech-resurs.

Varning

När du aktiverar ett anpassat domännamn är åtgärden inte reversibel. Det enda sättet att gå tillbaka till det regionala namnet är att skapa en ny Speech-resurs.

Om din Speech-resurs har många associerade anpassade modeller och projekt som skapats via Speech Studio rekommenderar vi starkt att du provar konfigurationen med en testresurs innan du ändrar resursen som används i produktion.

Azure-portalen

Följ dessa steg för att skapa ett anpassat domännamn med hjälp av Azure Portal:

1. Gå till Azure-portalen och logga in på ditt Azure-konto.

2. Välj den talresurs som krävs.

3. I gruppen Resurshantering i den vänstra rutan väljer du Nätverk.

4. På fliken Brandväggar och virtuella nätverk väljer du Generera anpassat domännamn. En ny högerpanel visas med instruktioner för att skapa en unik anpassad underdomän för resursen.

5. I panelen Generera anpassat domännamn anger du ett anpassat domännamn. Din fullständiga anpassade domän ser ut så här: https://{your custom name}.cognitiveservices.azure.com.

   Kom ihåg att när du har skapat ett anpassat domännamn kan det inte ändras.

   När du har angett ditt anpassade domännamn väljer du Spara.

6. När åtgärden är klar väljer du Nycklar och slutpunkt i resurshanteringsgruppen. Bekräfta att resursens nya slutpunktsnamn börjar så här: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Om du vill skapa ett anpassat domännamn med hjälp av PowerShell kontrollerar du att datorn har PowerShell version 7.x eller senare med Azure PowerShell-modulen version 5.1.0 eller senare. Följ dessa steg för att se versionerna av dessa verktyg:

1. I ett PowerShell-fönster anger du:

   $PSVersionTable

   Bekräfta att värdet PSVersion är 7.x eller senare. Om du vill uppgradera PowerShell följer du anvisningarna i Installera olika versioner av PowerShell.

2. I ett PowerShell-fönster anger du:

   Get-Module -ListAvailable Az

   Om ingenting visas, eller om den versionen av Azure PowerShell-modulen är tidigare än 5.1.0, följer du anvisningarna i Installera Azure PowerShell-modulen för att uppgradera.

Innan du fortsätter kör Connect-AzAccount du för att skapa en anslutning till Azure.

Kontrollera att ett anpassat domännamn är tillgängligt

Kontrollera om den anpassade domän som du vill använda är tillgänglig. Följande kod bekräftar att domänen är tillgänglig med hjälp av åtgärden Kontrollera domäntillgänglighet i REST-API:et för Azure AI-tjänster.

Kommentar

Följande kod fungerar inte i 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

Om önskat namn är tillgängligt visas ett svar som liknar detta:

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

Om namnet redan har tagits visas följande svar:

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

Skapa ditt anpassade domännamn

Om du vill aktivera ett anpassat domännamn för den valda Speech-resursen använder du cmdleten Set-AzCognitiveServicesAccount .

Varning

När följande kod har körts skapar du ett anpassat domännamn för din Speech-resurs. Kom ihåg att det här namnet inte kan ändras.

$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

Azure CLI

Förutsättningar

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Det här avsnittet kräver den senaste versionen av Azure CLI. Om du använder Azure Cloud Shell är den senaste versionen redan installerad.

Kontrollera att det anpassade domännamnet är tillgängligt

Kontrollera om den anpassade domän som du vill använda är kostnadsfri. Använd metoden Kontrollera domäntillgänglighet från REST-API:et för Azure AI-tjänster.

Kopiera följande kodblock, infoga det anpassade domännamnet och spara i filen subdomain.json.

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

Kopiera filen till den aktuella mappen eller ladda upp den till Azure Cloud Shell och kör följande kommando. Ersätt xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx med ditt Azure-prenumerations-ID.

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

Om önskat namn är tillgängligt visas ett svar som liknar detta:

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

Om namnet redan har tagits visas följande svar:

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

Aktivera ett anpassat domännamn

Om du vill använda ett anpassat domännamn med den valda Speech-resursen använder du kommandot az cognitiveservices account update .

(Om ditt Azure-konto bara har en aktiv prenumeration kan du hoppa över det här steget.) Välj den Azure-prenumeration som innehåller Speech-resursen. Ersätt xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx med ditt Azure-prenumerations-ID.

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

Ange det anpassade domännamnet till den valda resursen. Ersätt exempelparametervärdena med de faktiska och kör följande kommando.

Varning

När du har kört följande kommando skapar du ett anpassat domännamn för din Speech-resurs. Kom ihåg att det här namnet inte kan ändras.

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

Tilldela roller

För Microsoft Entra-autentisering med Speech-resurser måste du tilldela rollen Cognitive Services Speech-deltagare eller Cognitive Services Speech-användare .

Du kan tilldela roller till användaren eller programmet med hjälp av Azure Portal eller PowerShell.

Hämta en Microsoft Entra-åtkomsttoken

Om du vill hämta en Microsoft Entra-åtkomsttoken i C# använder du Azure Identity Client Library.

Här är ett exempel på hur du använder Azure Identity för att hämta en Microsoft Entra-åtkomsttoken från en interaktiv webbläsare:

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;

Kommentar

Tokenkontexten måste anges till "https://cognitiveservices.azure.com/.default".

Om du vill hämta en Microsoft Entra-åtkomsttoken i C++använder du Azure Identity Client Library.

Här är ett exempel på hur du använder Azure Identity för att hämta en Microsoft Entra-åtkomsttoken med ditt klient-ID, klient-ID och autentiseringsuppgifter för klienthemligheter:

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

Kommentar

Tokenkontexten måste anges till "https://cognitiveservices.azure.com/.default".

Om du vill hämta en Microsoft Entra-åtkomsttoken i Java använder du Azure Identity Client Library.

Här är ett exempel på hur du använder Azure Identity för att hämta en Microsoft Entra-åtkomsttoken från en webbläsare:

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

Kommentar

Tokenkontexten måste anges till "https://cognitiveservices.azure.com/.default".

Om du vill hämta en Microsoft Entra-åtkomsttoken i Python använder du Azure Identity Client Library.

Här är ett exempel på hur du använder Azure Identity för att hämta en Microsoft Entra-åtkomsttoken från en interaktiv webbläsare:

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

Hitta exempel som hämtar en Microsoft Entra-åtkomsttoken i Microsofts identitetsplattform kodexempel.

För programmeringsspråk där ett Microsofts identitetsplattform klientbibliotek inte är tillgängligt kan du begära en åtkomsttoken direkt.

Hämta resurs-ID för Tal

Du behöver ditt Speech-resurs-ID för att göra SDK-anrop med Microsoft Entra-autentisering.

Kommentar

Använd ditt LUIS Prediction-resurs-ID för avsiktsigenkänning.

Azure-portalen

Så här hämtar du resurs-ID:t i Azure Portal:

1. Gå till Azure-portalen och logga in på ditt Azure-konto.
2. Välj en Speech-resurs.
3. I gruppen Resurshantering i den vänstra rutan väljer du Egenskaper.
4. Kopiera resurs-ID: t

PowerShell

Om du vill hämta resurs-ID:t med PowerShell kontrollerar du att du har PowerShell version 7.x eller senare med Azure PowerShell-modulen version 5.1.0 eller senare. Följ dessa steg för att se versionerna av dessa verktyg:

1. I ett PowerShell-fönster anger du:

   $PSVersionTable

   Bekräfta att värdet PSVersion är 7.x eller senare. Om du vill uppgradera PowerShell följer du anvisningarna i Installera olika versioner av PowerShell.

2. I ett PowerShell-fönster anger du:

   Get-Module -ListAvailable Az

   Om ingenting visas, eller om den versionen av Azure PowerShell-modulen är tidigare än 5.1.0, följer du anvisningarna i Installera Azure PowerShell-modulen för att uppgradera.

Connect-AzAccount Kör nu för att skapa en anslutning till 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

Skapa speech SDK-konfigurationsobjektet

Med en Microsoft Entra-åtkomsttoken kan du nu skapa ett Speech SDK-konfigurationsobjekt.

Metoden för att tillhandahålla token och metoden för att konstruera motsvarande Speech SDK-objekt Config varierar beroende på vilket objekt du använder.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

För SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber objekt skapar du auktoriseringstoken från resurs-ID:t och Microsoft Entra-åtkomsttoken och använder den sedan för att skapa ett SpeechConfig objekt.

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

TranslationRecognizerFör skapar du auktoriseringstoken från resurs-ID:t och Microsoft Entra-åtkomsttoken och använder den sedan för att skapa ett SpeechTranslationConfig objekt.

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

Om du vill använda VoiceProfileClient med Microsoft Entra-autentisering använder du det anpassade domännamnet som skapades ovan.

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 Är inte tillgängligt med Speech SDK för Python.

Kommentar

ConversationTranslator Stöder inte Microsoft Entra-autentisering.