Аутентификация Microsoft Entra с помощью Speech SDK

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

В этой статье показано, как использовать аутентификацию Microsoft Entra с Speech SDK. Вы научитесь:

Создание ресурса Foundry
Настройка ресурса распознавания речи для аутентификации Microsoft Entra
Получите токен доступа Microsoft Entra
создавать соответствующий объект конфигурации пакета SDK.

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

Создание ресурса Foundry

Сведения о создании ресурса Foundry на портале Azure см. в этом кратком руководстве.

Настройка ресурса распознавания речи для аутентификации Microsoft Entra

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

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

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

Внимание

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

Если у вашего ресурса речи много связанных пользовательских моделей и проектов, созданных с помощью Speech Studio, настоятельно рекомендуется выполнить настройку с помощью тестового ресурса, прежде чем изменять ресурс, используемый в производственной среде.

Чтобы создать имя личного домена на портале Azure, выполните следующие действия:

Откройте портал Azure и войдите в свою учетную запись Azure.
Выберите необходимый ресурс Speech.
В группе Управление ресурсами на левой панели выберите Сеть.
На вкладке Брандмауэры и виртуальные сети выберите Создать пользовательское доменное имя. Справа появится новая панель с инструкциями по созданию уникального пользовательского поддомена для ресурса.
На панели Создание пользовательского доменного имени введите пользовательское доменное имя. Полное имя вашего личного домена будет выглядеть так: 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.

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

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

Примечание.

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

Внимание

После успешного выполнения следующего кода вы создадите пользовательское доменное имя для вашего ресурса 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

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".
Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
- Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".
- Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.
- Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

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

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

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

Скопируйте следующий блок кода, вставьте нужное пользовательское доменное имя и сохраните его в файл 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 Identity Client.

Приведён пример использования Azure Identity для получения токена доступа 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 tokenContext = "https://cognitiveservices.azure.com/.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.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 Identity Client Library.

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

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

Другие примеры

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

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

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

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

Портал Azure
PowerShell

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

Откройте портал Azure и войдите в свою учетную запись Azure.
Выберите ресурс Foundry.
В группе Управление ресурсами на левой панели выберите Свойства.
Скопируйте Идентификатор ресурса.

Чтобы получить идентификатор ресурса с помощью 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, SourceLanguageRecognizer, ConversationTranscriber используйте соответствующий экземпляр TokenCredential для аутентификации, а также конечную точку, включающую ваш пользовательский домен, чтобы создать объект SpeechConfig.

TokenCredential browserCredential = new InteractiveBrowserCredential();

// Define the custom domain endpoint for your Speech resource.
var endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
var speechConfig = SpeechConfig.FromEndpoint(new Uri(endpoint), browserCredential);

Распознаватель перевода

Для TranslationRecognizer объекта используйте соответствующий экземпляр TokenCredential для проверки подлинности, а также конечную точку, включающую личный домен, для создания SpeechTranslationConfig объекта.

TokenCredential browserCredential = new InteractiveBrowserCredential();

// Define the custom domain endpoint for your Speech resource
var endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
var speechConfig = SpeechTranslationConfig.FromEndpoint(new Uri(endpoint), browserCredential);

Синтезатор речи

Для SpeechSynthesizer объектов используйте соответствующий экземпляр TokenCredential для проверки подлинности. Вместе с конечной точкой, содержащей ваш пользовательский домен, используйте эти учетные данные, чтобы создать объект SpeechConfig.

TokenCredential browserCredential = new InteractiveBrowserCredential();

// Define the custom domain endpoint for your Speech resource.
var endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
var speechConfig = SpeechConfig.FromEndpoint(new Uri(endpoint), browserCredential);

Распознаватель речи (SpeechRecognizer), Синтезатор речи (SpeechSynthesizer), Транскрибатор разговора (ConversationTranscriber)

Для объектов SpeechRecognizer, SpeechSynthesizer и ConversationTranscriber используйте соответствующий экземпляр TokenCredential для аутентификации. Вместе с конечной точкой, содержащей ваш пользовательский домен, используйте эти учетные данные, чтобы создать объект SpeechConfig.

