Spracherkennung-REST-API für kurze Audiodaten

Artikel
09/23/2024

Anwendungsfälle für die Spracherkennung-REST-API für kurze Audiodaten sind begrenzt. Verwenden Sie sie nur in Fällen, in denen Sie das Speech SDK nicht verwenden können.

Bedenken Sie die folgenden Einschränkungen, bevor Sie die Spracherkennung-REST-API für kurze Audiodaten verwenden:

Anforderungen, die die REST-API für kurze Audiodaten verwenden und Audiodaten direkt übertragen, können nur bis zu 60 Sekunden Audiodaten enthalten. Die Eingabeaudioformate sind im Vergleich zum Speech SDK eingeschränkter.
Die REST-API für kurze Audioinhalte gibt nur Endergebnisse zurück. Sie liefert keine Teilergebnisse.
Die Sprachübersetzung wird nicht über die REST-API für kurze Audiodaten unterstützt. Sie müssen das Speech SDK verwenden.
Batchtranskription und benutzerdefinierte Spracherkennung werden nicht über die REST-API für kurze Audiodaten unterstützt. Sie sollten die Spracherkennung immer zur Rest-API für Text für batchtranskription und benutzerdefinierte Spracherkennung verwenden.

Bevor Sie die Spracherkennung-REST-API für kurze Audiodaten verwenden, sollten Sie verstehen, dass Sie einen Tokenaustausch als Teil der Authentifizierung durchführen müssen, um auf den Dienst zugreifen zu können. Weitere Informationen finden Sie unter Authentifizierung.

Regionen und Endpunkte

Der Endpunkt für die REST-API für kurze Audiodaten weist das folgende Format auf:

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

Ersetzen Sie <REGION_IDENTIFIER> durch den Bezeichner, der mit der Region Ihrer Speech-Ressource übereinstimmt.

Hinweis

Informationen zu Azure Government- und Microsoft Azure-Endpunkten, betrieben von 21Vianet, finden Sie in diesem Artikel zu Sovereign Clouds.

Audioformate

Audiodaten werden im Text der HTTP-POST-Anforderung gesendet. Sie müssen in einem der in der folgenden Tabelle aufgeführten Formate vorliegen:

Format	Codec	Bitrate	Samplingrate
WAV	PCM	256 KBit/s	16 kHz, mono
OGG	OPUS	256 KBit/s	16 kHz, mono

Hinweis

Die vorstehenden Formate werden durch die REST-API für kurze Audiodaten und WebSocket im Speech-Dienst unterstützt. Das Speech SDK unterstützt aktuell das WAV-Format mit dem PCM-Codec sowie weitere Formate.

Anforderungsheader

In der folgenden Tabelle sind die erforderlichen und optionalen Header für Spracherkennungsanforderungen aufgeführt:

Header	BESCHREIBUNG	Erforderlich oder optional
`Ocp-Apim-Subscription-Key`	Ihr Ressourcenschlüssel für den Speech-Dienst.	Entweder dieser Header oder `Authorization` ist erforderlich.
`Authorization`	Ein Autorisierungstoken, dem das Wort `Bearer` vorangestellt ist. Weitere Informationen finden Sie unter Authentifizierung.	Entweder dieser Header oder `Ocp-Apim-Subscription-Key` ist erforderlich.
`Pronunciation-Assessment`	Gibt die Parameter zum Anzeigen von Aussprachebewertungen in Erkennungsergebnissen an. Mit diesen Bewertungen wird die Aussprachequalität der Spracheingabe mit Indikatoren wie Genauigkeit, Redefluss und Vollständigkeit beurteilt. Dieser Parameter ist Base64-codierter JSON-Code, der viele ausführliche Parameter enthält. Informationen zum Erstellen dieses Headers finden Sie unter Parameter für die Aussprachebewertung.	Optional
`Content-type`	Beschreibt das Format und den Codec der bereitgestellten Audiodaten. Zulässige Werte sind `audio/wav; codecs=audio/pcm; samplerate=16000` und `audio/ogg; codecs=opus`.	Erforderlich
`Transfer-Encoding`	Gibt an, dass segmentierte Audiodaten anstatt einer einzelnen Datei gesendet werden. Verwenden Sie diesen Header nur, wenn Sie Audiodaten segmentieren.	Optional
`Expect`	Wenn Sie segmentierte Übertragung verwenden, senden Sie `Expect: 100-continue`. Der Sprachdienst erkennt die anfängliche Anforderung an und wartet auf weitere Daten.	Erforderlich, wenn segmentierte Audiodaten gesendet werden.
`Accept`	Wenn angegeben, muss der Wert `application/json` entsprechen. Der Speech-Dienst übermittelt Ergebnisse im JSON-Format. Einige Anforderungsframeworks bieten einen inkompatiblen Standardwert. Es ist eine bewährte Methode, `Accept` immer einzubeziehen.	Optional, wird jedoch empfohlen.

