Microsoft Entra 身份验证与语音 SDK 结合使用

使用语音 SDK 访问语音服务时，可以使用三种身份验证方法：服务密钥、基于密钥的令牌和Microsoft Entra ID。本文介绍如何配置 AI Services 资源并创建语音 SDK 配置对象，以使用Microsoft Entra ID进行身份验证。

本文介绍如何将Microsoft Entra身份验证与语音 SDK 配合使用。您将会学习如何：

创建 AI 服务资源
配置语音资源用于Microsoft Entra身份验证
获取Microsoft Entra访问令牌
创建适当的 SDK 配置对象。

若要详细了解 Microsoft Entra 访问令牌（包括令牌生存期），请访问 Microsoft 标识平台中的访问令牌。

创建 AI 服务资源

若要在 Azure 门户中创建 AI Services 资源，请参阅本快速入门。

配置用于 Microsoft Entra 身份验证的语音资源

若要配置语音资源进行Microsoft Entra身份验证，请创建自定义域名并分配角色。

创建自定义域名

按照以下步骤为 Azure AI 服务的语音资源创建自定义子域名。

注意

启用自定义域名时，此操作不可逆。返回区域名称的唯一方法是创建一个新的语音资源。

如果语音资源具有大量通过 Speech Studio 创建的关联自定义模型和项目，则强烈建议在修改生产中使用的资源之前，使用测试资源尝试配置。

若要使用 Azure 门户创建自定义域名，请执行以下步骤：

转到 Azure 门户并登录到Azure帐户。
选择所需语音资源。
在左窗格的“资源管理”组中，选择“网络” 。
在“防火墙和虚拟网络”选项卡上，选择“生成自定义域名” 。一个新的右面板随即出现，其中包含有关为资源创建唯一自定义子域的说明。
在“生成自定义域名”面板中，输入自定义域名。完整自定义域会如下所示：https://{your custom name}.cognitiveservices.azure.cn。

请记住，创建自定义域名后，无法更改域名。

输入自定义域名后，请选择“保存”。
操作完成后，在“资源管理”组中，选择“密钥和终结点” 。确认资源的新终结点名称以这种方式开始：https://{your custom name}.cognitiveservices.azure.cn。

若要使用 PowerShell 创建自定义域名，请使用 Azure PowerShell 模块版本 5.1.0 或更高版本确认计算机具有 PowerShell 7.x 或更高版本。若要查看这些工具的版本，请执行以下步骤：

在 PowerShell 窗口中，输入：

$PSVersionTable

确认 PSVersion 值为 7.x 或更高。若要升级 PowerShell，请按照安装各种版本的 PowerShell 中的说明进行操作。
在 PowerShell 窗口中，输入：

Get-Module -ListAvailable Az

如果未显示任何内容，或者Azure PowerShell模块的版本低于 5.1.0，请按照安装 Azure PowerShell 模块的说明进行升级。

在继续之前，请运行 Connect-AzAccount -Environment AzureChinaCloud 以创建与Azure的连接。

验证自定义域名是否可用

检查要使用的自定义域是否可用。以下代码确认域在 Azure AI 服务 REST API 中使用 Check 域可用性操作可用。

$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.chinacloudapi.cn/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

如果所需名称可用，你会看到如下所示的响应：

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

如果名称已被占用，你会看到以下响应：

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

创建自定义域名

若要为所选语音资源启用自定义域名，请使用 Set-AzCognitiveServicesAccount cmdlet。

注意

在以下代码成功运行后，你会为语音资源创建自定义域名。请记住，此名称无法更改。

$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 引用命令，install Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行Azure CLI。
- 如果使用本地安装，请使用 az login 命令登录到Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅Azure CLI登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展的详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

本部分需要最新版本的Azure CLI。

验证自定义域名是否可用

检查要使用的自定义域是否免费。使用 Azure AI 服务 REST API 中的 Check 域可用性方法。

复制以下代码块，插入首选自定义域名，并保存到文件 subdomain.json。

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

运行以下命令。将 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 替换为Azure订阅 ID。

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

如果所需名称可用，你会看到如下所示的响应：

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

如果名称已被占用，你会看到以下响应：

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

启用自定义域名

若要为所选语音资源使用自定义域名，请使用 az cognitiveservices account update 命令。

