Użycie interfejsu API REST do przekształcania mowy na tekst dla krótkich nagrań audio

Używaj interfejsu REST API do zamiany mowy na tekst dla krótkich nagrań tylko wtedy, gdy nie można użyć Speech SDK ani szybkiego interfejsu API transkrypcji.

Przed użyciem interfejsu API REST zamiany mowy na tekst dla krótkiego nagrania audio należy wziąć pod uwagę następujące ograniczenia:

  • Żądania korzystające z interfejsu API REST dla krótkiego dźwięku i przesyłania dźwięku bezpośrednio mogą zawierać nie więcej niż 60 sekund dźwięku. W przypadku oceny wymowy czas trwania dźwięku nie powinien przekraczać 30 sekund. Formaty audio wejściowego są bardziej ograniczone w porównaniu z zestawem SPEECH SDK.
  • Interfejs API REST dla krótkiego dźwięku zwraca tylko końcowe wyniki. Nie zapewnia częściowych wyników.
  • Tłumaczenie mowy nie jest obsługiwane za pośrednictwem interfejsu API REST w przypadku krótkiego dźwięku. Musisz użyć Speech SDK.
  • Transkrypcja wsadowa i niestandardowa mowa nie są obsługiwane za pośrednictwem interfejsu API REST w przypadku krótkiego dźwięku. Zawsze należy używać interfejsu API REST zamiany mowy na tekst na potrzeby transkrypcji wsadowej i mowy niestandardowej.

Zanim skorzystasz z interfejsu Speech to text REST API dla krótkich nagrań audio, pamiętaj, że musisz najpierw przeprowadzić wymianę tokenów w ramach procesu uwierzytelniania, aby uzyskać dostęp do usługi. Aby uzyskać więcej informacji, zobacz Authentication (Uwierzytelnianie).

Regiony i punkty końcowe

Punkt końcowy interfejsu API REST dla krótkiego dźwięku ma następujący format:

https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1

Zastąp element YourResourceName nazwą swojego zasobu Speech.

Uwaga

Aby uzyskać dostęp do Azure Government i Microsoft Azure obsługiwanych przez 21Vianet, zobacz ten artykuł dotyczący suwerennych chmur.

Formaty audio

Dźwięk jest wysyłany w treści żądania HTTP POST . Musi być w jednym z formatów w tej tabeli:

Formacie Kodek Szybkość bitów Częstotliwość próbkowania
WAV PCM 256 kb/s 16 kHz, mono
OGG OPUS 256 kb/s 16 kHz, mono

Uwaga

Powyższe formaty są obsługiwane za pośrednictwem interfejsu API REST dla krótkich nagrań audio i interfejsu WebSocket w usłudze Mowa. Zestaw Speech SDK obsługuje format WAV z kodekiem PCM, a także innymi formatami.

Nagłówki żądań

Ta tabela zawiera listę wymaganych i opcjonalnych nagłówków dla żądań zamiany mowy na tekst:

Nagłówka Opis Wymagane lub opcjonalne
Ocp-Apim-Subscription-Key Twój klucz zasobu do usługi Mowa. Ten nagłówek lub Authorization jest wymagany.
Authorization Token autoryzacji poprzedzony wyrazem Bearer. Aby uzyskać więcej informacji, zobacz Authentication (Uwierzytelnianie). Ten nagłówek lub Ocp-Apim-Subscription-Key jest wymagany.
Pronunciation-Assessment Określa parametry wyświetlania wyników wymowy w wynikach rozpoznawania. Wyniki te oceniają jakość wymowy danych wejściowych mowy, ze wskaźnikami takimi jak dokładność, płynność i kompletność.