Abfrageparameter

Diese Parameter können in der Abfragezeichenfolge der REST-Anforderung enthalten sein.

Hinweis

Sie müssen den Sprachparameter an die URL anfügen, um HTTP Fehler des Typs „4xx“ zu vermeiden. Das folgende Beispiel zeigt die Spracheinstellung „Englisch (USA)“ über den Endpunkt „USA, Westen“: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parameter	BESCHREIBUNG	Erforderlich oder optional
`language`	Identifiziert die gesprochene Sprache, die erkannt wird. Siehe Unterstützte Sprachen.	Erforderlich
`format`	Gibt das Ergebnisformat an. Zulässige Werte sind `simple` und `detailed`. Einfache Ergebnisse enthalten `RecognitionStatus`, `DisplayText`, `Offset` und `Duration`. Ausführliche Antworten enthalten vier verschiedene Darstellungen des Anzeigetexts. Die Standardeinstellung ist `simple`.	Optional
`profanity`	Gibt den Umgang mit Obszönitäten in Erkennungsergebnissen an. Akzeptierte Werte sind: `masked`, der anstößige Ausdrücke durch Sternchen ersetzt `removed`, der alle anstößigen Ausdrücke aus dem Ergebnis entfernt `raw`, der anstößige Ausdrücke im Ergebnis beibehält. Die Standardeinstellung ist `masked`.	Optional
`cid`	Wenn Sie Speech Studio verwenden, um benutzerdefinierte Modelle zu erstellen, können Sie den Wert der Endpunkt-ID auf der Seite Bereitstellung nutzen. Verwenden Sie den Wert von Endpunkt-ID als Argument für den Parameter `cid` der Abfragezeichenfolge.	Optional

Parameter für die Aussprachebewertung

In dieser Tabelle sind die erforderlichen und optionalen Parameter für die Aussprachebewertung aufgeführt:

Parameter	BESCHREIBUNG	Erforderlich oder optional
`ReferenceText`	Der Text, anhand dessen die Aussprache bewertet wird.	Erforderlich
`GradingSystem`	Das Punktesystem zur Kalibrierung der Bewertung. Das `FivePoint`-System gibt eine 0-5-Gleitkommabewertung und `HundredMark` eine 0-100-Gleitkommabewertung aus. Standardwert: `FivePoint`.	Optional
`Granularity`	Die Granularität der Auswertung. Dies sind die zulässigen Werte: `Phoneme`, das die Bewertung auf der Volltext-, Wort- und Phonemebene zeigt. `Word`, das die Bewertung auf der Volltext- und Wortebene zeigt. `FullText`, das die Bewertung nur für die Volltextebene zeigt. Die Standardeinstellung ist `Phoneme`.	Optional
`Dimension`	Definiert die Ausgabekriterien. Dies sind die zulässigen Werte: `Basic`, das nur die Genauigkeitsbewertung zeigt. `Comprehensive`, das Bewertungen für mehr Dimensionen zeigt (z B. die Werte für den Redefluss und die Vollständigkeit auf Volltextebene und den Fehlertyp auf Wortebene). In den Antworteigenschaften finden Sie Definitionen verschiedener Bewertungsdimensionen und Wortfehlertypen. Die Standardeinstellung ist `Basic`.	Optional
`EnableMiscue`	Aktiviert die Fehlschlagsberechnung. Wenn dieser Parameter aktiviert ist, werden die ausgesprochenen Wörter mit dem Bezugstext verglichen. Sie werden basierend auf dem Vergleich mit Auslassung oder Einfügung gekennzeichnet. Zulässige Werte sind `False` und `True`. Die Standardeinstellung ist `False`.	Optional
`ScenarioId`	Eine GUID, die ein benutzerdefiniertes Punktsystem angibt.	Optional

