Speech SDK を使用した Microsoft Entra 認証

Speech SDK を使用して Speech サービスにアクセスする場合、サービス キー、キーベースのトークン、Microsoft Entra ID の 3 つの認証方法を使用できます。 この記事では、Microsoft Entra ID を認証に使用できるように、Speech リソースを構成し、Speech SDK 構成オブジェクトを作成する方法について説明します。

この記事では、Speech SDK で Microsoft Entra 認証を使用する方法を示します。 学習内容は次のとおりです。

• Speech リソースを作成する
• Microsoft Entra 認証の Speech リソースを構成する
• Microsoft Entra トークンを取得する
• 適切な SDK 構成オブジェクトを作成する

トークンの有効期間など、Microsoft Entra アクセス トークンの詳細については、「Microsoft ID プラットフォームのアクセス トークン」を参照してください。

Speech リソースを作成する

Azure portalで Speech リソースを作成するには、「リソースのキーを取得する」を参照してください

Microsoft Entra 認証の Speech リソースを構成する

Microsoft Entra 認証用にご自身の Speech リソースを構成するには、カスタム ドメイン名を作成し、ロールを割り当てます。

カスタム ドメイン名を作成する

こちらの手順に従って、Speech リソースの Azure AI サービスのカスタム サブドメイン名を作成します。

注意事項

カスタム ドメイン名をオンにした場合、この操作を元に戻すことはできません。 リージョン名に戻る唯一の方法は、新しい Speech リソースを作成することです。

Speech Studio を使用して作成された多数のカスタム モデルおよびプロジェクトが Speech リソースに関連付けられている場合は、運用環境で使用されているリソースを変更する前に、テスト リソースで構成を試してみることを強くお勧めします。

Azure Portal

Azure portal を使用してカスタム ドメイン名を作成するには、次の手順に従います。

1. Azure portal に移動し、ご自分の Azure アカウントにサインインします。

2. 必要な Speech リソースを選択します。

3. 左側のペインの [リソース管理] グループで、 [ネットワーク] を選択します。

4. [ファイアウォールと仮想ネットワーク] タブで、 [カスタム ドメイン名を生成します] を選択します。 新しい右パネルが開き、リソースの一意のカスタム サブドメインを作成する手順が示されます。

5. [カスタム ドメイン名の生成] パネルで、カスタム ドメイン名を入力します。 完全なカスタム ドメインは、https://{your custom name}.cognitiveservices.azure.com のようになります。

   作成したカスタム ドメイン名は後で変更 "できない" ことに注意してください。

   カスタム ドメイン名を入力した後、 [保存] を選択します。

6. 操作が終わったら、 [リソース管理] グループで [Keys and Endpoint](キーとエンドポイント) を選択します。 リソースの新しいエンドポイント名が次のように始まっていることを確認します: 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 のドメインの可用性の確認操作を使用して、ドメインが使用可能であることが確認されます。

Note

次のコードは 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

カスタム ドメイン名を作成する

選択した Speech リソースでカスタム ドメイン名をオンにするには、Set-AzCognitiveServicesAccount コマンドレットを使用します。

注意事項

次のコードが正常に実行された後、Speech リソースのカスタム ドメイン名を作成します。 この名前は変更 "できない" ことに注意してください。

$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 サブスクリプション 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

目的の名前が使用可能な場合は、次のような応答が表示されます。

{
  "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
}

カスタム ドメイン名をオンにする

選択した Speech リソースでカスタム ドメイン名を使用するには、az cognitiveservices account update コマンドを使用します。

(Azure アカウントにアクティブなサブスクリプションが 1 つしかない場合は、この手順をスキップできます) Speech リソースを含む Azure サブスクリプションを選択します。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx は、Azure サブスクリプション ID に置き換えてください。

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

カスタム ドメイン名を、選択したリソースに設定します。 サンプル パラメーターの値を実際の値に置き換えて、次のコマンドを実行します。

注意事項

以下のコマンドが正常に実行された後、Speech リソースのカスタム ドメイン名を作成します。 この名前は変更 "できない" ことに注意してください。

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

ロールを割り当てる

Speech リソースを使用して Microsoft Entra 認証を行うには、"Cognitive Services Speech 共同作成者" または "Cognitive Services Speech ユーザー" のいずれかのロールを割り当てる必要があります。

Azure portal または PowerShell を使用して、ユーザーまたはアプリケーションにロールを割り当てることができます。

Microsoft Entra トークンを取得する

C# で Microsoft Entra アクセス トークンを取得するには、Azure ID クライアント ライブラリを使用します。

Azure ID を使用して、対話型ブラウザーから 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 ID クライアント ライブラリを使用します。

Azure ID を使用して、テナント ID、クライアント ID、クライアント シークレット資格情報を含む 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 ID クライアント ライブラリを使用します。

Azure ID を使用して、ブラウザーから 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 ID クライアント ライブラリを使用します。

Azure ID を使用して、対話型ブラウザーから Microsoft Entra アクセス トークンを取得する例を次に示します:

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

Microsoft ID プラットフォームのコード サンプル内で、Microsoft Entra アクセス トークンを取得するサンプルを見つけます。

Microsoft ID プラットフォームのクライアント ライブラリを使用できないプログラミング言語の場合、直接アクセス トークンを要求できます。

Speech リソース ID を取得する

Microsoft Entra 認証を使用して SDK 呼び出しを行うには、お使いの Speech リソース ID が必要です。

Note

意図認識については、LUIS 予測リソース ID を使用します。

Azure Portal

Azure portal 内でリソース ID を取得するには:

1. Azure portal に移動し、ご自分の Azure アカウントにサインインします。
2. Speech リソースの選択します。
3. 左側のペインの [リソース管理] グループで、[プロパティ] を選択します。
4. リソース ID をコピーします

PowerShell

PowerShell を使用してリソース ID を取得するには、PowerShell バージョン 7.x 以降と Azure PowerShell モジュールのバージョン 5.1.0 以降を使用していることを確認します。 これらのツールのバージョンを確認するには、次の手順のようにします。

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

Speech SDK 構成オブジェクトを作成する

Microsoft Entra アクセス トークンを使用して、Speech SDK 構成オブジェクトを作成することができます。

トークンの提供方法や、対応する Speech SDK の Config オブジェクトの構築方法は、使用するオブジェクトによって異なります。

SpeechRecognizer、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber

SpeechRecognizer、SpeechSynthesizer、IntentRecognizer、ConversationTranscriber の各オブジェクトについては、リソース ID と 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 では、リソース ID と 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 オブジェクトでは、リソース ID と 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);

DialogServiceConnector は現在、Python ではサポートされていません

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 用 Speech SDK では使用できません。

Note

ConversationTranslator では、Microsoft Entra 認証はサポートされていません。