Ten parametr jest kodem JSON zakodowanym w formacie Base64, który zawiera wiele szczegółowych parametrów. Aby dowiedzieć się, jak utworzyć ten nagłówek, zobacz Parametry oceny wymowy.
Opcjonalne
Content-type Opisuje format i koder koderowy dostarczonych danych dźwiękowych. Akceptowane wartości to audio/wav; codecs=audio/pcm; samplerate=16000 i audio/ogg; codecs=opus. Wymagane
Transfer-Encoding Określa, że fragmentowane dane audio są wysyłane, a nie pojedynczy plik. Użyj tego nagłówka tylko wtedy, gdy fragmentujesz dane audio. Opcjonalne
Expect Jeśli używasz fragmentowanego transferu, wyślij polecenie Expect: 100-continue. Usługa rozpoznawania mowy potwierdza wstępne żądanie i oczekuje na więcej danych. Wymagane w przypadku wysyłania fragmentowanych danych dźwiękowych.
Accept Jeśli podano, musi to być application/json. Usługa rozpoznawania mowy udostępnia wyniki w formacie JSON. Niektóre struktury żądań zapewniają niezgodną wartość domyślną. Dobrym rozwiązaniem jest zawsze uwzględnienie Accept. Opcjonalne, ale zalecane.

Parametry zapytania

Te parametry mogą być uwzględniane w łańcuchu zapytania REST.

Uwaga

Aby uniknąć odbierania błędu HTTP 4xx, należy dołączyć parametr języka do adresu URL. Na przykład język ustawiony na angielski (Stany Zjednoczone) to: https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parametr Opis Wymagane lub opcjonalne
language Identyfikuje rozpoznawany język mówiony. Zobacz Obsługiwane języki. Wymagane
format Określa format wyniku. Akceptowane wartości to simple i detailed. Proste wyniki obejmują RecognitionStatus, , DisplayTextOffseti Duration. Szczegółowe odpowiedzi obejmują cztery różne reprezentacje tekstu wyświetlanego. Ustawieniem domyślnym jest simple. Opcjonalne
profanity Określa sposób obsługi wulgaryzmów w wynikach rozpoznawania. Akceptowane wartości to:

masked, który zastępuje wulgaryzmy gwiazdkami.
removed, który usuwa wszystkie niecenzuralne wyrażenia z wyniku.
raw, który w rezultacie zawiera wulgaryzmy.

Ustawieniem domyślnym jest masked.
Opcjonalne

Parametry oceny wymowy

W tej tabeli wymieniono wymagane i opcjonalne parametry oceny wymowy:

Parametr Opis Wymagane lub opcjonalne
ReferenceText Tekst, względem którego jest obliczana wymowa. Wymagane
GradingSystem System punktów do kalibracji wyników. System FivePoint daje wynik zmiennoprzecinkowy 0–5 i HundredMark daje wynik zmiennoprzecinkowy 0–100. Wartość domyślna: FivePoint. Opcjonalne
Granularity Stopień szczegółowości oceny. Akceptowane wartości to:

Phoneme, który pokazuje wynik na poziomie tekstu pełnego, słów i fonemów.
Word, który pokazuje wynik na poziomie pełnego tekstu i słowa.
FullText, który pokazuje wynik tylko na poziomie pełnotekstowym.

Ustawieniem domyślnym jest Phoneme.
Opcjonalne
Dimension Definiuje kryteria wyjściowe. Akceptowane wartości to:

Basic, który pokazuje tylko ocenę dokładności.
Comprehensive, który pokazuje wyniki dla większej liczby wymiarów (na przykład wynik płynności i wynik kompletności na poziomie pełnotekstowym oraz typ błędu na poziomie wyrazu).

Aby wyświetlić definicje różnych wymiarów wyników i typów błędów słów, zobacz Właściwości odpowiedzi. Ustawieniem domyślnym jest Basic.
Opcjonalne
EnableMiscue Włącza błędne obliczanie. Po włączeniu tego parametru wyrazy wymawiane są porównywane z tekstem odwołania. Na podstawie porównania są one oznaczone jako pominięcie lub dodanie. Akceptowane wartości to False i True. Ustawieniem domyślnym jest False. Opcjonalne
EnableProsodyAssessment Umożliwia ocenę prosody na potrzeby oceny wymowy. Ta funkcja ocenia aspekty, takie jak stres, intonacja, szybkość mówienia i rytm. Ta funkcja zapewnia wgląd w naturalność i wyrazistość mowy.

