Проверка подлинности Microsoft Entra с помощью пакета SDK службы "Речь"

При использовании пакета SDK службы "Речь" для доступа к службе "Речь" доступны три метода проверки подлинности: ключи службы, маркер на основе ключей и идентификатор Microsoft Entra. В этой статье описывается настройка ресурса "Речь" и создание объекта конфигурации пакета SDK службы "Речь" для использования идентификатора Microsoft Entra для проверки подлинности.

В этой статье показано, как использовать проверку подлинности Microsoft Entra с пакетом SDK службы "Речь". Узнайте следующие темы:

• создавать ресурс службы "Речь";
• Настройка ресурса службы "Речь" для проверки подлинности Microsoft Entra
• Получение маркера доступа Microsoft Entra
• создавать соответствующий объект конфигурации пакета SDK.

Дополнительные сведения о маркерах доступа Microsoft Entra, включая время существования маркеров, посетите маркеры доступа в платформа удостоверений Майкрософт.

создавать ресурс службы "Речь";

Сведения о создании ресурса службы "Речь" на портале Azure см. в статье Получение ключей для ресурса

Настройка ресурса службы "Речь" для проверки подлинности Microsoft Entra

Чтобы настроить ресурс службы "Речь" для проверки подлинности Microsoft Entra, создайте имя личного домена и назначьте роли.

Создание пользовательского доменного имени

Выполните следующие действия, чтобы создать пользовательское имя поддомена для служб ИИ Azure для ресурса "Речь".

Внимание

Операция включения имени личного домена необратима. Единственный способ вернуться к региональному имени — создать новый ресурс "Речь".

Если у вашего ресурса "Речь" много связанных пользовательских моделей и проектов создано с помощью 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, убедитесь, что на компьютере установлен 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.

Проверка доступности пользовательского доменного имени

Проверьте, доступен ли личный домен, который вы хотите использовать. Следующий код подтверждает, что домен доступен с помощью операции проверки доступности домена в REST API служб ИИ Azure.

Примечание.

Следующий код не будет работать в 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.

Внимание

После успешного выполнения следующего кода будет создано пользовательское доменное имя для ресурса "Речь". Помните, что это имя нельзя изменить.

$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

Необходимые компоненты

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  

• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Для работы с этим разделом требуется последняя версия Azure CLI. Если вы используете Azure Cloud Shell, последняя версия уже установлена.

Проверка доступности пользовательского доменного имени

Проверьте, свободен ли личный домен, который вы хотите использовать. Используйте метод проверки доступности домена из REST API служб ИИ Azure.

Скопируйте следующий блок кода, вставьте нужное пользовательское доменное имя и сохраните его в файл 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 с помощью ресурсов службы "Речь" необходимо назначить роль "Участник речи Cognitive Services" или "Пользователь службы распознавания речи Cognitive Services".

Роли можно назначить пользователю или приложению с помощью портала Azure или PowerShell.

Получение маркера доступа Microsoft Entra

Чтобы получить маркер доступа Microsoft Entra в C#, используйте клиентская библиотека удостоверений 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".

Чтобы получить маркер доступа Microsoft Entra в C++, используйте клиентская библиотека удостоверений 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".

Чтобы получить маркер доступа Microsoft Entra на Java, используйте клиентская библиотека удостоверений 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".

Чтобы получить маркер доступа Microsoft Entra в Python, используйте клиентская библиотека удостоверений Azure.

Ниже приведен пример использования удостоверения Azure для получения маркера доступа Microsoft Entra из интерактивного браузера:

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

Найдите примеры, которые получают маркер доступа Microsoft Entra в платформа удостоверений Майкрософт примерах кода.

Для языков программирования, для которых клиентская библиотека платформы удостоверений Майкрософт недоступна, можно запрашивать маркер доступа напрямую.

Получение идентификатора ресурса службы "Речь"

Вам нужен идентификатор ресурса службы "Речь" для вызова пакета SDK с помощью проверки подлинности Microsoft Entra.

Примечание.

Для распознавания намерений используйте идентификатор ресурса прогнозирования LUIS.

Портал Azure

Чтобы получить идентификатор ресурса на портале Azure, выполните следующие действия.

1. Откройте портал Azure и войдите в свою учетную запись Azure.
2. Выберите ресурс службы "Речь".
3. В группе Управление ресурсами на левой панели выберите Свойства.
4. Скопируйте Идентификатор ресурса.

PowerShell

Чтобы получить идентификатор ресурса с помощью PowerShell, убедитесь, что на компьютере имеется 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

Создание объекта конфигурации пакета 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)

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

В настоящее время DialogServiceConnector не поддерживается в Python

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

Объект VoiceProfileClient недоступен в пакете SDK службы "Речь" для Python.

Примечание.

Проверка ConversationTranslator подлинности Microsoft Entra не поддерживается.