Ověřování Microsoft Entra pomocí sady Speech SDK

Při použití sady Speech SDK pro přístup ke službě Speech jsou k dispozici tři metody ověřování: klíče služby, token založený na klíči a ID Microsoft Entra. Tento článek popisuje, jak nakonfigurovat prostředek služby Speech a vytvořit objekt konfigurace sady Speech SDK pro použití Microsoft Entra ID pro ověřování.

Tento článek ukazuje, jak používat ověřování Microsoft Entra se sadou Speech SDK. Získáte informace pro:

• Vytvoření prostředku služby Speech
• Konfigurace prostředku služby Speech pro ověřování Microsoft Entra
• Získání přístupového tokenu Microsoft Entra
• Vytvořte odpovídající objekt konfigurace sady SDK.

Další informace o přístupovýchtokench

Vytvoření prostředku služby Speech

Pokud chcete vytvořit prostředek služby Speech na webu Azure Portal, podívejte se na tento rychlý start.

Konfigurace prostředku služby Speech pro ověřování Microsoft Entra

Pokud chcete nakonfigurovat prostředek služby Speech pro ověřování Microsoft Entra, vytvořte vlastní název domény a přiřaďte role.

Vytvoření vlastního názvu domény

Podle těchto kroků vytvořte vlastní název subdomény pro služby Azure AI pro váš prostředek služby Speech.

Upozornění

Když zapnete vlastní název domény, operace se nedá vrátit zpět. Jediným způsobem, jak se vrátit k názvu oblasti, je vytvořit nový prostředek služby Speech.

Pokud váš prostředek služby Speech obsahuje mnoho přidružených vlastních modelů a projektů vytvořených prostřednictvím sady Speech Studio, důrazně doporučujeme vyzkoušet konfiguraci s testovacím prostředkem, než upravíte prostředek použitý v produkčním prostředí.

Azure Portal

Pokud chcete vytvořit vlastní název domény pomocí webu Azure Portal, postupujte takto:

1. Přejděte na Azure Portal a přihlaste se ke svému účtu Azure.

2. Vyberte požadovaný prostředek služby Speech.

3. Ve skupině Správa prostředků v levém podokně vyberte Sítě.

4. Na kartě Brány firewall a virtuální sítě vyberte Vygenerovat vlastní název domény. Zobrazí se nový pravý panel s pokyny k vytvoření jedinečné vlastní subdomény pro váš prostředek.

5. Na panelu Generovat vlastní název domény zadejte vlastní název domény. Vaše úplná vlastní doména bude vypadat takto: https://{your custom name}.cognitiveservices.azure.com.

   Mějte na paměti, že po vytvoření vlastního názvu domény ho nelze změnit.

   Po zadání vlastního názvu domény vyberte Uložit.

6. Po dokončení operace ve skupině pro správu prostředků vyberte Klíče a koncový bod. Ověřte, že nový název koncového bodu vašeho prostředku začíná tímto způsobem: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Pokud chcete vytvořit vlastní název domény pomocí PowerShellu, ověřte, že váš počítač má PowerShell verze 7.x nebo novější s modulem Azure PowerShell verze 5.1.0 nebo novějším. Pokud chcete zobrazit verze těchto nástrojů, postupujte takto:

1. V okně PowerShellu zadejte:

   $PSVersionTable

   Ověřte, že PSVersion hodnota je 7.x nebo novější. Pokud chcete upgradovat PowerShell, postupujte podle pokynů v tématu Instalace různých verzí PowerShellu.

2. V okně PowerShellu zadejte:

   Get-Module -ListAvailable Az

   Pokud se nic nezobrazí nebo pokud je tato verze modulu Azure PowerShell starší než 5.1.0, postupujte podle pokynů v tématu Instalace modulu Azure PowerShell a proveďte upgrade.

Než budete pokračovat, spusťte spuštění Connect-AzAccount a vytvořte připojení k Azure.

Ověřte, že je k dispozici vlastní název domény.

Zkontrolujte, jestli je k dispozici vlastní doména, kterou chcete použít. Následující kód potvrdí, že je doména k dispozici pomocí operace Zkontrolovat dostupnost domény v rozhraní REST API služeb Azure AI.

Poznámka:

Následující kód nebude v Azure Cloud Shellu fungovat.

$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