Jeśli ta właściwość jest ustawiona na True, zwracana jest wartość wyniku ProsodyScore.
Opcjonalne
ScenarioId Identyfikator GUID wskazujący dostosowany system punktów. Opcjonalne

Oto przykładowy kod JSON zawierający parametry oceny wymowy:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "Word",
  "Dimension": "Comprehensive",
  "EnableProsodyAssessment": "True"
}

Poniższy przykładowy kod pokazuje, jak skompilować parametry oceny wymowy w nagłówku Pronunciation-Assessment :

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"Word\",\"Dimension\":\"Comprehensive\",\"EnableProsodyAssessment\":\"True\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

Zdecydowanie zalecamy przesyłanie strumieniowe (transfer fragmentowany) podczas publikowania danych audio, co może znacznie zmniejszyć opóźnienie. Aby dowiedzieć się, jak włączyć przesyłanie strumieniowe, zobacz kod sample w różnych językach programowania.

Uwaga

Aby uzyskać więcej informacji, zobacz ocena wymowy.

Przykładowe żądanie

Poniższy przykład zawiera nazwę hosta i wymagane nagłówki. Należy pamiętać, że usługa oczekuje również danych dźwiękowych, które nie są uwzględnione w tym przykładzie. Jak wspomniano wcześniej, fragmentowanie jest zalecane, ale nie jest wymagane.

POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: YourResourceName.cognitiveservices.azure.com
Transfer-Encoding: chunked
Expect: 100-continue

Aby włączyć ocenę wymowy, możesz dodać następujący nagłówek. Aby dowiedzieć się, jak utworzyć ten nagłówek, zobacz Parametry oceny wymowy.

Pronunciation-Assessment: eyJSZWZlcm...

Kody stanu HTTP

Kod stanu HTTP dla każdej odpowiedzi wskazuje powodzenie lub typowe błędy.

Kod stanu HTTP Opis Możliwe przyczyny
100 Kontynuuj Początkowe żądanie jest akceptowane. Kontynuuj wysyłanie pozostałych danych. (Ten kod jest używany z przesyłaniem danych w częściach).
200 OK Żądanie zakończyło się pomyślnie. Treść odpowiedzi jest obiektem JSON.
400 Nieprawidłowe żądanie Nie podano kodu językowego, język nie jest obsługiwany lub plik dźwiękowy jest nieprawidłowy (na przykład).
401 Nieautoryzowany Klucz zasobu lub token autoryzacji jest nieprawidłowy w określonym regionie lub punkt końcowy jest nieprawidłowy.
403 Zakazane Brak klucza zasobu lub tokenu autoryzacji.

Przykładowe odpowiedzi

Oto typowa odpowiedź dla rozpoznawania simple:

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

Oto typowa odpowiedź dla rozpoznawania detailed:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    },
    {
      "Confidence": 0.92459863,
      "Display": "what is the weather like",
      "ITN": "what is the weather like",
      "Lexical": "what is the weather like",
      "MaskedITN": "what is the weather like"
    }
  ]
}

Oto typowa odpowiedź na uznanie za pomocą oceny wymowy:

{
  "RecognitionStatus": "Success",
  "Offset": 700000,
  "Duration": 8400000,
  "DisplayText": "Good morning.",
  "SNR": 38.76819,
  "NBest": [
    {
      "Confidence": 0.98503506,
      "Lexical": "good morning",
      "ITN": "good morning",
      "MaskedITN": "good morning",
      "Display": "Good morning.",
      "AccuracyScore": 100.0,
      "FluencyScore": 100.0,
      "ProsodyScore": 87.8,
      "CompletenessScore": 100.0,
      "PronScore": 95.1,
      "Words": [
        {
          "Word": "good",
          "Offset": 700000,
          "Duration": 2600000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                ],
                "BreakLength": 0
              },
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
                }
              }
            }
          }
        },
        {
          "Word": "morning",
          "Offset": 3400000,
          "Duration": 5700000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                ],
                "UnexpectedBreak": {
                  "Confidence": 3.5294118e-08
                },
                "MissingBreak": {
                  "Confidence": 1.0
                },
                "BreakLength": 0
              },
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Właściwości odpowiedzi

