使用語音 SDK 進行 Microsoft Entra 驗證

使用語音 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 入口網站 建立自定義功能變數名稱，請遵循下列步驟：

1. 前往 Azure 入口網站並登入 Azure 帳戶。

2. 選取所需的語音資源。

3. 在左窗格的 [ 資源管理 ] 群組中，選取 [ 網络]。

4. 在 [ 防火牆和虛擬網络] 索引標籤 上，選取 [ 產生自定義功能變數名稱]。 新的右面板隨即出現，其中包含為資源建立唯一自定義子域的指示。

5. 在 [ 產生自定義功能變數名稱] 面板中，輸入自訂功能變數名稱。 您的完整自定義網域看起來會像： https://{your custom name}.cognitiveservices.azure.com。

   請記住，在您建立自定義功能變數名稱之後，就無法變更它。

   輸入自訂功能變數名稱之後，請選取 [ 儲存]。

6. 作業完成後，在 [資源管理] 群組中，選取 [金鑰] 和 [端點]。 確認資源的新端點名稱會以下列方式啟動： https://{your custom name}.cognitiveservices.azure.com。

PowerShell

若要使用 PowerShell 建立自定義功能變數名稱，請使用 Azure PowerShell 模組 5.1.0 版或更新版本確認您的電腦具有 PowerShell 7.x 版或更新版本。 若要查看這些工具的版本，請遵循下列步驟：

1. 在 PowerShell 視窗中，輸入：

   $PSVersionTable

   確認 PSVersion 此值為 7.x 或更新版本。 若要升級 PowerShell，請遵循安裝各種 PowerShell 版本的指示。

2. 在 PowerShell 視窗中，輸入：

   Get-Module -ListAvailable Az

   如果沒有出現任何專案，或該版本的 Azure PowerShell 模組早於 5.1.0，請遵循安裝 Azure PowerShell 模組以升級的指示。

繼續進行之前，請執行 Connect-AzAccount 以建立與 Azure 的連線。

確認自定義功能變數名稱可供使用

檢查您是否可使用您想要使用的自訂網域。 下列程式碼會使用 Azure AI 服務 REST API 中的 [檢查網域可用性] 作業，確認網域可供使用。

注意

下列程式代碼無法在 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

如果有所需的名稱可用，您會看到如下的回應：

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

Azure CLI

必要條件

• 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

  

• 若要在本地執行 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 Cloud Shell，則已安裝最新版本。

確認自定義功能變數名稱可供使用

檢查您想要使用的自定義網域是否是免費的。 使用 Azure AI 服務 REST API 中的 [檢查網域可用性] 方法。

複製下列程式代碼區塊、插入您慣用的自訂功能變數名稱，並將 儲存至 檔案 subdomain.json。

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

將檔案複製到您目前的資料夾，或將其上傳至 Azure Cloud Shell，然後執行下列命令。 將取代 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 為您的 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

如果有所需的名稱可用，您會看到如下的回應：

{
  "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 訂用帳戶標識碼。

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.com/.default" });
InteractiveBrowserCredential browserCredential = new InteractiveBrowserCredential();
var browserToken = browserCredential.GetToken(context);
string aadToken = browserToken.Token;

令牌內容必須設定為 ”https://cognitiveservices.azure.com/.default"

若要在 C++ 中取得 Microsoft Entra 存取令牌，請使用 Azure 身分識別客戶端連結庫。

以下是使用 Azure 身分識別取得具有租使用者識別碼、用戶端識別碼和用戶端密碼認證的 Microsoft Entra 存取令牌的範例：

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

令牌內容必須設定為 ”https://cognitiveservices.azure.com/.default"

若要在 Java 中取得 Microsoft Entra 存取令牌，請使用 Azure 身分識別客戶端連結庫。

以下是使用 Azure 身分識別從瀏覽器取得 Microsoft Entra 存取令牌的範例：

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

令牌內容必須設定為 ”https://cognitiveservices.azure.com/.default"

若要在 Java 中取得 Microsoft Entra 存取令牌，請使用 Azure 身分識別客戶端連結庫。

以下是使用 Azure 身分識別從互動式瀏覽器取得 Microsoft Entra 存取令牌的範例：

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

在程式代碼範例中尋找取得 Microsoft Entra 存取令牌的範例 Microsoft 身分識別平台。

對於無法使用 Microsoft 身分識別平台 用戶端連結庫的程式設計語言，您可以直接要求存取令牌。

取得語音資源標識碼

您需要語音資源識別碼，才能使用 Microsoft Entra 驗證進行 SDK 呼叫。

注意

針對意圖辨識，請使用您的 LUIS 預測資源識別碼。

Azure 入口網站

若要在 Azure 入口網站 中取得資源識別碼：

1. 前往 Azure 入口網站並登入 Azure 帳戶。
2. 選取語音資源。
3. 在左窗格的 [ 資源管理 ] 群組中，選取 [ 屬性]。
4. 複製資源標識碼

PowerShell

若要使用 PowerShell 取得資源識別符，請使用 Azure PowerShell 模組 5.1.0 版或更新版本確認您擁有 PowerShell 7.x 版或更新版本。 若要查看這些工具的版本，請遵循下列步驟：

1. 在 PowerShell 視窗中，輸入：

   $PSVersionTable

   確認 PSVersion 此值為 7.x 或更新版本。 若要升級 PowerShell，請遵循安裝各種 PowerShell 版本的指示。

2. 在 PowerShell 視窗中，輸入：

   Get-Module -ListAvailable Az

   如果沒有出現任何專案，或該版本的 Azure PowerShell 模組早於 5.1.0，請遵循安裝 Azure PowerShell 模組以升級的指示。

現在執行 Connect-AzAccount 以建立與 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

建立語音 SDK 組態物件

使用 Microsoft Entra 存取令牌，您現在可以建立語音 SDK 組態物件。

提供令牌的方法，以及建構對應語音 SDK Config 物件的方法會因您使用的物件而有所不同。

SpeechRecognizer、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber

針對SpeechRecognizer、 SpeechSynthesizerIntentRecognizerConversationTranscriber 、 物件，從資源識別碼和 Microsoft Entra 存取令牌建置授權令牌，然後使用它來建立SpeechConfig物件。

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

TranslationRecognizer針對，從資源標識碼和 Microsoft Entra 存取令牌建置授權令牌，然後使用它來建立SpeechTranslationConfig物件。

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 連線 or

DialogServiceConnection針對物件，從資源標識碼和 Microsoft Entra 存取令牌建置授權令牌，然後使用它來建立 CustomCommandsConfig 或 BotFrameworkConfig 物件。

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

Python 目前不支援 DialogService 連線 or

VoiceProfileClient

若要搭配 Microsoft Entra 驗證使用 VoiceProfileClient ，請使用上面建立的自定義功能變數名稱。

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

VoiceProfileClient不適用於適用於 Python 的語音 SDK。

注意

ConversationTranslator不支援 Microsoft Entra 驗證。