Pokud je požadovaný název dostupný, zobrazí se odpověď podobná této:

isSubdomainAvailable : True
reason               :
type                 :
subdomainName        : my-custom-name

Pokud se název už používá, zobrazí se následující odpověď:

isSubdomainAvailable : False
reason               : Sub domain name 'my-custom-name' is already used. Please pick a different name.
type                 :
subdomainName        : my-custom-name

Vytvoření vlastního názvu domény

Pokud chcete zapnout vlastní název domény pro vybraný prostředek služby Speech, použijte rutinu Set-AzCognitiveServicesAccount .

Upozornění

Po úspěšném spuštění následujícího kódu vytvoříte vlastní název domény pro váš prostředek služby Speech. Nezapomeňte, že tento název nelze změnit.

$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

Požadavky

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Tato část vyžaduje nejnovější verzi Azure CLI. Pokud používáte Azure Cloud Shell, je už nainstalovaná nejnovější verze.

Ověřte, že je k dispozici vlastní název domény.

Zkontrolujte, jestli je vlastní doména, kterou chcete použít, bezplatná. Použijte metodu Kontrola dostupnosti domény z rozhraní REST API služeb Azure AI.

Zkopírujte následující blok kódu, vložte upřednostňovaný vlastní název domény a uložte ho do souboru subdomain.json.

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

Zkopírujte soubor do aktuální složky nebo ho nahrajte do Azure Cloud Shellu a spusťte následující příkaz. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx nahraďte ID vašeho předplatného 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

Pokud je požadovaný název dostupný, zobrazí se odpověď podobná této:

{
  "isSubdomainAvailable": true,
  "reason": null,
  "subdomainName": "my-custom-name",
  "type": null
}

Pokud se název už používá, zobrazí se následující odpověď:

{
  "isSubdomainAvailable": false,
  "reason": "Sub domain name 'my-custom-name' is already used. Please pick a different name.",
  "subdomainName": "my-custom-name",
  "type": null
}

Zapnutí vlastního názvu domény

Pokud chcete použít vlastní název domény s vybraným prostředkem služby Speech, použijte příkaz az cognitiveservices account update .

(Pokud má váš účet Azure jenom jedno aktivní předplatné, můžete tento krok přeskočit.) Vyberte předplatné Azure, které obsahuje prostředek služby Speech. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx nahraďte ID vašeho předplatného Azure.

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

Nastavte vlastní název domény na vybraný prostředek. Nahraďte hodnoty ukázkových parametrů skutečnými hodnotami a spusťte následující příkaz.

Upozornění

Po úspěšném provedení následujícího příkazu vytvoříte vlastní název domény pro prostředek služby Speech. Nezapomeňte, že tento název nelze změnit.

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

Přiřazení rolí

Pro ověřování Microsoft Entra pomocí prostředků služby Speech je potřeba přiřadit roli přispěvatele řeči služeb Cognitive Services nebo role uživatele služby Cognitive Services Speech.

Role můžete uživateli nebo aplikaci přiřadit pomocí webu Azure Portal nebo PowerShellu.

Získání přístupového tokenu Microsoft Entra

Pokud chcete získat přístupový token Microsoft Entra v jazyce C#, použijte klientskou knihovnu Azure Identity.

Tady je příklad použití služby Azure Identity k získání přístupového tokenu Microsoft Entra z interaktivního prohlížeče:

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;

Poznámka:

Kontext tokenu musí být nastaven na "https://cognitiveservices.azure.com/.default".

Pokud chcete získat přístupový token Microsoft Entra v jazyce C++, použijte klientskou knihovnu Azure Identity.

Tady je příklad použití služby Azure Identity k získání přístupového tokenu Microsoft Entra s ID tenanta, ID klienta a přihlašovacími údaji tajného klíče klienta:

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

Poznámka:

Kontext tokenu musí být nastaven na "https://cognitiveservices.azure.com/.default".

Pokud chcete získat přístupový token Microsoft Entra v Javě, použijte klientskou knihovnu Azure Identity.

Tady je příklad použití služby Azure Identity k získání přístupového tokenu Microsoft Entra z prohlížeče:

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

Poznámka:

Kontext tokenu musí být nastaven na "https://cognitiveservices.azure.com/.default".

Pokud chcete získat přístupový token Microsoft Entra v Pythonu, použijte klientskou knihovnu Azure Identity.