Wyniki są udostępniane jako dane JSON. Format simple zawiera następujące pola najwyższego poziomu:

Właściwość Opis
RecognitionStatus Stan, taki jak Success pomyślne rozpoznawanie. Zobacz następną tabelę.
DisplayText Rozpoznany tekst po kapitalizacji, interpunkcji, odwrotnej normalizacji tekstów oraz maskowaniu wulgaryzmów. Wyświetlaj tylko w przypadku powodzenia. Odwrotna normalizacja tekstu to konwersja tekstu mówionego na krótsze formy, takie jak 200 dla "dwustu" lub "Dr Smith" dla "doktora Smitha".
Offset Czas (w 100-nanosekundowych jednostkach), w którym rozpoznana mowa rozpoczyna się w strumieniu audio.
Duration Czas trwania (w 100-nanosekundowych jednostkach) rozpoznanej mowy w strumieniu audio.
SNR Współczynnik sygnału do szumu (SNR) rozpoznanej mowy w strumieniu audio.

Pole RecognitionStatus może zawierać następujące wartości:

Stan Opis
Success Rozpoznawanie zakończyło się pomyślnie, a DisplayText pole jest obecne.
NoMatch W strumieniu audio wykryto mowę, ale nie zostały dopasowane żadne słowa z języka docelowego. Ten stan zwykle oznacza, że język rozpoznawania różni się od języka, w jakim mówi użytkownik.
InitialSilenceTimeout Początek strumienia audio to była tylko cisza, a usługa przekroczyła limit czasu podczas oczekiwania na mowę.
BabbleTimeout Początek strumienia audio zawierał tylko szum, a usługa przekroczyła czas oczekiwania na rozpoczęcie mowy.
Error Usługa rozpoznawania napotkała błąd wewnętrzny i nie mogła kontynuować. Spróbuj ponownie, jeśli to możliwe.

Uwaga

Jeśli dźwięk składa się tylko z wulgaryzmów, a parametr zapytania profanity jest ustawiony na wartość remove, usługa nie zwraca wyniku mowy.

Format detailed zawiera więcej form rozpoznanych wyników. Jeśli używasz formatu detailed, DisplayText jest podawany jako Display dla każdego wyniku na liście NBest.

Obiekt na NBest liście może zawierać następujące elementy:

Właściwość Opis
Confidence Współczynnik ufności wpisu z zakresu od 0,0 (bez pewności) do 1,0 (pełna pewność).
Lexical Forma leksykalna rozpoznanego tekstu: rozpoznane rzeczywiste wyrazy.
ITN Tekst odwrotnie znormalizowany (ITN) lub forma kanoniczna rozpoznanego tekstu, z numerami telefonów, liczbami, skrótami ("Lekarz Smith" do "dr Smith") i innymi zastosowanymi przekształceniami.
MaskedITN Formularz ITN z maskowaniem wulgaryzmów, jeśli jest to wymagane.
Display Forma wyświetlania rozpoznanego tekstu z dodanymi znakami interpunkcyjnymi i wielkimi literami. Ten parametr jest taki sam jak DisplayText generowany, gdy format jest ustawiony na simple.
AccuracyScore Dokładność wymowy mowy. Dokładność wskazuje, jak dobrze fonemy pasują do wymowy rodzimych użytkowników języka. Wynik dokładności na poziomie słowa i pełnego tekstu jest agregowany na podstawie wyniku dokładności na poziomie fonemu.
FluencyScore Płynność podanej mowy. Płynność wskazuje, jak ściśle mowa pasuje do użycia przez osoby mówiące w trybie dyskretnym przerw między wyrazami.
ProsodyScore Prosody danej mowy. Prosodia wskazuje, jak naturalna jest dana mowa, w tym akcent, intonacja, szybkość mówienia i rytm.