Hier sehen Sie ein JSON-Beispiel, das die Parameter für die Aussprachebewertung enthält:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "FullText",
  "Dimension": "Comprehensive"
}

Der folgende Beispielcode zeigt, wie die Parameter für die Aussprachebewertung in den Header Pronunciation-Assessment integriert werden:

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

Für die Veröffentlichung von Audiodaten wird dringend das Hochladen per Streaming (segmentierter Transfer) empfohlen, da damit die Latenz deutlich reduziert werden kann. Informationen zum Aktivieren des Streamings finden Sie im Beispielcode in verschiedenen Programmiersprachen.

Hinweis

Weitere Informationen finden Sie unter Aussprachebewertung.

Beispiel für eine Anforderung

Das folgende Beispiel enthält den Hostnamen und die erforderlichen Header. Es ist wichtig zu beachten, dass der Dienst auch Audiodaten erwartet, die in diesem Beispiel nicht enthalten sind. Wie bereits erwähnt, wird die Segmentierung empfohlen, ist aber nicht erforderlich.

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: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

Sie können den folgenden Header hinzufügen, um die Aussprachebewertung zu aktivieren. Informationen zum Erstellen dieses Headers finden Sie unter Parameter für die Aussprachebewertung.

Pronunciation-Assessment: eyJSZWZlcm...

HTTP-Statuscodes

Der HTTP-Statuscode jeder Antwort zeigt den Erfolg oder allgemeine Fehler an.

HTTP-Statuscode	BESCHREIBUNG	Mögliche Ursachen
100	Fortfahren	Die ursprüngliche Anforderung wird akzeptiert. Mit dem Senden der restlichen Daten fortfahren. (Dieser Code wird bei segmentierter Übertragung verwendet.)
200	OK	Die Anforderung wurde erfolgreich gesendet. Der Antworttext ist ein JSON-Objekt.
400	Ungültige Anforderung	Der Sprachcode wurde nicht angegeben, die Sprache wird nicht unterstützt, oder die Audiodatei ist ungültig (beispielsweise).
401	Nicht autorisiert	Ein Ressourcenschlüssel oder ein Autorisierungstoken ist in der angegebenen Region ungültig, oder ein Endpunkt ist ungültig.
403	Verboten	Ein Ressourcenschlüssel oder ein Autorisierungstoken fehlt.

Beispielantworten

Hier sehen Sie eine typische Antwort für die Erkennung simple:

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

Hier sehen Sie eine typische Antwort für die Erkennung 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"
    }
  ]
}

Hier sehen Sie eine typische Antwort für Erkennung mit Bewertung der Aussprache:

{
  "RecognitionStatus": "Success",
  "Offset": "400000",
  "Duration": "11000000",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "good morning",
        "ITN" : "good morning",
        "MaskedITN" : "good morning",
        "Display" : "Good morning.",
        "PronScore" : 84.4,
        "AccuracyScore" : 100.0,
        "FluencyScore" : 74.0,
        "CompletenessScore" : 100.0,
        "Words": [
            {
              "Word" : "Good",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 500000,
              "Duration" : 2700000
            },
            {
              "Word" : "morning",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 5300000,
              "Duration" : 900000
            }
        ]
      }
  ]
}

Antworteigenschaften

Ergebnisse werden im JSON-Format bereitgestellt. Das Format simple schließt die folgenden Felder auf oberster Ebene ein:

Eigenschaft	BESCHREIBUNG
`RecognitionStatus`	Status, z.B. `Success` für erfolgreiche Erkennung. Mehr dazu finden Sie in der nächsten Tabelle.
`DisplayText`	Der erkannte Text nach Groß-/Kleinschreibung, Zeichensetzung, inverser Textnormalisierung und Filterung anstößiger Ausdrücke. Nur bei Erfolg vorhanden. Inverse Textnormalisierung ist die Konvertierung von gesprochenem Text in kürzere Formen, z. B. 200 für „zweihundert“ oder „Dr. Schmidt“ für „Doktor Schmidt“.
`Offset`	Die Zeit (in Einheiten von 100 Nanosekunden), zu der die erkannte Sprache im Audiostream beginnt.
`Duration`	Die Dauer (in Einheiten von 100 Nanosekunden) der erkannten Sprache im Audiostream.

Das RecognitionStatus-Feld kann diese Werte enthalten:

Status	BESCHREIBUNG
`Success`	Die Erkennung war erfolgreich, und das `DisplayText`-Feld ist vorhanden.
`NoMatch`	Im Audiodatenstrom wurde Sprache erkannt, aber es wurde keine Übereinstimmung mit Wörtern aus der Zielsprache festgestellt. Dieser Status bedeutet in der Regel, dass sich die Erkennungssprache von der Sprache unterscheidet, die der Benutzer spricht.
`InitialSilenceTimeout`	Der Anfang des Audiodatenstroms enthielt nur Stille, und beim Warten auf Sprache wurde das Timeout des Diensts aktiviert.
`BabbleTimeout`	Der Anfang des Audiodatenstroms enthielt nur Rauschen, und beim Warten auf Sprache wurde das Timeout des Diensts aktiviert.
`Error`	Der Erkennungsdienst hat einen internen Fehler festgestellt und konnte nicht fortgesetzt werden. Versuchen Sie es noch mal, wenn möglich.

Hinweis

Wenn die Audiodaten nur aus Obszönitäten bestehen und der profanity-Abfrageparameter auf remove festgelegt ist, gibt der Dienst kein Sprachergebnis zurück.

Das detailed Format enthält weitere Formen erkannter Ergebnisse. Bei Verwendung des Formats detailed wird DisplayText für jedes Ergebnis in der NBest-Liste als Display angegeben.

Das Objekt in der NBest-Liste kann Folgendes enthalten:

Eigenschaft	BESCHREIBUNG
`Confidence`	Die Zuverlässigkeitsbewertung des Eintrags von 0,0 (keine Zuverlässigkeit) bis 1,0 (volle Zuverlässigkeit).
`Lexical`	Die lexikalische Form des erkannten Texts: die tatsächlich erkannten Wörter.
`ITN`	Die inverse Textnormalisierung (ITN) oder kanonische Form des erkannten Texts nach der Anwendung von Telefonnummern, Zahlen, Abkürzungen („Doktor Schmidt“ zu „Dr. Schmidt“) und weiteren Transformationen.
`MaskedITN`	Die ITN-Form mit angewendeter Obszönitätenmaskierung, wenn angefordert.
`Display`	Die Anzeigeform des erkannten Texts mit hinzugefügten Satzzeichen und Großschreibung. Dieser Parameter entspricht dem, was `DisplayText` bereitstellt, wenn das Format auf `simple` festgelegt ist.
`AccuracyScore`	Genauigkeit der Aussprache des Texts. Genauigkeit heißt dabei, wie exakt Phoneme der Aussprache eines Muttersprachlers entsprechen. Die Genauigkeitsbewertung auf Wort- und Volltextebene wird aus der Genauigkeitsbewertung auf Phonemebene aggregiert.
`FluencyScore`	Redefluss in der angegebenen Sprache. Der Redefluss bedeutet, wie exakt der ausgegebene Text mit den Pausen zwischen Wörtern eines Muttersprachlers übereinstimmt.
`CompletenessScore`	Vollständigkeit des Texts. Dafür wird das Verhältnis ausgesprochener Wörter zur Texteingabe berechnet.
`PronScore`	Gesamtbewertung, die die Aussprachequalität der bereitgestellten Sprache angibt. Diese Bewertung wird mit Gewichtung aus `AccuracyScore`, `FluencyScore` und `CompletenessScore` aggregiert.
`ErrorType`	Wert, der angibt, ob ein Wort im Vergleich zu `ReferenceText` ausgelassen, eingefügt oder schlecht ausgesprochen wird. Die möglichen Werte sind `None` (d. h. kein Fehler in diesem Wort), `Omission`, `Insertion` und `Mispronunciation`.

