使用语音 SDK 的 Microsoft Entra 身份验证

项目
09/20/2024

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

本文介绍如何使用语音 SDK 的 Microsoft Entra 身份验证。学习如何：

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

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

创建语音资源

若要在 Azure 门户中创建语音资源，请参阅此快速入门。

为 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 创建自定义域名，请确认计算机具有 PowerShell 版本 7.x 或更高版本，其中包含 Azure PowerShell 模块版本 5.1.0 或更高版本。若要查看这些工具的版本，请执行以下步骤：

在 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 中的检查域可用性操作来确认域可用。

$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 参考命令，请安装 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 中的检查域可用性方法。

复制以下代码块，插入首选自定义域名，并保存到文件 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 标识客户端库。

下面是使用 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 标识来用租户 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")

查找在 Microsoft 标识平台代码示例中获取 Microsoft Entra 访问令牌的示例。

对于 Microsoft 标识平台客户端库不可用的编程语言，可以直接请求访问令牌。

获取语音资源 ID

需要语音资源 ID，以使用 Microsoft Entra 身份验证进行 SDK 调用。

注意

对于意向识别，请使用 LUIS 预测资源 ID。

Azure 门户
PowerShell

若要在 Azure 门户中获取资源 ID：

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

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

在 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、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber

对于 SpeechRecognizer、SpeechSynthesizer、IntentRecognizer 和 ConversationTranscriber 对象，请根据资源 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);

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

对于 TranslationRecognizer，请根据资源 ID 和 Microsoft Entra 访问令牌构建身份验证令牌，然后使用它来创建 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

若要将 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);

VoiceProfileClient 不可用于适用于 Python 的语音 SDK。

注意

ConversationTranslator 不支持 Microsoft Entra 身份验证。

通过

使用语音 SDK 的 Microsoft Entra 身份验证

创建语音资源

为 Microsoft Entra 身份验证配置语音资源

创建自定义域名

分配角色

获取 Microsoft Entra 访问令牌

获取语音资源 ID

创建语音 SDK 配置对象

SpeechRecognizer、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber

TranslationRecognizer

VoiceProfileClient

其他资源