Aby szczegółowo zapoznać się z definicjami oceny wyników prosody, zobacz Parametry wyników.
CompletenessScore Ustalanie kompletności mowy poprzez obliczenie stosunku wymawianych słów do tekstu referencyjnego.
PronScore Ogólny wynik wskazujący jakość wymowy podanej mowy. Ten wynik jest agregowany z AccuracyScore, FluencyScore i CompletenessScore, z uwzględnieniem ich wag.
ErrorType Wartość wskazująca, czy wyraz zostanie pominięty, wstawiony lub źle wymawiany w porównaniu do ReferenceText. Możliwe wartości to None (czyli brak błędu w tym słowie), Omission, Insertioni Mispronunciation.

Transfer fragmentowany

Fragmentowany transfer (Transfer-Encoding: chunked) może pomóc zmniejszyć opóźnienie rozpoznawania. Umożliwia usłudze rozpoznawania mowy rozpoczęcie przetwarzania pliku audio podczas przesyłania. Interfejs API REST dla krótkiego dźwięku nie zapewnia wyników częściowych ani tymczasowych.

Poniższy przykładowy kod pokazuje, jak wysyłać dźwięk we fragmentach. Tylko pierwszy fragment powinien zawierać nagłówek pliku audio. request HttpWebRequest to obiekt połączony z odpowiednim punktem końcowym REST. audioFile to ścieżka do pliku audio na dysku.

var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1,024-byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1,024 raw bytes from the input audio file.
        buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
        while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
        {
            requestStream.Write(buffer, 0, bytesRead);
        }

        requestStream.Flush();
    }
}

Uwierzytelniania

Każde żądanie wymaga nagłówka autoryzującego. W tej tabeli przedstawiono, które nagłówki są obsługiwane dla każdej funkcji:

Obsługiwany nagłówek autoryzacji Zamiana mowy na tekst Zamiana tekstu na mowę
Ocp-Apim-Subscription-Key Tak Tak
Authorization: Bearer Tak Tak

W przypadku korzystania z nagłówka Ocp-Apim-Subscription-Key należy podać tylko klucz zasobu. Na przykład:

'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'

Jeśli używasz przepływu tokenu elementu nośnego STS z usługą Authorization: Bearer, najpierw prześlij żądanie do punktu końcowego issueToken . W tym żądaniu wymieniasz klucz zasobu na token dostępu, który jest ważny przez 10 minut.

Inną opcją jest użycie uwierzytelniania Microsoft Entra, które używa również nagłówka Authorization: Bearer, ale z tokenem wystawionym za pośrednictwem Microsoft Entra ID. Zobacz Użyj uwierzytelniania Microsoft Entra.

Jak uzyskać token dostępu usługi STS

Aby uzyskać token dostępu usługi STS, prześlij żądanie do punktu końcowego issueToken przy użyciu polecenia Ocp-Apim-Subscription-Key i klucza zasobu.

Punkt issueToken końcowy ma następujący format:

https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken

Zastąp element YourResourceName nazwą swojego zasobu Speech.

Uwaga

Ten punkt końcowy wymaga skonfigurowania niestandardowej poddomeny zasobu. W przypadku zasobów bez domeny niestandardowej należy użyć regionalnego punktu końcowego: https://<region>.api.cognitive.microsoft.com/sts/v1.0/issueToken. Zastąp <region> regionem Azure zasobu (na przykład eastus).

Użyj poniższych przykładów, aby utworzyć żądanie tokenu dostępu.

Przykład HTTP