Segmentierte Übertragung

Mithilfe der segmentierten Übertragung (Transfer-Encoding: chunked) kann die Erkennungslatenz verringert werden. Es ermöglicht dem Speech-Dienst, mit der Verarbeitung der Audiodatei zu beginnen, während sie übertragen wird. Die REST-API für kurze Audiodaten stellt keine Partielle oder Zwischenergebnisse bereit.

Das folgende Codebeispiel zeigt, wie Sie Audiodaten in Blöcken senden. Nur der erste Block sollte den Header der Audiodatei enthalten. request ist ein HttpWebRequest-Objekt, das mit dem entsprechenden REST-Endpunkt verbunden ist. audioFile ist der Pfad zu einer Audiodatei auf dem Datenträger.

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

Authentication

Jede Anforderung erfordert einen Autorisierungsheader. In dieser Tabelle wird veranschaulicht, welche Header für die einzelnen Features unterstützt werden:

Unterstützter Autorisierungsheader	Spracherkennung	Text-to-Speech
`Ocp-Apim-Subscription-Key`	Ja	Ja
`Authorization: Bearer`	Ja	Ja

Wenn Sie den Ocp-Apim-Subscription-Key Header verwenden, muss nur Ihr Ressourcenschlüssel bereitgestellt werden. Zum Beispiel:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Wenn Sie den Authorization: Bearer Header verwenden, müssen Sie eine Anforderung an den issueToken Endpunkt senden. In dieser Anforderung tauschen Sie Ihren Ressourcenschlüssel gegen ein Zugriffstoken, das 10 Minuten lang gültig ist.

Eine weitere Möglichkeit besteht darin, die Microsoft Entra-Authentifizierung zu verwenden, die auch den Authorization: Bearer Header verwendet, aber mit einem Token, das über die Microsoft Entra-ID ausgestellt wurde. Siehe Verwenden der Microsoft Entra-Authentifizierung.

Abrufen eines Zugriffstokens

Zum Abrufen eines Zugriffstokens müssen Sie eine Anforderung an den issueToken-Endpunkt mit dem Header Ocp-Apim-Subscription-Key und Ihrem Ressourcenschlüssel senden.

Der issueToken-Endpunkt hat folgendes Format:

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Ersetzen Sie <REGION_IDENTIFIER> durch den Bezeichner, der mit der Region Ihres Abonnements übereinstimmt:

Verwenden Sie die folgenden Beispiele, um Ihre Zugriffstokenanforderung zu erstellen.

HTTP-Beispiel

Dieses Beispiel stellt eine einfache HTTP-Anforderung zum Abrufen eines Tokens dar. Ersetzen Sie YOUR_SUBSCRIPTION_KEY durch Ihren Ressourcenschlüssel für den Speech-Dienst. Wenn sich Ihr Abonnement nicht in der Region „USA, Westen“ befindet, ersetzen Sie den Host-Header durch den Hostnamen für Ihre Region.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

Der Antworttext enthält das Zugriffstoken im JWT-Format (JSON Web Token).

PowerShell-Beispiel

Dieses Beispiel stellt ein einfaches PowerShell-Skript zum Abrufen eines Zugriffstokens dar. Ersetzen Sie YOUR_SUBSCRIPTION_KEY durch Ihren Ressourcenschlüssel für den Speech-Dienst. Achten Sie darauf, dass Sie den richtigen Endpunkt für die Region Ihres Abonnements verwenden. In diesem Beispiel ist das „USA, Westen“.

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

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

