利用語音 SDK 進行 Microsoft Entra 驗證

發行項
09/03/2024

使用語音 SDK 存取語音服務時，有三種可用的驗證方法：服務金鑰、金鑰型權杖，以及 Microsoft Entra ID。本文說明如何設定語音資源，並建立語音 SDK 設定物件以使用 Microsoft Entra ID 進行驗證。

本文說明如何搭配使用 Microsoft Entra 驗證與語音 SDK。您將學習如何：

建立語音資源
設定 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.com。

請記住，自訂網域名稱一經建立即無法變更。

輸入自訂網域名稱後，選取 [儲存]。
作業完成後，在 [資源管理] 群組中選取 [金鑰與端點]。確認資源的新端點名稱是以這種方式啟動：https://{your custom name}.cognitiveservices.azure.com。

如要使用 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 以建立與 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 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，然後執行下列命令。使用您的 Azure 訂用帳戶識別碼來取代 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 。

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 訂閱。使用您的 Azure 訂用帳戶識別碼來取代 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 。

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"。

如要在 Python 中取得 Microsoft Entra 存取權杖，請使用 Azure 身分識別用戶端程式庫。

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

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

在 Microsoft 身分識別平台程式碼範例中，尋找取得 Microsoft Entra 存取權杖的範例。

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

取得語音資源識別碼

您必須具有語音資源識別碼，才能使用 Microsoft Entra 驗證執行 SDK 呼叫。

注意

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

Azure 入口網站
PowerShell

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

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

如要使用 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 來建立與 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、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber 物件，從資源識別碼和 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)

DialogServiceConnector

針對 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 目前不支援 DialogServiceConnector

VoiceProfileClient

如要使用 VoiceProfileClient 搭配 Microsoft Entra 驗證，請使用以上建立的自訂網域名稱。

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

適用於 Python 的語音 SDK 無法使用 VoiceProfileClient。

注意

ConversationTranslator 不支援 Microsoft Entra 驗證。

共用方式為

利用語音 SDK 進行 Microsoft Entra 驗證

建立語音資源

設定 Microsoft Entra 驗證的語音資源

建立自訂網域名稱

確認具有可用的自訂網域名稱

建立您的自訂網域名稱

必要條件

確認具有可用的自訂網域名稱

開啟自訂網域名稱

指派角色

取得 Microsoft Entra 存取權杖

取得語音資源識別碼

建立語音 SDK 設定物件

SpeechRecognizer、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber

TranslationRecognizer

DialogServiceConnector

VoiceProfileClient

意見反應

其他資源