（如果Azure帐户只有一个活动订阅，则可以跳过此步骤。选择包含语音资源的Azure订阅。将 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 替换为Azure订阅 ID。

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

将自定义域名设置为所选资源。将示例参数值替换为实际参数值，并运行以下命令。

注意

成功执行以下命令后，你会为语音资源创建自定义域名。请记住，此名称无法更改。

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

分配角色

若要使用语音资源Microsoft Entra身份验证，需要分配认知服务语音参与者或认知服务语音用户角色。

可以使用 Azure 门户或 PowerShell 向用户或应用程序分配角色。

获取Microsoft Entra访问令牌

若要在 C# 中获取Microsoft Entra访问令牌，请使用 Azure Identity Client Library。

下面是使用 Azure 标识从交互式浏览器获取Microsoft Entra访问令牌的示例：

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

注意

必须将令牌上下文设置为 "https://cognitiveservices.azure.cn/.default""。

若要在 C++ 中获取Microsoft Entra访问令牌，请使用 Azure 标识客户端库。

下面是使用 Azure Identity 凭证，包括租户 ID、客户端 ID 和客户端密码，获取 Microsoft Entra 访问令牌的示例：

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

Azure::Identity::DefaultAzureCredential();

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

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

注意

必须将令牌上下文设置为 "https://cognitiveservices.azure.cn/.default""。

若要在 Java 中获取Microsoft Entra访问令牌，请使用 Azure 标识客户端库。

下面是使用 Azure 标识从浏览器获取Microsoft Entra访问令牌的示例：

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

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

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

注意

必须将令牌上下文设置为 "https://cognitiveservices.azure.cn/.default""。

若要在 Python 中获取Microsoft Entra访问令牌，请使用 Azure 标识客户端库。

下面是使用 Azure 标识从交互式浏览器获取Microsoft Entra访问令牌的示例：

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

获取语音资源 ID

在尚不支持 Entra ID 的情况下，您需要使用您的语音资源 ID 和 Microsoft Entra 身份验证来进行 SDK 调用。

Azure 门户
PowerShell

若要在Azure门户中获取资源 ID，请执行以下操作：

转到 Azure 门户并登录到Azure帐户。
选择 AI 服务资源。
在左窗格的“资源管理”组中，选择“属性”。
复制资源 ID

若要使用 PowerShell 获取资源 ID，请使用 Azure PowerShell 模块 5.1.0 或更高版本确认 PowerShell 版本为 7.x 或更高版本。若要查看这些工具的版本，请执行以下步骤：

在 PowerShell 窗口中，输入：

$PSVersionTable

确认 PSVersion 值为 7.x 或更高。若要升级 PowerShell，请按照安装各种版本的 PowerShell 中的说明进行操作。
在 PowerShell 窗口中，输入：

Get-Module -ListAvailable Az

如果未显示任何内容，或者Azure PowerShell模块的版本低于 5.1.0，请按照安装 Azure PowerShell 模块的说明进行升级。

现在运行 Connect-AzAccount 以创建与Azure的连接。

Connect-AzAccount -Environment AzureChinaCloud
$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

创建语音 SDK 配置对象

使用Microsoft Entra访问令牌，现在可以创建语音 SDK 配置对象。

提供令牌的方法和构造相应语音 SDK Config 对象的方法因要使用的对象而异。

SpeechRecognizer、SourceLanguageRecognizer、ConversationTranscriber

对于 SpeechRecognizer、SourceLanguageRecognizer 和 ConversationTranscriber 对象，使用相应的 TokenCredential 实例进行身份验证，并使用包含您的自定义域的终结点来创建 SpeechConfig 对象。

TokenCredential browserCredential = new InteractiveBrowserCredential();

// Define the custom domain endpoint for your Speech resource.
var endpoint = "https://{your custom name}.cognitiveservices.azure.cn/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
var speechConfig = SpeechConfig.FromEndpoint(new Uri(endpoint), browserCredential);

翻译识别器

对于 TranslationRecognizer 对象，请使用相应的 TokenCredential 实例进行身份验证，以及包含自定义域的终结点来创建 SpeechTranslationConfig 对象。

TokenCredential browserCredential = new InteractiveBrowserCredential();