auto browserCredential = std::make_shared<Azure::Identity::InteractiveBrowserCredential>();

// Define the custom domain endpoint for your Speech resource.
auto endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
auto speechConfig = SpeechConfig::FromEndpoint(endpoint, browserCredential);

Распознаватель перевода

Для TranslationRecognizer используйте подходящий экземпляр TokenCredential для аутентификации. Вместе с конечной точкой, содержащей ваш пользовательский домен, используйте эти учетные данные, чтобы создать объект SpeechTranslationConfig.

auto browserCredential = std::make_shared<Azure::Identity::InteractiveBrowserCredential>();

// Define the custom domain endpoint for your Speech resource
auto endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
auto speechConfig = SpeechTranslationConfig::FromEndpoint(endpoint, browserCredential);

Распознаватель речи, Транскриптор разговоров

Для SpeechRecognizerConversationTranscriber объектов используйте соответствующий экземпляр TokenCredential для проверки подлинности, а также конечную точку, включающую ваш пользовательский домен, для создания SpeechConfig объекта.

TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();

// Define the custom domain endpoint for your Speech resource.
String endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
SpeechConfig speechConfig = SpeechConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);

Распознаватель перевода

TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();

// Define the custom domain endpoint for your Speech resource
String endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
SpeechConfig speechConfig = SpeechTranslationConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);

Синтезатор речи

Для SpeechSynthesizer объекта используйте соответствующий экземпляр TokenCredential для проверки подлинности. Вместе с конечной точкой, содержащей ваш пользовательский домен, используйте эти учетные данные, чтобы создать объект SpeechConfig.

TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();

// Define the custom domain endpoint for your Speech resource.
String endpoint = "https://{your custom name}.cognitiveservices.azure.com/";

// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
SpeechConfig speechConfig = SpeechConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);

Распознаватель речи, Транскриптор разговоров

browserCredential = InteractiveBrowserCredential()

# Define the custom domain endpoint for your Speech resource.
custom_endpoint = "https://{your custom name}.cognitiveservices.azure.com/"

# Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
speechConfig = SpeechConfig(token_credential=browserCredential, endpoint=custom_endpoint)

Распознаватель перевода

browserCredential = InteractiveBrowserCredential()

# Define the custom domain endpoint for your Speech resource
custom_endpoint = "https://{your custom name}.cognitiveservices.azure.com/"

# Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
speechTranslationConfig = SpeechTranslationConfig(token_credential=browserCredential, endpoint=custom_endpoint)

Синтезатор речи

SpeechSynthesizer Для объекта используйте соответствующий экземпляр TokenCredential для проверки подлинности. Наряду с конечной точкой, включающей личный домен, используйте эти элементы для создания SpeechConfig объекта.

browserCredential = InteractiveBrowserCredential()

# Define the custom domain endpoint for your Speech resource.
custom_endpoint = "https://{your custom name}.cognitiveservices.azure.com/"

# Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
speechConfig = SpeechConfig(token_credential=browserCredential, endpoint=custom_endpoint)

Примечание.

Аутентификация Microsoft Entra не поддерживается ConversationTranslator.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-22

Аутентификация Microsoft Entra с помощью Speech SDK

Создание ресурса Foundry

Настройка ресурса распознавания речи для аутентификации Microsoft Entra

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

Назначьте роли

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

Другие примеры

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

Создать объект конфигурации SDK для службы речевых технологий

Распознаватель речи, Определитель языка источника, Транскриптор беседы

Распознаватель перевода

Синтезатор речи

Распознаватель речи (SpeechRecognizer), Синтезатор речи (SpeechSynthesizer), Транскрибатор разговора (ConversationTranscriber)

Распознаватель перевода

Распознаватель речи, Транскриптор разговоров

Распознаватель перевода

Синтезатор речи

Распознаватель речи, Транскриптор разговоров

Распознаватель перевода

Синтезатор речи

Обратная связь

Дополнительные ресурсы