Tady je příklad použití služby Azure Identity k získání přístupového tokenu Microsoft Entra z interaktivního prohlížeče:

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

Najděte ukázky, které získají přístupový token Microsoft Entra v ukázkách kódu platformy Microsoft Identity Platform.

V programovacích jazycích, kde není k dispozici klientská knihovna Microsoft Identity Platform, můžete požádat přímo o přístupový token.

Získání ID prostředku služby Speech

K volání sady SDK pomocí ověřování Microsoft Entra potřebujete ID prostředku služby Speech.

Poznámka:

Pro rozpoznávání záměru použijte ID prostředku predikce služby LUIS.

Azure Portal

Id prostředku získáte na webu Azure Portal:

1. Přejděte na Azure Portal a přihlaste se ke svému účtu Azure.
2. Vyberte prostředek služby Speech.
3. Ve skupině Správa prostředků v levém podokně vyberte Vlastnosti.
4. Zkopírování ID prostředku

PowerShell

Pokud chcete získat ID prostředku pomocí PowerShellu, ověřte, že máte PowerShell verze 7.x nebo novější s modulem Azure PowerShell verze 5.1.0 nebo novější. Pokud chcete zobrazit verze těchto nástrojů, postupujte takto:

1. V okně PowerShellu zadejte:

   $PSVersionTable

   Ověřte, že PSVersion hodnota je 7.x nebo novější. Pokud chcete upgradovat PowerShell, postupujte podle pokynů v tématu Instalace různých verzí PowerShellu.

2. V okně PowerShellu zadejte:

   Get-Module -ListAvailable Az

   Pokud se nic nezobrazí nebo pokud je tato verze modulu Azure PowerShell starší než 5.1.0, postupujte podle pokynů v tématu Instalace modulu Azure PowerShell a proveďte upgrade.

Teď spusťte, Connect-AzAccount abyste vytvořili připojení k 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

Vytvoření objektu konfigurace sady Speech SDK

S přístupovým tokenem Microsoft Entra teď můžete vytvořit objekt konfigurace sady Speech SDK.

Metoda poskytnutí tokenu a metoda pro vytvoření odpovídajícího objektu sady Speech SDK Config se liší podle objektu, který používáte.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Pro SpeechRecognizer, , IntentRecognizerSpeechSynthesizerConversationTranscriber , objekty, sestavení autorizační token z ID prostředku a Microsoft Entra přístupový token a pak ho použít k vytvoření objektu.SpeechConfig

string resourceId = "Your Resource ID";
string aadToken = "Your Microsoft Entra access token";
string region =  "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
var speechConfig = SpeechConfig.FromAuthorizationToken(authorizationToken, region);

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Microsoft Entra access token";
std::string region = "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra 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 Microsoft Entra 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 Microsoft Entra access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)

TranslationRecognizer

V případě objektu TranslationRecognizersestavte autorizační token z ID prostředku a přístupového tokenu Microsoft Entra a pak ho použijte k vytvoření objektu SpeechTranslationConfig .

string resourceId = "Your Resource ID";
string aadToken = "Your Microsoft Entra access token";
string region =  "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
var speechConfig = SpeechTranslationConfig.FromAuthorizationToken(authorizationToken, region);

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Microsoft Entra access token";
std::string region = "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra 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 Microsoft Entra 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 Microsoft Entra access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
translationConfig = SpeechTranslationConfig(auth_token=authorizationToken, region=region)

VoiceProfileClient

Pokud chcete použít VoiceProfileClient ověřování Microsoft Entra, použijte název vlastní domény vytvořený výše.

string customDomainName = "Your Custom Name";
string hostName = $"https://{customDomainName}.cognitiveservices.azure.com/";
string token = "Your Microsoft Entra access token";

var config =  SpeechConfig.FromHost(new Uri(hostName));

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
config.AuthorizationToken = authorizationToken;

std::string customDomainName = "Your Custom Name";
std::string aadToken = "Your Microsoft Entra 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 Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
speechConfig->SetAuthorizationToken(authorizationToken);

String aadToken = "Your Microsoft Entra 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 Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;

speechConfig.setAuthorizationToken(authorizationToken);

Sada VoiceProfileClient Speech SDK pro Python není dostupná.

Poznámka:

Ověřování ConversationTranslator Microsoft Entra nepodporuje.