Auf Englisch lesen

Freigeben über

Spracherkennung-REST-API für kurze Audiodaten

  • Artikel

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.
  • Sprachübersetzung wird über die REST-API für kurze Audiodaten nicht unterstützt. Sie müssen das Speech SDK verwenden.
  • Batch-Transkription und Custom Speech werden über die REST-API für kurze Audiodaten nicht unterstützt. Sie sollten immer die Spracherkennung-REST-API für Batch-Transkription und Custom Speech 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 Speech-Dienst bestätigt die ursprüngliche Anforderung 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. Dies sind die zulässigen Werte:

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 Verweistext verglichen. Sie werden auf der Grundlage des Vergleichs mit Auslassung oder Einfügung markiert. Zulässige Werte sind False und True. Die Standardeinstellung ist False. Optional
EnableProsodyAssessment Aktiviert die Prosodiebewertung für Ihre Ausspracheauswertung Diese Funktion bewertet Aspekte wie Stress, Intonation, Sprechgeschwindigkeit und Rhythmus. Diese Funktion bietet Einblicke in die Natürlichkeit und Ausdrucksfähigkeit Ihrer Sprache.

Wenn diese Eigenschaft auf True festgelegt ist, wird der Ergebniswert ProsodyScore zurückgegeben.		 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:

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

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

C# 
var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"Word\",\"Dimension\":\"Comprehensive\",\"EnableProsodyAssessment\":\"True\"}}";
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. Beachten Sie, 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.

HTTP 
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.

HTTP 
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:

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

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

JSON 
{
  "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:

JSON 
{
  "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
                }
              }
            }
          }
        }
      ]
    }
  ]
}

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.
SNR Das Signal-zu-Rausch-Verhältnis (SNR) der erkannten Sprache im Audiodatenstrom.

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 erkannt 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 Format detailed enthält zusätzliche 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.
ProsodyScore Prosodie eines gegebenen Texts. Die Prosodie gibt an, wie natürlich die gegebene Sprache ist, einschließlich Betonung, Intonation, Sprechgeschwindigkeit und Rhythmus.

Die Definitionen der Prosodie-Bewertungsergebnisse im Detail finden Sie unter Ergebnisparameter.
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 gibt keine Teil- oder Zwischenergebnisse zurück.

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.

C# 
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, müssen Sie nur Ihren Ressourcenschlüssel bereitstellen. Zum Beispiel:

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

Wenn Sie den Authorization: Bearer-Header verwenden, müssen Sie eine Anforderung an den Endpunkt issueToken stellen. 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 ebenfalls den Authorization: Bearer-Header verwendet, aber mit einem Token, das von Microsoft Entra ID ausgestellt wurde. Weitere Informationen finden Sie unter 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:

HTTP 
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.

HTTP 
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“.

PowerShell 
$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“.

Konsole 
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.

C# 
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

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://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:

HTTP 
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 Spracherkennungs-REST-API für kurze Audiodaten zu verwenden, müssen Sie ein Zugriffstoken erstellen. Die Schritte zum Abrufen des Zugriffstokens, das sich aus Ressourcen-ID und Microsoft Entra-Zugriffstoken zusammensetzt, sind identisch mit der Verwendung des Speech SDK. Führen Sie die Schritte unter Verwenden der Microsoft Entra-Authentifizierung aus.

  • Erstellen einer KI Services-Ressource für Sprache
  • 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 eigentliche Zugriffstoken im folgenden Format erstellt werden:

HTTP 
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Sie müssen das Präfix „aad#“ und das Trennzeichen „#“ (Raute) zwischen Ressourcen-ID und Zugriffstoken einfügen.

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

HTTP 
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.

Nächste Schritte