W tym przykładzie jest proste żądanie HTTP w celu uzyskania tokenu. Zastąp YourSpeechResourceKey kluczem zasobu dla usługi Mowy. Zastąp element YourResourceName nazwą swojego zasobu Speech.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

Treść odpowiedzi zawiera token dostępu w formacie JSON Web Token (JWT).

Przykład programu PowerShell

W tym przykładzie jest prosty skrypt programu PowerShell umożliwiający uzyskanie tokenu dostępu. Zastąp YourSpeechResourceKey kluczem zasobu dla usługi Mowy. Zastąp element YourResourceName nazwą swojego zasobu Speech.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YourSpeechResourceKey'
}

$OAuthToken = Invoke-RestMethod -Method POST `
    -Uri https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken `
    -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Przykład cURL

cURL to narzędzie wiersza polecenia dostępne w systemie Linux (i w Podsystem Windows dla systemu Linux). To polecenie cURL ilustruje sposób uzyskiwania tokenu dostępu. Zastąp YourSpeechResourceKey kluczem zasobu dla usługi Mowy. Zastąp element YourResourceName nazwą swojego zasobu Speech.

curl -v -X POST \
 "https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey"

Przykład w języku C#

Ta klasa języka C# ilustruje sposób uzyskiwania tokenu dostępu. Przekaż klucz zasobu dla usługi rozpoznawania mowy podczas tworzenia wystąpienia klasy. Zastąp element YourResourceName nazwą swojego zasobu Speech.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

przykład Python

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

Jak używać tokenu dostępu

Token dostępu powinien zostać wysłany do usługi jako nagłówek Authorization: Bearer <TOKEN>. Każdy token dostępu jest ważny przez 10 minut. Nowy token można uzyskać w dowolnym momencie, ale aby zminimalizować ruch sieciowy i opóźnienie, zalecamy użycie tego samego tokenu przez dziewięć minut.

Important

Tokeny elementu nośnego są ograniczone do punktu końcowego, który je wystawił. Token uzyskany z YourResourceName.cognitiveservices.azure.com działa tylko w przypadku żądań do tego samego hosta. Token z <region>.api.cognitive.microsoft.com działa tylko względem regionalnych punktów końcowych mowy. Jeśli podczas używania tokenu Bearer wystąpi błąd 401, zamiast tego użyj Ocp-Apim-Subscription-Key z kluczem zasobu, który działa ze wszystkimi formatami punktów końcowych.

Oto przykładowe żądanie HTTP do interfejsu API REST przekształcania mowy na tekst dla krótkiego nagrania audio.

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Korzystanie z uwierzytelniania Microsoft Entra

Aby użyć uwierzytelniania Microsoft Entra z interfejsem API REST do zamiany mowy na tekst dla krótkiego dźwięku, należy utworzyć token dostępu. Kroki uzyskiwania dostępu do tokenu, który składa się z identyfikatora zasobu i tokenu dostępu Microsoft Entra, są takie same jak w przypadku korzystania z pakietu Speech SDK. Wykonaj kroki opisane tutaj Użyj uwierzytelniania Microsoft Entra

  • Utwórz zasób Foundry dla Mowy
  • Konfigurowanie zasobu mowa na potrzeby uwierzytelniania Microsoft Entra
  • Uzyskiwanie tokenu dostępu Microsoft Entra
  • Pobierz identyfikator zasobu Mowy

Po uzyskaniu identyfikatora zasobu i tokenu dostępu Microsoft Entra można utworzyć rzeczywisty token dostępu w następującym formacie:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Należy uwzględnić prefiks "aad#" oraz separator "#" między identyfikatorem zasobu a tokenem dostępu.

Oto przykładowe żądanie HTTP do interfejsu API REST przekształcania mowy na tekst dla krótkiego nagrania audio.

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Aby dowiedzieć się więcej na temat tokenów dostępu Microsoft Entra, w tym okres istnienia tokenu, odwiedź stronę Tokeny dostępu w Platforma tożsamości Microsoft.