cURL-Beispiel

cURL ist ein Befehlszeilentool, das in Linux (und im Windows-Subsystem für Linux) zur Verfügung steht. Dieser cURL-Befehl veranschaulicht, wie Sie ein Zugriffstoken abrufen. Ersetzen Sie YOUR_SUBSCRIPTION_KEY durch Ihren Ressourcenschlüssel für den Speech-Dienst. Achten Sie darauf, dass Sie den richtigen Endpunkt für die Region Ihres Abonnements verwenden. In diesem Beispiel ist das „USA, Westen“.

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

C#-Beispiel

Diese C#-Klasse veranschaulicht, wie Sie ein Zugriffstoken abrufen. Übergeben Sie Ihren Ressourcenschlüssel für den Speech-Dienst beim Instanziieren der Klasse. Wenn Ihr Abonnement sich nicht in der Region „USA, Westen“ befindet, ändern Sie den Wert von FetchTokenUri so, dass er der Region Ihres Abonnements entspricht.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.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();
        }
    }
}

Python-Beispiel

# 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://eastus.api.cognitive.microsoft.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)

Verwenden eines Zugriffstokens

Das Zugriffstoken sollte als Authorization: Bearer <TOKEN>-Header an den Dienst gesendet werden. Jedes Zugriffstoken ist 10 Minuten lang gültig. Sie können jederzeit ein neues Token abrufen, allerdings wird empfohlen, das gleiche Token neun Minuten lang zu verwenden, um den Datenverkehr und die Wartezeit zu minimieren.

Hier finden Sie eine HTTP-Beispielanforderung an die Spracherkennung-REST-API für kurze Audiodaten:

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

// Message body here...

Verwenden der Microsoft Entra-Authentifizierung

Um die Microsoft Entra-Authentifizierung mit der Sprachausgabe-REST-API für kurze Audiodaten zu verwenden, müssen Sie ein Zugriffstoken erstellen. Die Schritte zum Abrufen des Zugriffstokens, das aus Ressourcen-ID und Microsoft Entra-Zugriffstoken besteht, sind identisch mit der Verwendung des Speech SDK. Gehen Sie folgendermaßen vor : Verwenden der Microsoft Entra-Authentifizierung

Erstellen einer Speech-Ressource
Konfigurieren der Speech-Ressource für die Microsoft Entra-Authentifizierung
Erhalten eines Microsoft Entra-Zugriffstokens
Erhalten der Sprachressourcen-ID

Nachdem die Ressourcen-ID und das Microsoft Entra-Zugriffstoken abgerufen wurden, kann das tatsächliche Zugriffstoken nach diesem Format erstellt werden:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Sie müssen das Präfix "aad#" und das Trennzeichen "#" (Hash) zwischen Ressourcen-ID und dem Zugriffstoken einschließen.

Hier finden Sie eine HTTP-Beispielanforderung an die Spracherkennung-REST-API für kurze Audiodaten:

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

// Message body here...

Weitere Informationen zu Microsoft Entra-Zugriffstoken, einschließlich der Tokenlebensdauer, finden Sie unter Microsoft Identity Platform – Zugriffstoken.

Teilen über

Spracherkennung-REST-API für kurze Audiodaten

Regionen und Endpunkte

Audioformate

Anforderungsheader

Abfrageparameter

Parameter für die Aussprachebewertung

Beispiel für eine Anforderung

HTTP-Statuscodes

Beispielantworten

Antworteigenschaften

Segmentierte Übertragung

Authentication

Abrufen eines Zugriffstokens

HTTP-Beispiel

PowerShell-Beispiel

cURL-Beispiel

C#-Beispiel

Python-Beispiel

Verwenden eines Zugriffstokens

Verwenden der Microsoft Entra-Authentifizierung

Nächste Schritte

Feedback

Zusätzliche Ressourcen