// Define the custom domain endpoint for your Speech resource
var endpoint = "https://{your custom name}.cognitiveservices.azure.cn/";

// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
var speechConfig = SpeechTranslationConfig.FromEndpoint(new Uri(endpoint), browserCredential);

语音合成器

对于 SpeechSynthesizer 对象，请从资源 ID 和Microsoft Entra访问令牌生成授权令牌，然后使用它创建 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);

SpeechRecognizer、SpeechSynthesizer、ConversationTranscriber

对于 SpeechRecognizer、SpeechSynthesizer、ConversationTranscriber 对象，从资源 ID 和Microsoft Entra访问令牌生成授权令牌，然后使用它创建 SpeechConfig 对象。

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

翻译识别器

对于 TranslationRecognizer，请从资源 ID 和Microsoft Entra访问令牌生成授权令牌，然后使用它创建 SpeechTranslationConfig 对象。

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

SpeechRecognizer、ConversationTranscriber

对于 SpeechRecognizer 和 ConversationTranscriber 对象，请使用适当的 TokenCredential 实例进行身份验证，并使用包含您自定义域的终结点来创建 SpeechConfig 对象。

TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();

// Define the custom domain endpoint for your Speech resource.
String endpoint = "https://{your custom name}.cognitiveservices.azure.cn/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
SpeechConfig speechConfig = SpeechConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);

翻译识别器

对于 TranslationRecognizer 对象，请使用相应的 TokenCredential 实例进行身份验证，以及包含自定义域的终结点来创建 SpeechTranslationConfig 对象。

TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();

// Define the custom domain endpoint for your Speech resource
String endpoint = "https://{your custom name}.cognitiveservices.azure.cn/";

// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
SpeechConfig speechConfig = SpeechTranslationConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);

语音合成器

对于 SpeechSynthesizer，对象从资源 ID 和Microsoft Entra访问令牌生成授权令牌，然后使用它创建 SpeechConfig 对象。

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

SpeechRecognizer、ConversationTranscriber

browserCredential = InteractiveBrowserCredential()

// Define the custom domain endpoint for your Speech resource.
custom_endpoint = "https://{your custom name}.cognitiveservices.azure.cn/"

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
speechConfig = SpeechConfig(token_credential=credential, endpoint=custom_endpoint)

翻译识别器 (TranslationRecognizer)

对于 TranslationRecognizer 对象，请使用相应的 TokenCredential 实例进行身份验证，以及包含自定义域的终结点来创建 SpeechTranslationConfig 对象。

browserCredential = InteractiveBrowserCredential()

// Define the custom domain endpoint for your Speech resource
custom_endpoint = "https://{your custom name}.cognitiveservices.azure.cn/"

// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
speechTranslationConfig = SpeechTranslationConfig(token_credential=credential, endpoint=custom_endpoint)

语音合成器

对于 SpeechSynthesizer 对象，请从资源 ID 和Microsoft Entra访问令牌生成授权令牌，然后使用它创建 SpeechConfig 对象。

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)

VoiceProfileClient

若要将 VoiceProfileClient 用于Microsoft Entra身份验证，请使用上面创建的自定义域名。

string customDomainName = "Your Custom Name";
string hostName = $"https://{customDomainName}.cognitiveservices.azure.cn/";
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.cn/");

// 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.cn/";
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);

Python 语音 SDK 不支持 VoiceProfileClient。

注意

ConversationTranslator不支持Microsoft Entra身份验证。

Last updated on 2026-04-17

通过

Microsoft Entra 身份验证与语音 SDK 结合使用

创建 AI 服务资源

配置用于 Microsoft Entra 身份验证的语音资源

创建自定义域名

分配角色

获取Microsoft Entra访问令牌

更多示例

获取语音资源 ID

创建语音 SDK 配置对象

SpeechRecognizer、SourceLanguageRecognizer、ConversationTranscriber

翻译识别器

语音合成器

SpeechRecognizer、SpeechSynthesizer、ConversationTranscriber

翻译识别器

SpeechRecognizer、ConversationTranscriber

翻译识别器

语音合成器

SpeechRecognizer、ConversationTranscriber

翻译识别器 (TranslationRecognizer)

语音合成器

VoiceProfileClient

其他资源