WebSocket-Protokoll für die Bing-SpracheingabeBing Speech WebSocket protocol

Hinweis

Der neue Spracherkennungsdienst und das SDK ersetzen die Bing-Spracheingabe, die ab dem 14. Januar 2020 nicht mehr genutzt werden kann.The new Speech Service and SDK is replacing Bing Speech, which will no longer work starting January 14, 2020. Informationen zum Umstieg auf den Spracherkennungsdienst finden Sie unter Migration von der Bing-Spracheingabe zum Spracherkennungsdienst.For information on switching to the Speech Service, see Migrating from Bing Speech to the Speech Service.

Die Bing-Spracheingabe ist eine cloudbasierte Plattform mit den am weitesten entwickelten Algorithmen, die für die Konvertierung von Sprachaudiodaten in Text verfügbar sind.Bing Speech is a cloud-based platform that features the most advanced algorithms available for converting spoken audio to text. Mit dem Protokoll für die Bing-Spracheingabe wird die Verbindungseinrichtung zwischen Clientanwendungen und dem Dienst und den Spracherkennungsnachrichten definiert, die zwischen den beiden Seiten ausgetauscht werden (Nachrichten vom Client und Nachrichten vom Dienst).The Bing Speech protocol defines the connection setup between client applications and the service and the speech recognition messages exchanged between counterparts (client-originated Messages and service-originated messages). Außerdem werden Telemetrienachrichten und die Fehlerbehandlung beschrieben.In addition, telemetry messages and error handling are described.

VerbindungsherstellungConnection establishment

Für das Spracherkennungsdienst-Protokoll wird die WebSocket-Standardspezifikation IETF RFC 6455 beachtet.The Speech Service protocol follows the WebSocket standard specification IETF RFC 6455. Am Anfang einer WebSocket-Verbindung steht eine HTTP-Anforderung mit HTTP-Headern, mit denen die Absicht des Clients angegeben wird, für die Verbindung ein Upgrade auf ein WebSocket durchzuführen, anstatt die HTTP-Semantik zu verwenden.A WebSocket connection starts out as an HTTP request that contains HTTP headers that indicate the client's desire to upgrade the connection to a WebSocket instead of using HTTP semantics. Der Server gibt die Bereitschaft an, sich an der WebSocket-Verbindung zu beteiligen, indem die HTTP-Antwort 101 Switching Protocols zurückgegeben wird.The server indicates its willingness to participate in the WebSocket connection by returning an HTTP 101 Switching Protocols response. Nach dem Austausch dieses Handshakes lassen sowohl der Client als auch der Dienst den Socket geöffnet und beginnen damit, ein nachrichtenbasiertes Protokoll zum Senden und Empfangen von Informationen zu nutzen.After the exchange of this handshake, both client and service keep the socket open and begin using a message-based protocol to send and receive information.

Zum Starten des Vorgangs für den WebSocket-Handshake sendet die Clientanwendung eine HTTPS GET-Anforderung an den Dienst.To begin the WebSocket handshake, the client application sends an HTTPS GET request to the service. Sie enthält WebSocket-Standardheader für das Upgrade und weitere sprachspezifische Header.It includes standard WebSocket upgrade headers along with other headers that are specific to speech.

GET /speech/recognition/interactive/cognitiveservices/v1 HTTP/1.1
Host: speech.platform.bing.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Authorization: t=EwCIAgALBAAUWkziSCJKS1VkhugDegv7L0eAAJqBYKKTzpPZOeGk7RfZmdBhYY28jl&p=
X-ConnectionId: A140CAF92F71469FA41C72C7B5849253
Origin: https://speech.platform.bing.com

Der Dienst antwortet wie folgt:The service responds with:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: upgrade
Sec-WebSocket-Key: 2PTTXbeeBXlrrUNsY15n01d/Pcc=
Set-Cookie: SpeechServiceToken=AAAAABAAWTC8ncb8COL; expires=Wed, 17 Aug 2016 15:39:06 GMT; domain=bing.com; path="/"
Date: Wed, 17 Aug 2016 15:03:52 GMT

Für alle Sprachanforderungen ist die TLS-Verschlüsselung erforderlich.All speech requests require the TLS encryption. Die Verwendung von unverschlüsselten Sprachanforderungen wird nicht unterstützt.The use of unencrypted speech requests is not supported. Die folgende TLS-Version wird unterstützt:The following TLS version is supported:

  • TLS 1.2TLS 1.2

VerbindungsbezeichnerConnection identifier

Für den Spracherkennungsdienst ist es erforderlich, dass alle Clients eine eindeutige ID zum Identifizieren der Verbindung enthalten.Speech Service requires that all clients include a unique ID to identify the connection. Clients müssen den X-ConnectionId-Header enthalten, wenn sie einen WebSocket-Handshake starten.Clients must include the X-ConnectionId header when they start a WebSocket handshake. Der X-ConnectionId-Header muss ein UUID-Wert (Universally Unique Identifier) sein.The X-ConnectionId header must be a universally unique identifier (UUID) value. WebSocket-Upgradeanforderungen, die X-ConnectionId nicht enthalten, keinen Wert für den X-ConnectionId-Header angeben oder keinen gültigen UUID-Wert enthalten, werden vom Dienst mit der HTTP-Antwort 400 Bad Request abgelehnt.WebSocket upgrade requests that do not include the X-ConnectionId, do not specify a value for the X-ConnectionId header, or do not include a valid UUID value are rejected by the service with an HTTP 400 Bad Request response.

AuthorizationAuthorization

Zusätzlich zu Standardheadern für den WebSocket-Handshake wird für Sprachanforderungen ein Authorization-Header benötigt.In addition to the standard WebSocket handshake headers, speech requests require an Authorization header. Verbindungsanforderungen ohne diesen Header werden vom Dienst mit der HTTP-Antwort 403 Forbidden abgelehnt.Connection requests without this header are rejected by the service with an HTTP 403 Forbidden response.

Der Authorization-Header muss ein JWT-Zugriffstoken (JSON Web Token) enthalten.The Authorization header must contain a JSON Web Token (JWT) access token.

Informationen dazu, wie Sie API-Schlüssel abonnieren und beziehen, die zum Abrufen von gültigen JWT-Zugriffstoken verwendet werden, finden Sie auf der Seite Cognitive Services ausprobieren.For information about how to subscribe and obtain API keys that are used to retrieve valid JWT access tokens, see the Cognitive Services subscription page.

Der API-Schlüssel wird an den Tokendienst übergeben.The API key is passed to the token service. Beispiel:For example:

POST https://api.cognitive.microsoft.com/sts/v1.0/issueToken
Content-Length: 0

Für den Tokenzugriff sind die folgenden Headerinformationen erforderlich.The following header information is required for token access.

NameName FormatFormat BESCHREIBUNGDescription
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key ASCIIASCII Your subscription key (Ihr Abonnementschlüssel)Your subscription key

Der Tokendienst gibt das JWT-Zugriffstoken im Format text/plain zurück.The token service returns the JWT access token as text/plain. Das JWT wird dann im Format Base64 access_token als Authorization-Header mit der Zeichenfolge Bearer als Präfix an den Handshake übergeben.Then the JWT is passed as a Base64 access_token to the handshake as an Authorization header prefixed with the string Bearer. Beispiel:For example:

Authorization: Bearer [Base64 access_token]

CookiesCookies

Clients müssen HTTP-Cookies unterstützen, wie unter RFC 6265 angegeben.Clients must support HTTP cookies as specified in RFC 6265.

HTTP-UmleitungHTTP redirection

Clients müssen die Standardumleitungsmechanismen unterstützen, die über die HTTP-Protokollspezifikation angegeben werden.Clients must support the standard redirection mechanisms specified by the HTTP protocol specification.

SprachendpunkteSpeech endpoints

Clients müssen einen geeigneten Endpunkt des Spracherkennungsdiensts nutzen.Clients must use an appropriate endpoint of Speech Service. Der Endpunkt basiert auf dem Erkennungsmodus und der Sprache.The endpoint is based on recognition mode and language. In der Tabelle sind einige Beispiele angegeben.The table shows some examples.

ModeMode PathPath Dienst-URIService URI
InteractiveInteractive /speech/recognition/interactive/cognitiveservices/v1/speech/recognition/interactive/cognitiveservices/v1 https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=pt-BR
UnterhaltungConversation /speech/recognition/conversation/cognitiveservices/v1/speech/recognition/conversation/cognitiveservices/v1 https://speech.platform.bing.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US
DiktierenDictation /speech/recognition/dictation/cognitiveservices/v1/speech/recognition/dictation/cognitiveservices/v1 https://speech.platform.bing.com/speech/recognition/dictation/cognitiveservices/v1?language=fr-FR

Weitere Informationen finden Sie auf der Seite zum Dienst-URI.For more information, see the Service URI page.

Melden von VerbindungsproblemenReport connection problems

Clients sollten sofort alle Probleme melden, die beim Herstellen einer Verbindung auftreten.Clients should immediately report all problems encountered while making a connection. Das Nachrichtenprotokoll für das Melden von fehlgeschlagenen Verbindungen ist unter Telemetriedaten für Verbindungsfehler beschrieben.The message protocol for reporting failed connections is described in Connection failure telemetry.

Einschränkungen der VerbindungsdauerConnection duration limitations

Im Vergleich zu typischen Webdienst-HTTP-Verbindungen haben WebSocket-Verbindungen eine lange Dauer.When compared with typical web service HTTP connections, WebSocket connections last a long time. Der Spracherkennungsdienst schränkt die Dauer der WebSocket-Verbindungen mit dem Dienst ein:Speech Service places limitations on the duration of the WebSocket connections to the service:

  • Die maximale Dauer für aktive WebSocket-Verbindungen beträgt 10 Minuten.The maximum duration for any active WebSocket connection is 10 minutes. Eine Verbindung ist aktiv, wenn entweder der Dienst oder der Client WebSocket-Nachrichten über diese Verbindung sendet.A connection is active if either the service or the client sends WebSocket messages over that connection. Der Dienst beendet die Verbindung ohne Warnung, wenn die Höchstdauer erreicht ist.The service terminates the connection without warning when the limit is reached. Für Clients sollten Benutzerszenarien entwickelt werden, bei denen die Verbindung nicht so lange aktiv bleiben muss, dass die maximale Verbindungslebensdauer erreicht bzw. fast erreicht wird.Clients should develop user scenarios that do not require the connection to remain active at or near the maximum connection lifetime.

  • Die maximale Dauer für inaktive WebSocket-Verbindungen beträgt 180 Sekunden.The maximum duration for any inactive WebSocket connection is 180 seconds. Eine Verbindung ist inaktiv, wenn weder der Dienst noch der Client eine WebSocket-Nachricht über die Verbindung sendet.A connection is inactive if neither the service nor the client sent a WebSocket message over the connection. Nachdem die maximale Lebensdauer für Inaktivität erreicht wurde, beendet der Dienst die inaktive WebSocket-Verbindung.After the maximum inactive lifetime is reached, the service terminates the inactive WebSocket connection.

NachrichtentypenMessage types

Nachdem zwischen dem Client und dem Dienst eine WebSocket-Verbindung hergestellt wurde, kann sowohl der Client als auch der Dienst Nachrichten senden.After a WebSocket connection is established between the client and the service, both the client and the service can send messages. In diesem Abschnitt wird das Format dieser WebSocket-Nachrichten beschrieben.This section describes the format of these WebSocket messages.

In der Spezifikation IETF RFC 6455 ist angegeben, dass WebSocket-Nachrichten Daten übertragen können, indem entweder eine Text- oder binäre Codierung verwendet wird.IETF RFC 6455 specifies that WebSocket messages can transmit data by using either a text or a binary encoding. Für die beiden Codierungen werden unterschiedliche „On-the-Wire-Formate“ verwendet.The two encodings use different on-the-wire formats. Jedes Format ist für das effiziente Codieren, Übertragen und Decodieren der Nachrichtennutzlast optimiert.Each format is optimized for efficient encoding, transmission, and decoding of the message payload.

WebSocket-TextnachrichtenText WebSocket messages

WebSocket-Textnachrichten verfügen über eine Nutzlast mit Textinformationen, die einen Abschnitt mit Headern und einen Text umfassen, die durch die vertrauten doppelten Absatzzeichenpaare für HTTP-Nachrichten getrennt sind.Text WebSocket messages carry a payload of textual information that consists of a section of headers and a body separated by the familiar double-carriage-return newline pair used for HTTP messages. Und wie bei HTTP-Nachrichten auch, werden in WebSocket-Textnachrichten Header im Format Name:Wert getrennt durch ein einzelnes Absatzzeichenpaar angegeben.And, like HTTP messages, text WebSocket messages specify headers in name: value format separated by a single-carriage-return newline pair. Für alle Texte, die in einer WebSocket-Textnachricht enthalten sind, muss die UTF-8-Codierung verwendet werden.Any text included in a text WebSocket message must use UTF-8 encoding.

Bei WebSocket-Textnachrichten muss ein Nachrichtenpfad im Path-Header angegeben werden.Text WebSocket messages must specify a message path in the header Path. Der Wert dieses Headers muss einen der Sprachprotokollnachricht-Typen aufweisen, die weiter unten in diesem Dokument definiert sind.The value of this header must be one of the speech protocol message types defined later in this document.

Binäre WebSocket-NachrichtenBinary WebSocket messages

Binäre WebSocket-Nachrichten verfügen über eine binäre Nutzlast.Binary WebSocket messages carry a binary payload. Im Spracherkennungsdienst-Protokoll werden Audiodaten an den bzw. vom Dienst übertragen, indem binäre WebSocket-Nachrichten verwendet werden.In the Speech Service protocol, audio is transmitted to and received from the service by using binary WebSocket messages. Alle andere Nachrichten sind WebSocket-Textnachrichten.All other messages are text WebSocket messages.

Wie WebSocket-Textnachrichten auch, bestehen binäre WebSocket-Nachrichten aus einem Header und einem Textabschnitt.Like text WebSocket messages, binary WebSocket messages consist of a header and a body section. In den ersten beiden Bytes der binären WebSocket-Nachricht ist in Big-Endian-Reihenfolge die 16-Bit-Integergröße des Headerabschnitts angegeben.The first 2 bytes of the binary WebSocket message specify, in big-endian order, the 16-bit integer size of the header section. Die Mindestgröße für den Headerabschnitt beträgt 0 Byte.The minimum header section size is 0 bytes. Die maximale Größe beträgt 8.192 Byte.The maximum size is 8,192 bytes. Für den Text in den Headern von binären WebSocket-Nachrichten muss die US-ASCII-Codierung verwendet werden.The text in the headers of binary WebSocket messages must use US-ASCII encoding.

Header in einer binären WebSocket-Nachricht sind in demselben Format wie in WebSocket-Textnachrichten codiert.Headers in a binary WebSocket message are encoded in the same format as in text WebSocket messages. Das Format Name:Wert ist durch ein einzelnes Absatzzeichenpaar getrennt.The name:value format is separated by a single-carriage-return newline pair. Bei binären WebSocket-Nachrichten muss ein Nachrichtenpfad im Path-Header angegeben werden.Binary WebSocket messages must specify a message path in the header Path. Der Wert dieses Headers muss einen der Sprachprotokollnachricht-Typen aufweisen, die weiter unten in diesem Dokument definiert sind.The value of this header must be one of the speech protocol message types defined later in this document.

Im Spracherkennungsdienst-Protokoll werden WebSocket-Nachrichten sowohl in Textform als auch in binärer Form verwendet.Both text and binary WebSocket messages are used in the Speech Service protocol.

Nachrichten vom ClientClient-originated messages

Nachdem die Verbindung hergestellt wurde, können sowohl der Client als auch der Dienst mit dem Senden von Nachrichten beginnen.After the connection is established, both the client and the service can start to send messages. In diesem Abschnitt werden das Format und die Nutzlast von Nachrichten beschrieben, die von Clientanwendungen an den Spracherkennungsdienst gesendet werden.This section describes the format and payload of messages that client applications send to Speech Service. Im Abschnitt Nachrichten vom Dienst sind die Nachrichten angegeben, die vom Spracherkennungsdienst stammen und an die Clientanwendungen gesendet werden.The section Service-originated messages presents the messages that originate in Speech Service and are sent to the client applications.

Die Hauptnachrichten, die vom Client an die Dienste gesendet werden, sind Nachrichten der Art speech.config, audio und telemetry.The main messages sent by the client to the services are speech.config, audio, and telemetry messages. Bevor wir uns die einzelnen Nachrichten genauer ansehen, werden die allgemein erforderlichen Nachrichtenheader für diese Nachrichten beschrieben.Before we consider each message in detail, the common required message headers for all these messages are described.

Erforderliche NachrichtenheaderRequired message headers

Die unten angegebenen Header sind für alle vom Client stammenden Nachrichten erforderlich.The following headers are required for all client-originated messages.

HeaderHeader WertValue
PathPath Der Nachrichtenpfad gemäß Angabe in diesem DokumentThe message path as specified in this document
X-RequestIdX-RequestId UUID im Format „no-dash“UUID in "no-dash" format
X-TimestampX-Timestamp Zeitstempel der UTC-Uhrzeit des Clients im Format ISO 8601Client UTC clock time stamp in ISO 8601 format

X-RequestId-HeaderX-RequestId header

Vom Client stammende Anforderungen werden mit dem X-RequestId-Nachrichtenheader eindeutig identifiziert.Client-originated requests are uniquely identified by the X-RequestId message header. Dieser Header ist für alle vom Client stammenden Nachrichten erforderlich.This header is required for all client-originated messages. Der Wert des X-RequestId-Headers muss eine UUID im Format „no-dash“ (ohne Bindestriche) sein, z.B. 123e4567e89b12d3a456426655440000.The X-RequestId header value must be a UUID in "no-dash" form, for example, 123e4567e89b12d3a456426655440000. Das kanonische Format 123e4567-e89b-12d3-a456-426655440000 ist nicht möglich.It cannot be in the canonical form 123e4567-e89b-12d3-a456-426655440000. Anforderungen ohne X-RequestId-Header oder mit einem Headerwert, für die ein falsches Format für UUIDs verwendet wird, führen dazu, dass der Dienst die WebSocket-Verbindung beendet.Requests without an X-RequestId header or with a header value that uses the wrong format for UUIDs cause the service to terminate the WebSocket connection.

X-Timestamp-HeaderX-Timestamp header

Jede Nachricht, die vom Spracherkennungsdienst an eine Clientanwendung gesendet wird, muss einen X-Timestamp-Header enthalten.Each message sent to Speech Service by a client application must include an X-Timestamp header. Der Wert für diesen Header ist die Uhrzeit, zu der der Client die Nachricht sendet.The value for this header is the time when the client sends the message. Anforderungen ohne X-Timestamp-Header oder mit einem Headerwert, für die ein falsches Format verwendet wird, führen dazu, dass der Dienst die WebSocket-Verbindung beendet.Requests without an X-Timestamp header or with a header value that uses the wrong format cause the service to terminate the WebSocket connection.

Der Wert des X-Timestamp-Headers muss das folgende Format aufweisen: 'jjjj'-'MM'-'tt'T'HH':'mm':'ss'.'fffffffZ'. Hierbei steht „fffffffZ“ für den Bruchteil einer Sekunde.The X-Timestamp header value must be of the form 'yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffZ' where 'fffffff' is a fraction of a second. Beispielsweise steht der Wert „12,5“ für „12 + 5/10 Sekunden“ und „12,526“ für „12 plus 526/1000 Sekunden“.For example, '12.5' means '12 + 5/10 seconds' and '12.526' means '12 plus 526/1000 seconds'. Dieses Format erfüllt die Anforderungen von ISO 8601 und ermöglicht – im Gegensatz zum HTTP-Standardheader Date – eine Auflösung auf Millisekundenebene.This format complies with ISO 8601 and, unlike the standard HTTP Date header, it can provide millisecond resolution. Clientanwendungen runden Zeitstempel ggf. auf die nächste Millisekunde.Client applications might round time stamps to the nearest millisecond. Für Clientanwendungen muss sichergestellt werden, dass die Geräteuhr die Uhrzeit genau nachverfolgt, indem ein NTP-Server (Network Time Protocol, Netzwerkzeitprotokoll) verwendet wird.Client applications need to ensure that the device clock accurately tracks time by using a Network Time Protocol (NTP) server.

speech.config-NachrichtMessage speech.config

Der Spracherkennungsdienst muss die Merkmale Ihrer Anwendung kennen, um die bestmögliche Spracherkennung bereitstellen zu können.Speech Service needs to know the characteristics of your application to provide the best possible speech recognition. Die Daten zu den erforderlichen Merkmalen umfassen Informationen zum Gerät und zum Betriebssystem, auf dem Ihre Anwendung basiert.The required characteristics data includes information about the device and OS that powers your application. Sie geben diese Informationen in der speech.config-Nachricht an.You supply this information in the speech.config message.

Clients müssen sofort eine speech.config-Nachricht senden, nachdem sie die Verbindung mit dem Spracherkennungsdienst hergestellt haben und bevor sie audio-Nachrichten senden.Clients must send a speech.config message immediately after they establish the connection to Speech Service and before they send any audio messages. Sie müssen eine speech.config-Nachricht nur einmal pro Verbindung senden.You need to send a speech.config message only once per connection.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
BodyBody Nutzlast als JSON-StrukturThe payload as a JSON structure

Erforderliche NachrichtenheaderRequired message headers

HeadernameHeader name WertValue
PathPath speech.config
X-TimestampX-Timestamp Zeitstempel der UTC-Uhrzeit des Clients im Format ISO 8601Client UTC clock time stamp in ISO 8601 format
Content-TypeContent-Type application/json; charset=utf-8application/json; charset=utf-8

Wie bei allen vom Client stammenden Nachrichten im Spracherkennungsdienst-Protokoll, muss die speech.config-Nachricht einen X-Timestamp-Header enthalten, mit dem die UTC-Uhrzeit des Clients für den Zeitpunkt aufgezeichnet wird, zu dem die Nachricht an den Dienst gesendet wurde.As with all client-originated messages in the Speech Service protocol, the speech.config message must include an X-Timestamp header that records the client UTC clock time when the message was sent to the service. Für die speech.config-Nachricht ist kein X-RequestId-Header erforderlich, da diese Nachricht nicht einer bestimmten Sprachanforderung zugeordnet ist.The speech.config message does not require an X-RequestId header because this message isn't associated with a particular speech request.

NachrichtennutzlastMessage payload

Die Nutzlast der speech.config-Nachricht ist eine JSON-Struktur, die Informationen zur Anwendung enthält.The payload of the speech.config message is a JSON structure that contains information about the application. Diese Informationen sind im folgenden Beispiel dargestellt.The following example shows this information. Informationen im Client- und Gerätekontext sind im context-Element der JSON-Struktur enthalten.Client and device context information is included in the context element of the JSON structure.

{
  "context": {
    "system": {
      "version": "2.0.12341",
    },
    "os": {
      "platform": "Linux",
      "name": "Debian",
      "version": "2.14324324"
    },
    "device": {
      "manufacturer": "Contoso",
      "model": "Fabrikan",
      "version": "7.341"
      }
    },
  }
}
SystemelementSystem element

Das system.version-Element der speech.config-Nachricht enthält die Version der Sprach-SDK-Software, die von der Clientanwendung oder vom Gerät verwendet wird.The system.version element of the speech.config message contains the version of the speech SDK software used by the client application or device. Der Wert hat das Format major.minor.build.branch.The value is in the form major.minor.build.branch. Sie können die Komponente branch weglassen, falls sie nicht benötigt wird.You can omit the branch component if it's not applicable.

BetriebssystemelementOS element
FeldField BESCHREIBUNGDescription VerwendungUsage
os.platformos.platform Die Betriebssystemplattform, auf der die Anwendung gehostet wird, z.B. Windows, Android, iOS oder LinuxThe OS platform that hosts the application, for example, Windows, Android, iOS, or Linux ErforderlichRequired
os.nameos.name Der Produktname des Betriebssystems, z.B. Debian oder Windows 10The OS product name, for example, Debian or Windows 10 ErforderlichRequired
os.versionos.version Die Version des Betriebssystems im Format major.minor.build.branchThe version of the OS in the form major.minor.build.branch ErforderlichRequired
GeräteelementDevice element
FeldField BESCHREIBUNGDescription VerwendungUsage
device.manufacturerdevice.manufacturer Hersteller der GerätehardwareThe device hardware manufacturer ErforderlichRequired
device.modeldevice.model GerätemodellThe device model ErforderlichRequired
device.versiondevice.version Die Version der Gerätesoftware, die vom Gerätehersteller angegeben wird.The device software version provided by the device manufacturer. Mit diesem Wert wird eine Version des Geräts angegeben, die vom Hersteller nachverfolgt werden kann.This value specifies a version of the device that can be tracked by the manufacturer. ErforderlichRequired

audio-NachrichtMessage audio

Für Sprache aktivierte Clientanwendungen senden Audiodaten an den Spracherkennungsdienst, indem der Audiodatenstrom in eine Reihe von Audioblöcken unterteilt wird.Speech-enabled client applications send audio to Speech Service by converting the audio stream into a series of audio chunks. Mit jedem Audioblock wird ein Segment mit den Sprachaudiodaten übertragen, das vom Dienst transkribiert werden muss.Each chunk of audio carries a segment of the spoken audio that's to be transcribed by the service. Die maximale Größe eines einzelnen Audioblocks beträgt 8.192 Byte.The maximum size of a single audio chunk is 8,192 bytes. Bei Audiodatenstrom-Nachrichten handelt es sich um Binäre WebSocket-Nachrichten.Audio stream messages are Binary WebSocket messages.

Clients nutzen die audio-Nachricht, um einen Audioblock an den Dienst zu senden.Clients use the audio message to send an audio chunk to the service. Clients lesen Audiodaten in Blöcken über das Mikrofon und senden diese Blöcke zum Transkribieren an den Spracherkennungsdienst.Clients read audio from the microphone in chunks and send these chunks to Speech Service for transcription. Die erste audio-Nachricht muss einen wohlgeformten Header enthalten, über den richtig angegeben wird, dass die Audiodaten mit einem der vom Dienst unterstützten Codierungsformate konform sind.The first audio message must contain a well-formed header that properly specifies that the audio conforms to one of the encoding formats supported by the service. Zusätzliche audio-Nachrichten enthalten nur den binären Audiodatenstrom, der über das Mikrofon eingelesen wird.Additional audio messages contain only the binary audio stream data read from the microphone.

Clients können optional eine audio-Nachricht mit einer Textlänge von null senden.Clients might optionally send an audio message with a zero-length body. Über diese Nachricht wird dem Dienst mitgeteilt, dass der Client über die Beendigung der Spracheingabe durch den Benutzer informiert ist, die Äußerung beendet ist und das Mikrofon ausgeschaltet wurde.This message tells the service that the client knows that the user stopped speaking, the utterance is finished, and the microphone is turned off.

Der Spracherkennungsdienst verwendet die erste audio-Nachricht, die einen eindeutigen Anforderungsbezeichner enthält, um den Beginn eines neuen Anforderung/Antwort-Zyklus oder Vorgangs (als Turn bezeichnet) zu signalisieren.Speech Service uses the first audio message that contains a unique request identifier to signal the start of a new request/response cycle or turn. Nachdem der Dienst eine audio-Nachricht mit einem neuen Anforderungsbezeichner empfangen hat, werden alle in die Warteschlange eingereihten oder nicht gesendeten Nachrichten verworfen, die einem vorherigen „Turn“ zugeordnet sind.After the service receives an audio message with a new request identifier, it discards any queued or unsent messages that are associated with any previous turn.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding BinaryBinary
BodyBody Die Binärdaten für den Audioblock.The binary data for the audio chunk. Die maximale Größe beträgt 8.192 Byte.Maximum size is 8,192 bytes.

Erforderliche NachrichtenheaderRequired message headers

Die folgenden Header sind für alle audio-Nachrichten erforderlich.The following headers are required for all audio messages.

HeaderHeader WertValue
PathPath audio
X-RequestIdX-RequestId UUID im Format „no-dash“UUID in "no-dash" format
X-TimestampX-Timestamp Zeitstempel der UTC-Uhrzeit des Clients im Format ISO 8601Client UTC clock time stamp in ISO 8601 format
Content-TypeContent-Type Der Audioinhaltstyp.The audio content type. Der Typ muss entweder audio/x-wav (PCM) oder audio/silk (SILK) lauten.The type must be either audio/x-wav (PCM) or audio/silk (SILK).

Unterstützte AudiocodierungenSupported audio encodings

In diesem Abschnitt sind die vom Spracherkennungsdienst unterstützten Audiocodecs beschrieben.This section describes the audio codecs supported by Speech Service.

PCMPCM

Der Spracherkennungsdienst akzeptiert unkomprimierte PCM-Audiodaten (Pulse Code Modulation).Speech Service accepts uncompressed pulse code modulation (PCM) audio. Da Audiodaten im WAV-Format an den Dienst gesendet werden, muss der erste Audioblock einen gültigen RIFF-Header (Resource Interchange File Format) enthalten.Audio is sent to the service in WAV format, so the first audio chunk must contain a valid Resource Interchange File Format (RIFF) header. Wenn ein Client einen „Turn“ mit einem Audioblock initiiert, der keinen gültigen RIFF-Header enthält, lehnt der Dienst die Anforderung ab und beendet die WebSocket-Verbindung.If a client initiates a turn with an audio chunk that does not include a valid RIFF header, the service rejects the request and terminates the WebSocket connection.

Das Sampling von PCM-Audiodaten muss mit 16 kHz und 16 Bit pro Abtastvorgang sowie mit einem Kanal (riff-16khz-16bit-mono-pcm) durchgeführt werden.PCM audio must be sampled at 16 kHz with 16 bits per sample and one channel (riff-16khz-16bit-mono-pcm). Der Spracherkennungsdienst unterstützt keine Stereo-Audiodatenströme und lehnt Audiodatenströme ab, für die nicht die angegebene Bitrate, Abtastrate oder Anzahl von Kanälen verwendet wird.Speech Service doesn't support stereo audio streams and rejects audio streams that do not use the specified bit rate, sample rate, or number of channels.

OpusOpus

Opus ist ein offener, gebührenfreier und sehr vielseitiger Audiocodec.Opus is an open, royalty-free, highly versatile audio codec. Der Spracherkennungsdienst unterstützt Opus mit einer konstanten Bitrate von 32000 oder 16000.Speech Service supports Opus at a constant bit rate of 32000 or 16000. Nur der Container OGG für Opus, der über den MIME-Typ audio/ogg angegeben wird, wird derzeit unterstützt.Only the OGG container for Opus is currently supported that is specified by the audio/ogg mime type.

Ändern Sie zum Nutzen von Opus das JavaScript-Beispiel, und ändern Sie die RecognizerSetup-Methode in den Rückgabemodus.To use Opus, modify the JavaScript sample and change the RecognizerSetup method to return.

return SDK.CreateRecognizerWithCustomAudioSource(
            recognizerConfig,
            authentication,
            new SDK.MicAudioSource(
                     new SDK.OpusRecorder(
                     {
                         mimeType: "audio/ogg",
                         bitsPerSecond: 32000
                     }
              )
          ));

Erkennen des Endes der SpracheingabeDetect end of speech

Menschen geben nicht explizit an, dass sie die Spracheingabe beendet haben.Humans do not explicitly signal when they're finished speaking. Alle Anwendungen, die Sprache als Eingabe akzeptieren, haben zwei Möglichkeiten, um das Ende der Spracheingabe in einem Audiodatenstrom zu verarbeiten: Erkennung auf Dienstseite und Erkennung auf Clientseite.Any application that accepts speech as input has two choices for handling the end of speech in an audio stream: service end-of-speech detection and client end-of-speech detection. Die Erkennung auf Dienstseite bietet hierbei normalerweise eine höhere Benutzerfreundlichkeit.Of these two choices, service end-of-speech detection usually provides a better user experience.

Erkennung des Endes der Spracheingabe auf DienstseiteService end-of-speech detection

Um ein möglichst gutes Freisprechen zu ermöglichen, erlauben Anwendungen es dem Dienst, die Schritte zur Erkennung des Endes der Spracheingabe durch den Benutzer auszuführen.To build the ideal hands-free speech experience, applications allow the service to detect when the user has finished speaking. Clients senden über das Mikrofon eingegangene Audiodaten als audio-Blöcke, bis der Dienst keine Sprache mehr wahrnimmt und mit der Nachricht speech.endDetected antwortet.Clients send audio from the microphone as audio chunks until the service detects silence and responds back with a speech.endDetected message.

Erkennung des Endes der Spracheingabe auf ClientseiteClient end-of-speech detection

Clientanwendungen, die für Benutzer das Signalisieren des Endes der Spracheingabe ermöglichen, können ebenfalls das entsprechende Signal an den Dienst übermitteln.Client applications that allow the user to signal the end of speech in some way also can give the service that signal. Beispielsweise kann eine Clientanwendung über die Schaltfläche „Beenden“ oder „Stumm schalten“ verfügen, die Benutzer betätigen können.For example, a client application might have a "Stop" or "Mute" button that the user can press. Um das Ende der Spracheingabe zu signalisieren, senden Clientanwendungen eine audio-Blocknachricht mit einer Textlänge von null.To signal end-of-speech, client applications send an audio chunk message with a zero-length body. Der Spracherkennungsdienst interpretiert diese Nachricht als das Ende des eingehenden Audiodatenstroms.Speech Service interprets this message as the end of the incoming audio stream.

telemetry-NachrichtMessage telemetry

Clientanwendungen müssen das Ende jedes „Turns“ bestätigen, indem Telemetriedaten dazu an den Spracherkennungsdienst gesendet werden.Client applications must acknowledge the end of each turn by sending telemetry about the turn to Speech Service. Durch die Bestätigung des „Turn“-Endes kann der Spracherkennungsdienst sicherstellen, dass alle Nachrichten, die für den Abschluss des Anforderung/Antwort-Vorgangs erforderlich sind, vom Client richtig empfangen wurden.Turn-end acknowledgment allows Speech Service to ensure that all messages necessary for completion of the request and its response were properly received by the client. Außerdem kann der Spracherkennungsdienst durch das Bestätigen des „Turn“-Endes auch überprüfen, ob die Clientanwendungen wie erwartet funktionieren.Turn-end acknowledgment also allows Speech Service to verify that the client applications are performing as expected. Diese Informationen sind wertvoll, falls Sie Hilfe bei der Problembehandlung für Ihre sprachaktivierte Anwendung benötigen.This information is invaluable if you need help troubleshooting your speech-enabled application.

Clients müssen das Ende eines „Turns“ bestätigen, indem sie eine telemetry-Nachricht senden, kurz nachdem sie eine turn.end-Nachricht erhalten haben.Clients must acknowledge the end of a turn by sending a telemetry message soon after receiving a turn.end message. Clients sollten versuchen, turn.end so bald wie möglich zu bestätigen.Clients should attempt to acknowledge the turn.end as soon as possible. Wenn eine Clientanwendung das Ende eines „Turns“ nicht bestätigt, beendet der Spracherkennungsdienst die Verbindung unter Umständen mit einem Fehler.If a client application fails to acknowledge the turn end, Speech Service might terminate the connection with an error. Clients müssen nur eine telemetry-Nachricht pro Anforderung und Antwort senden, die jeweils über den Wert von X-RequestId identifiziert werden.Clients must send only one telemetry message for each request and response identified by the X-RequestId value.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath telemetry
X-TimestampX-Timestamp Zeitstempel der UTC-Uhrzeit des Clients im Format ISO 8601Client UTC clock time stamp in ISO 8601 format
Content-TypeContent-Type application/json
BodyBody Eine JSON-Struktur, die Clientinformationen zum „Turn“ enthält.A JSON structure that contains client information about the turn

Eine Definition des Schemas für den Text der telemetry-Nachricht finden Sie im Abschnitt Schema der Telemetriedaten.The schema for the body of the telemetry message is defined in the Telemetry schema section.

Telemetriedaten für unterbrochene VerbindungenTelemetry for interrupted connections

Wenn die Netzwerkverbindung während eines „Turns“ aus irgendeinem Grund fehlschlägt und der Client keine turn.end-Nachricht vom Dienst empfängt, sendet der Client eine telemetry-Nachricht.If the network connection fails for any reason during a turn and the client does not receive a turn.end message from the service, the client sends a telemetry message. In dieser Nachricht wird die fehlgeschlagene Anforderung für die nächste Verbindungsherstellung mit dem Dienst durch den Client beschrieben.This message describes the failed request the next time the client makes a connection to the service. Clients müssen nicht sofort versuchen, eine Verbindung herzustellen, um die telemetry-Nachricht zu senden.Clients do not have to immediately attempt a connection to send the telemetry message. Die Nachricht wird ggf. auf dem Client gepuffert und über eine zukünftige vom Benutzer angeforderte Verbindung gesendet.The message might be buffered on the client and sent over a future user-requested connection. Die telemetry-Nachricht für die fehlgeschlagene Anforderung muss den Wert von X-RequestId aus der fehlgeschlagenen Anforderung verwenden.The telemetry message for the failed request must use the X-RequestId value from the failed request. Dieser kann an den Dienst gesendet werden, sobald eine Verbindung hergestellt wurde, ohne auf das Senden oder Empfangen anderer Nachrichten zu warten.It might be sent to the service as soon as a connection is established, without waiting to send or receive for other messages.

Nachrichten vom DienstService-originated messages

In diesem Abschnitt werden die Nachrichten beschrieben, die vom Spracherkennungsdienst stammen und an den Client gesendet werden.This section describes the messages that originate in Speech Service and are sent to the client. Der Spracherkennungsdienst umfasst eine Registrierung mit Clientfunktionen und generiert die Nachrichten, die für die einzelnen Clients erforderlich sind. Es ist also so, dass nicht alle Clients alle hier beschriebenen Nachrichten erhalten.Speech Service maintains a registry of client capabilities and generates the messages required by each client, so not all clients receive all the messages that are described here. Zur Verbesserung der Übersichtlichkeit wird auf Nachrichten anhand des Werts des Path-Headers verwiesen.For brevity, messages are referenced by the value of the Path header. Auf eine WebSocket-Textnachricht mit dem Path-Wert speech.hypothesis wird beispielsweise als „speech.hypothesis“-Nachricht verwiesen.For example, we refer to a WebSocket text message with the Path value speech.hypothesis as a speech.hypothesis message.

speech.startDetected-NachrichtMessage speech.startDetected

Mit der speech.startDetected-Nachricht wird angegeben, dass der Spracherkennungsdienst Sprachdaten im Audiodatenstrom erkannt hat.The speech.startDetected message indicates that Speech Service detected speech in the audio stream.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath speech.startDetected
Content-TypeContent-Type application/json; charset=utf-8application/json; charset=utf-8
BodyBody Die JSON-Struktur mit Informationen zu den Bedingungen, die bei der Erkennung der Spracheingabe geherrscht haben.The JSON structure that contains information about the conditions when the start of speech was detected. Über das Feld Offset dieser Struktur wird der Versatz (in Einheiten von 100 Nanosekunden) angegeben, der zwischen der Erkennung der Sprachdaten im Audiodatenstrom und dem Beginn des Datenstroms besteht.The Offset field in this structure specifies the offset (in 100-nanosecond units) when speech was detected in the audio stream, relative to the start of the stream.

BeispielnachrichtSample message

Path: speech.startDetected
Content-Type: application/json; charset=utf-8
X-RequestId: 123e4567e89b12d3a456426655440000

{
  "Offset": 100000
}

speech.hypothesis-NachrichtMessage speech.hypothesis

Während der Spracherkennung generiert der Spracherkennungsdienst regelmäßig Hypothesen zu den vom Dienst erkannten Wörtern.During speech recognition, Speech Service periodically generates hypotheses about the words the service recognized. Der Spracherkennungsdienst sendet diese Hypothesen ca. alle 300 Millisekunden an den Client.Speech Service sends these hypotheses to the client approximately every 300 milliseconds. speech.hypothesis ist nur für die Verbesserung der Benutzerfreundlichkeit bei der Spracheingabe geeignet.The speech.hypothesis is suitable only for enhancing the user speech experience. Es darf keine Abhängigkeit vom Inhalt oder von der Genauigkeit des Texts in diesen Nachrichten bestehen.You must not take any dependency on the content or accuracy of the text in these messages.

Die speech.hypothesis-Nachricht gilt für die Clients, die über eine Funktion für das Textrendering verfügen und die für die sprechende Person nahezu in Echtzeit Feedback zur laufenden Erkennung bereitstellen sollen.The speech.hypothesis message is applicable to those clients that have some text rendering capability and want to provide near-real-time feedback of the in-progress recognition to the person who is speaking.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath speech.hypothesis
X-RequestIdX-RequestId UUID im Format „no-dash“UUID in "no-dash" format
Content-TypeContent-Type Anwendung/jsonapplication/json
BodyBody JSON-Struktur für die SprachhypotheseThe speech hypothesis JSON structure

BeispielnachrichtSample message

Path: speech.hypothesis
Content-Type: application/json; charset=utf-8
X-RequestId: 123e4567e89b12d3a456426655440000

{
  "Text": "this is a speech hypothesis",
  "Offset": 0,
  "Duration": 23600000
}

Mit dem Offset-Element wird der Versatz (in Einheiten von 100 Nanosekunden) angegeben, der zwischen der Erkennung des Ausdrucks und dem Beginn des Audiodatenstroms besteht.The Offset element specifies the offset (in 100-nanosecond units) when the phrase was recognized, relative to the start of the audio stream.

Mit dem Duration-Element wird die Dauer (in Einheiten von 100 Nanosekunden) für diese gesprochenen Wörter angegeben.The Duration element specifies the duration (in 100-nanosecond units) of this speech phrase.

Clients dürfen keine Annahmen zu Häufigkeit, Timing oder Text einer Sprachhypothese oder zur Konsistenz von Text in zwei beliebigen Sprachhypothesen treffen.Clients must not make any assumptions about the frequency, timing, or text contained in a speech hypothesis or the consistency of text in any two speech hypotheses. Die Hypothesen sind nur Momentaufnahmen im Transkriptionsprozess des Diensts.The hypotheses are just snapshots into the transcription process in the service. Sie stellen keine stabile Akkumulation in Bezug auf die Transkription dar.They do not represent a stable accumulation of transcription. Beispielsweise kann die erste Sprachhypothese im Englischen die Wörter „fine fun“ und die zweite Hypothese die Wörter „find funny“ enthalten.For example, a first speech hypothesis might contain the words "fine fun," and the second hypothesis might contain the words "find funny." Der Spracherkennungsdienst führt keine Nachbearbeitung (z.B. Großschreibung, Zeichensetzung) für den Text der Sprachhypothese durch.Speech Service doesn't perform any post-processing (for example, capitalization, punctuation) on the text in the speech hypothesis.

speech.phrase-NachrichtMessage speech.phrase

Wenn der Spracherkennungsdienst ermittelt, dass er über ausreichende Informationen zum Produzieren eines Erkennungsergebnisses verfügt, das sich nicht ändert, erstellt der Dienst eine speech.phrase-Nachricht.When Speech Service determines that it has enough information to produce a recognition result that won't change, the service produces a speech.phrase message. Der Spracherkennungsdienst produziert diese Ergebnisse, nachdem er erkannt hat, dass der Benutzer einen Satz oder einen Ausdruck beendet hat.Speech Service produces these results after it detects that the user has finished a sentence or phrase.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath speech.phrase
Content-TypeContent-Type Anwendung/jsonapplication/json
BodyBody JSON-Struktur des gesprochenen AusdrucksThe speech phrase JSON structure

Das JSON-Schema für gesprochene Ausdrücke enthält die folgenden Felder: RecognitionStatus, DisplayText, Offset und Duration.The speech phrase JSON schema includes the following fields: RecognitionStatus, DisplayText, Offset, and Duration. Weitere Informationen zu diesen Feldern finden Sie unter Transcription responses (Transkriptionsantworten).For more information about these fields, see Transcription responses.

BeispielnachrichtSample message

Path: speech.phrase
Content-Type: application/json; charset=utf-8
X-RequestId: 123e4567e89b12d3a456426655440000

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

speech.endDetected-NachrichtMessage speech.endDetected

Die speech.endDetected-Nachricht gibt an, dass die Clientanwendung das Streamen von Audiodaten an den Dienst beenden soll.The speech.endDetected message specifies that the client application should stop streaming audio to the service.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath speech.endDetected
BodyBody Die JSON-Struktur mit dem Versatz für die Erkennung des Endes der Spracheingabe.The JSON structure that contains the offset when the end of speech was detected. Der Versatz wird in Einheiten von 100 Nanosekunden ab dem Beginn der Audiodaten dargestellt, die für die Erkennung verwendet werden.The offset is represented in 100-nanosecond units offset from the start of audio that's used for recognition.
Content-TypeContent-Type application/json; charset=utf-8application/json; charset=utf-8

BeispielnachrichtSample message

Path: speech.endDetected
Content-Type: application/json; charset=utf-8
X-RequestId: 123e4567e89b12d3a456426655440000

{
  "Offset": 0
}

Mit dem Offset-Element wird der Versatz (in Einheiten von 100 Nanosekunden) angegeben, der zwischen der Erkennung des Ausdrucks und dem Beginn des Audiodatenstroms besteht.The Offset element specifies the offset (in 100-nanosecond units) when the phrase was recognized, relative to the start of the audio stream.

turn.start-NachrichtMessage turn.start

Mit turn.start wird der Beginn eines „Turns“ aus Sicht des Diensts signalisiert.The turn.start signals the start of a turn from the perspective of the service. Die turn.start-Nachricht ist immer die erste Antwortnachricht, die Sie für eine Anforderung empfangen.The turn.start message is always the first response message you receive for any request. Wenn Sie keine turn.start-Nachricht erhalten, sollten Sie annehmen, dass der Status der Dienstverbindung ungültig ist.If you don't receive a turn.start message, assume that the state of the service connection is invalid.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath turn.start
Content-TypeContent-Type application/json; charset=utf-8application/json; charset=utf-8
BodyBody JSON-StrukturJSON structure

BeispielnachrichtSample message

Path: turn.start
Content-Type: application/json; charset=utf-8
X-RequestId: 123e4567e89b12d3a456426655440000

{
  "context": {
    "serviceTag": "7B33613B91714B32817815DC89633AFA"
  }
}

Der Text der turn.start-Nachricht ist eine JSON-Struktur, die Kontext für den Beginn des „Turns“ enthält.The body of the turn.start message is a JSON structure that contains context for the start of the turn. Das context-Element enthält eine serviceTag-Eigenschaft.The context element contains a serviceTag property. Mit dieser Eigenschaft wird ein Tagwert angegeben, der dem „Turn“ vom Dienst zugeordnet wurde.This property specifies a tag value that the service has associated with the turn. Dieser Wert kann von Microsoft genutzt werden, falls Sie bei der Problembehandlung für Fehler in Ihrer Anwendung Hilfe benötigen.This value can be used by Microsoft if you need help troubleshooting failures in your application.

turn.end-NachrichtMessage turn.end

Mit turn.end wird das Ende eines „Turns“ aus Sicht des Diensts signalisiert.The turn.end signals the end of a turn from the perspective of the service. Die turn.end-Nachricht ist immer die letzte Antwortnachricht, die Sie für eine Anforderung empfangen.The turn.end message is always the last response message you receive for any request. Clients können den Empfang dieser Nachricht als Signal für Bereinigungsaktivitäten und den Übergang in einen Leerlaufzustand nutzen.Clients can use the receipt of this message as a signal for cleanup activities and transitioning to an idle state. Wenn Sie keine turn.end-Nachricht erhalten, sollten Sie annehmen, dass der Status der Dienstverbindung ungültig ist.If you don't receive a turn.end message, assume that the state of the service connection is invalid. Schließen Sie in diesem Fall die vorhandene Verbindung mit dem Dienst, und stellen Sie eine neue Verbindung her.In those cases, close the existing connection to the service and reconnect.

FeldField BESCHREIBUNGDescription
Codierung von WebSocket-NachrichtenWebSocket message encoding TextText
PathPath turn.end
BodyBody KeineNone

BeispielnachrichtSample message

Path: turn.end
X-RequestId: 123e4567e89b12d3a456426655440000

Schema der TelemetriedatenTelemetry schema

Der Text der telemetry-Nachricht ist eine JSON-Struktur, die Clientinformationen zu einem „Turn“ oder einer versuchten Verbindungsherstellung enthält.The body of the telemetry message is a JSON structure that contains client information about a turn or an attempted connection. Die Struktur besteht aus Clientzeitstempeln, mit denen aufgezeichnet wird, wann Clientereignisse eintreten.The structure is made up of client time stamps that record when client events occur. Jeder Zeitstempel muss das ISO 8601-Format haben, wie im Abschnitt „X-Timestamp-Header“ beschrieben.Each time stamp must be in ISO 8601 format as described in the section titled "X-Timestamp header." telemetry-Nachrichten, für die nicht alle erforderlichen Felder in der JSON-Struktur angegeben werden oder die nicht das richtige Zeitstempelformat nutzen, können dazu führen, dass der Dienst die Verbindung mit dem Client beendet.Telemetry messages that do not specify all the required fields in the JSON structure or that do not use the correct time stamp format might cause the service to terminate the connection to the client. Clients müssen gültige Werte für alle erforderlichen Felder angeben.Clients must supply valid values for all required fields. Clients sollten Werte für optionale Felder angeben, sofern dies erforderlich ist.Clients should supply values for optional fields whenever appropriate. Die Werte in den Beispielen dieses Abschnitts dienen nur zu Illustrationszwecken.The values shown in samples in this section are for illustration only.

Das Schema für Telemetriedaten ist in die folgenden Bestandteile unterteilt: Zeitstempel der empfangenen Nachricht und Metriken.Telemetry schema is divided into the following parts: received message time stamps and metrics. Das Format und die Nutzung der einzelnen Teile ist in den folgenden Abschnitten angegeben.The format and usage of each part is specified in the following sections.

Zeitstempel der empfangenen NachrichtReceived message time stamps

Clients müssen Empfangszeitpunkt-Werte für alle Nachrichten enthalten, die sie erhalten, nachdem die Verbindung mit dem Dienst erfolgreich hergestellt wurde.Clients must include time-of-receipt values for all messages that they receive after successfully connecting to the service. Mit diesen Werten muss der Zeitpunkt aufgezeichnet werden, zu dem der Client die einzelnen Nachrichten über das Netzwerk empfangen hat.These values must record the time when the client received each message from the network. Mit dem Wert sollten keine anderen Zeitpunkte aufgezeichnet werden.The value should not record any other time. Beispielsweise sollte der Client nicht den Zeitpunkt aufzeichnen, zu dem er für die Nachricht aktiv geworden ist.For example, the client should not record the time when it acted on the message. Die Zeitstempel von empfangenen Nachrichten werden in einem Array mit Name:Wert-Paaren angegeben.The received message time stamps are specified in an array of name:value pairs. Mit dem Namen des Paars wird der Path-Wert der Nachricht angegeben.The name of the pair specifies the Path value of the message. Der Wert des Paars gibt den Zeitpunkt an, zu dem der Client die Nachricht empfangen hat.The value of the pair specifies the client time when the message was received. Falls mehr als eine Nachricht mit dem angegebenen Namen empfangen wurde, ist der Wert des Paars ein Array mit Zeitstempeln, die darauf hinweisen, wann die Nachrichten empfangen wurden.Or, if more than one message of the specified name was received, the value of the pair is an array of time stamps that indicates when those messages were received.

  "ReceivedMessages": [
    { "speech.hypothesis": [ "2016-08-16T15:03:48.172Z", "2016-08-16T15:03:48.331Z", "2016-08-16T15:03:48.881Z" ] },
    { "speech.endDetected": "2016-08-16T15:03:49.721Z" },
    { "speech.phrase": "2016-08-16T15:03:50.001Z" },
    { "turn.end": "2016-08-16T15:03:51.021Z" }
  ]

Clients müssen den Empfang aller Nachrichten bestätigen, die vom Dienst gesendet werden, indem Zeitstempel für diese Nachrichten in den JSON-Text eingefügt werden.Clients must acknowledge the receipt of all messages sent by the service by including time stamps for those messages in the JSON body. Falls ein Client den Empfang einer Nachricht nicht bestätigt, beendet der Dienst ggf. die Verbindung.If a client fails to acknowledge the receipt of a message, the service might terminate the connection.

metricsMetrics

Clients müssen Informationen zu Ereignissen enthalten, die während der Lebensdauer einer Anforderung aufgetreten sind.Clients must include information about events that occurred during the lifetime of a request. Die folgenden Metriken werden unterstützt: Connection, Microphone und ListeningTrigger.The following metrics are supported: Connection, Microphone, and ListeningTrigger.

Connection-MetrikMetric Connection

Mit der Connection-Metrik werden Details zu Verbindungsversuchen des Clients angegeben.The Connection metric specifies details about connection attempts by the client. Die Metrik muss Zeitstempel für den Beginn und das Ende der WebSocket-Verbindung enthalten.The metric must include time stamps of when the WebSocket connection was started and finished. Die Connection-Metrik ist nur für den ersten „Turn“ einer Verbindung erforderlich.The Connection metric is required only for the first turn of a connection. Nachfolgende „Turns“ müssen diese Informationen nicht enthalten.Subsequent turns are not required to include this information. Wenn ein Client mehrere Verbindungsversuche unternimmt, bevor eine Verbindung hergestellt wird, sollten Informationen zu allen Verbindungsversuchen eingefügt werden.If a client makes multiple connection attempts before a connection is established, information about all the connection attempts should be included. Weitere Informationen finden Sie unter Telemetriedaten für Verbindungsfehler.For more information, see Connection failure telemetry.

FeldField BESCHREIBUNGDescription VerwendungUsage
NameName Connection ErforderlichRequired
IdId Der Wert des Verbindungsbezeichners, der im X-ConnectionId-Header für diese Verbindungsanforderung verwendet wurde.The connection identifier value that was used in the X-ConnectionId header for this connection request ErforderlichRequired
StartStart Der Zeitpunkt, zu dem der Client die Verbindungsanforderung gesendet hat.The time when the client sent the connection request ErforderlichRequired
EndEnd Der Zeitpunkt, zu dem der Client die Benachrichtigung erhalten hat, dass die Verbindung erfolgreich hergestellt wurde oder bei einem Fehler abgelehnt bzw. verweigert wurde oder fehlgeschlagen ist.The time when the client received notification that the connection was established successfully or, in error cases, rejected, refused, or failed ErforderlichRequired
ErrorError Eine Beschreibung des Fehlers, der aufgetreten ist (falls zutreffend).A description of the error that occurred, if any. Wenn die Verbindung erfolgreich hergestellt wurde, sollten Clients dieses Feld weglassen.If the connection was successful, clients should omit this field. Dieses Feld darf maximal 50 Zeichen lang sein.The maximum length of this field is 50 characters. Erforderlich für Fehlerfälle, andernfalls weggelassenRequired for error cases, omitted otherwise

Die Fehlerbeschreibung sollte maximal 50 Zeichen lang sein und idealerweise einem der Werte entsprechen, die in der folgenden Tabelle aufgeführt sind.The error description should be at most 50 characters and ideally should be one of the values listed in the following table. Wenn die Fehlerbedingung nicht mit einem dieser Wert übereinstimmt, können Clients eine kurze Beschreibung der Fehlerbedingung nutzen, indem sie Binnenmajuskeln (Englisch: CamelCasing) ohne Leerzeichen nutzen.If the error condition doesn't match one of these values, clients can use a succinct description of the error condition by using CamelCasing without white space. Für das Senden einer telemetry-Nachricht ist eine Verbindung mit dem Dienst erforderlich, sodass nur vorübergehende oder temporäre Fehlerbedingungen in der telemetry-Nachricht gemeldet werden können.The ability to send a telemetry message requires a connection to the service, so only transient or temporary error conditions can be reported in the telemetry message. Fehlerbedingungen, die einen Client dauerhaft daran hindern, eine Verbindung mit dem Dienst herzustellen, verhindern für den Client das Senden von Nachrichten an den Dienst (einschließlich telemetry-Nachrichten).Error conditions that permanently block a client from establishing a connection to the service prevent the client from sending any message to the service, including telemetry messages.

ErrorError VerwendungUsage
DNSfailureDNSfailure Der Client konnte aufgrund eines DNS-Fehlers im Netzwerkstapel keine Verbindung mit dem Dienst herstellen.The client was unable to connect to the service because of a DNS failure in the network stack.
NoNetworkNoNetwork Der Client hat versucht, eine Verbindung herzustellen, aber vom Netzwerkstapel wurde gemeldet, dass kein physisches Netzwerk verfügbar war.The client attempted a connection, but the network stack reported that no physical network was available.
NoAuthorizationNoAuthorization Die Clientverbindung ist fehlgeschlagen, während versucht wurde, ein Autorisierungstoken für die Verbindung zu beziehen.The client connection failed while attempting to acquire an authorization token for the connection.
NoResourcesNoResources Eine lokale Ressource (z.B. der Arbeitsspeicher) des Clients war erschöpft, während versucht wurde, eine Verbindung herzustellen.The client ran out of some local resource (for example, memory) while trying to make a connection.
VerbotenForbidden Der Client konnte keine Verbindung mit dem Dienst herstellen, da der Dienst den HTTP-Statuscode 403 Forbidden für die WebSocket-Upgradeanforderung zurückgegeben hat.The client was unable to connect to the service because the service returned an HTTP 403 Forbidden status code on the WebSocket upgrade request.
Nicht autorisiertUnauthorized Der Client konnte keine Verbindung mit dem Dienst herstellen, da der Dienst den HTTP-Statuscode 401 Unauthorized für die WebSocket-Upgradeanforderung zurückgegeben hat.The client was unable to connect to the service because the service returned an HTTP 401 Unauthorized status code on the WebSocket upgrade request.
BadRequestBadRequest Der Client konnte keine Verbindung mit dem Dienst herstellen, da der Dienst den HTTP-Statuscode 400 Bad Request für die WebSocket-Upgradeanforderung zurückgegeben hat.The client was unable to connect to the service because the service returned an HTTP 400 Bad Request status code on the WebSocket upgrade request.
ServerUnavailableServerUnavailable Der Client konnte keine Verbindung mit dem Dienst herstellen, da der Dienst den HTTP-Statuscode 503 Server Unavailable für die WebSocket-Upgradeanforderung zurückgegeben hat.The client was unable to connect to the service because the service returned an HTTP 503 Server Unavailable status code on the WebSocket upgrade request.
ServerErrorServerError Der Client konnte keine Verbindung mit dem Dienst herstellen, da der Dienst den Statuscode HTTP 500 für interne Fehler für die WebSocket-Upgradeanforderung zurückgegeben hat.The client was unable to connect to the service because the service returned an HTTP 500 Internal Error status code on the WebSocket upgrade request.
TimeoutTimeout Für die Verbindungsanforderung des Clients ist eine Zeitüberschreitung aufgetreten, ohne dass eine Antwort vom Dienst erhalten wurde.The client's connection request timed out without a response from the service. Das Feld End enthält den Zeitpunkt, zu dem für den Client die Zeitüberschreitung aufgetreten ist und das Warten auf die Verbindung beendet wurde.The End field contains the time when the client timed out and stopped waiting for the connection.
ClientErrorClientError Der Client hat die Verbindung aufgrund eines internen Clientfehlers beendet.The client terminated the connection because of some internal client error.

Microphone-MetrikMetric Microphone

Die Microphone-Metrik ist für alle Sprach-„Turns“ erforderlich.The Microphone metric is required for all speech turns. Mit dieser Metrik wird der Zeitraum auf dem Client gemessen, in dem die Audioeingabe aktiv für eine Sprachanforderung verwendet wird.This metric measures the time on the client during which audio input is being actively used for a speech request.

Verwenden Sie die folgenden Beispiele als Richtlinien für die Aufzeichnung von Start-Zeitwerten für die Microphone-Metrik in Ihrer Clientanwendung:Use the following examples as guidelines for recording Start time values for the Microphone metric in your client application:

  • Für eine Clientanwendung ist es erforderlich, dass ein Benutzer eine physische Taste drücken muss, um die Mikrofonnutzung zu starten.A client application requires that a user must press a physical button to start the microphone. Nach dem Betätigen der Taste liest die Clientanwendung die Eingabe über das Mikrofon und sendet sie an den Spracherkennungsdienst.After the button press, the client application reads the input from the microphone and sends it to Speech Service. Mit dem Start-Wert für die Microphone-Metrik wird die Zeit nach der Betätigung der Taste aufgezeichnet, bis das Mikrofon initialisiert wurde und für die Eingabe bereit ist.The Start value for the Microphone metric records the time after the button push when the microphone is initialized and ready to provide input. Mit dem End-Wert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Clientanwendung das Streamen von Audiodaten an den Dienst beendet hat, nachdem sie die speech.endDetected-Nachricht vom Dienst erhalten hat.The End value for the Microphone metric records the time when the client application stopped streaming audio to the service after it received the speech.endDetected message from the service.

  • Eine Clientanwendung nutzt eine Schlüsselworterkennung („Keyword Spotter“), die „immer“ lauscht.A client application uses a keyword spotter that is "always" listening. Erst nachdem die Schlüsselworterkennung einen gesprochenen Triggerausdruck erkannt hat, erfasst die Clientanwendung die Eingabe vom Mikrofon und sendet sie an den Spracherkennungsdienst.Only after the keyword spotter detects a spoken trigger phrase does the client application collect the input from the microphone and send it to Speech Service. Der Start-Wert für die Microphone-Metrik zeichnet den Zeitpunkt auf, zu dem der Client von der Schlüsselworterkennung aufgefordert wurde, mit der Verwendung der Eingabe über das Mikrofon zu beginnen.The Start value for the Microphone metric records the time when the keyword spotter notified the client to start using input from the microphone. Mit dem End-Wert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Clientanwendung das Streamen von Audiodaten an den Dienst beendet hat, nachdem sie die speech.endDetected-Nachricht vom Dienst erhalten hat.The End value for the Microphone metric records the time when the client application stopped streaming audio to the service after it received the speech.endDetected message from the service.

  • Eine Clientanwendung hat Zugriff auf einen konstanten Audiodatenstrom und führt die Erkennung von Schweigen bzw. Sprache für diesen Audiodatenstrom in einem Spracherkennungsmodul durch.A client application has access to a constant audio stream and performs silence/speech detection on that audio stream in a speech detection module. Mit dem Start-Wert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem das Spracherkennungsmodul den Client aufgefordert hat, mit der Verwendung der Eingabe des Audiodatenstroms zu beginnen.The Start value for the Microphone metric records the time when the speech detection module notified the client to start using input from the audio stream. Mit dem End-Wert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Clientanwendung das Streamen von Audiodaten an den Dienst beendet hat, nachdem sie die speech.endDetected-Nachricht vom Dienst erhalten hat.The End value for the Microphone metric records the time when the client application stopped streaming audio to the service after it received the speech.endDetected message from the service.

  • Eine Clientanwendung verarbeitet den zweiten „Turn“ einer Anforderung mit mehreren „Turns“ und wird per Dienstantwortnachricht aufgefordert, das Mikrofon einzuschalten, um Eingabedaten für den zweiten „Turn“ zu sammeln.A client application is processing the second turn of a multi-turn request and is informed by a service response message to turn on the microphone to gather input for the second turn. Mit dem Start-Wert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Clientanwendung das Mikrofon aktiviert und mit der Verwendung der Eingabedaten von dieser Audioquelle beginnt.The Start value for the Microphone metric records the time when the client application enables the microphone and starts using input from that audio source. Mit dem End-Wert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Clientanwendung das Streamen von Audiodaten an den Dienst beendet hat, nachdem sie die speech.endDetected-Nachricht vom Dienst erhalten hat.The End value for the Microphone metric records the time when the client application stopped streaming audio to the service after it received the speech.endDetected message from the service.

Mit dem End-Zeitwert für die Microphone-Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Clientanwendung das Streamen der Audioeingabe beendet hat.The End time value for the Microphone metric records the time when the client application stopped streaming audio input. In den meisten Fällen tritt dieses Ereignis kurze Zeit nach dem Empfang der speech.endDetected-Nachricht durch den Client vom Dienst auf.In most situations, this event occurs shortly after the client received the speech.endDetected message from the service. Für Clientanwendungen kann ggf. überprüft werden, dass die Konformität mit dem Protokoll gewährleistet ist. Hierzu wird sichergestellt, dass der End-Zeitwert für die Microphone-Metrik nach dem Empfangszeitwert für die speech.endDetected-Nachricht liegt.Client applications might verify that they're properly conforming to the protocol by ensuring that the End time value for the Microphone metric occurs later than the receipt time value for the speech.endDetected message. Und da es zwischen dem Ende eines „Turns“ und dem Start eines anderen „Turns“ normalerweise zu einer Verzögerung kommt, können Clients auch die Konformität des Protokolls überprüfen. Hierzu wird sichergestellt, dass der Start-Zeitpunkt der Microphone-Metrik für alle nachfolgenden „Turns“ richtig den Zeitpunkt aufzeichnet, zu dem der Client mit der Verwendung des Mikrofons zum Streamen der Audioeingabe an den Dienst begonnen hat.And, because there is usually a delay between the end of one turn and the start of another turn, clients might verify protocol conformance by ensuring that the Start time of the Microphone metric for any subsequent turn correctly records the time when the client started using the microphone to stream audio input to the service.

FeldField BESCHREIBUNGDescription VerwendungUsage
NameName MikrofonMicrophone ErforderlichRequired
StartStart Der Zeitpunkt, zu dem der Client mit der Verwendung der Audioeingabe vom Mikrofon oder anderer Audiodatenströme begonnen hat oder einen Trigger von der Schlüsselworterkennung erhalten hat.The time when the client started using audio input from the microphone or other audio stream or received a trigger from the keyword spotter ErforderlichRequired
EndEnd Der Zeitpunkt, zu dem der Client die Verwendung des Mikrofons bzw. des Audiodatenstroms beendet hat.The time when the client stopped using the microphone or audio stream ErforderlichRequired
ErrorError Eine Beschreibung des Fehlers, der aufgetreten ist (falls zutreffend).A description of the error that occurred, if any. Wenn die Mikrofonvorgänge erfolgreich waren, sollten Clients dieses Feld weglassen.If the microphone operations were successful, clients should omit this field. Dieses Feld darf maximal 50 Zeichen lang sein.The maximum length of this field is 50 characters. Erforderlich für Fehlerfälle, andernfalls weggelassenRequired for error cases, omitted otherwise

ListeningTrigger-MetrikMetric ListeningTrigger

Mit der ListeningTrigger-Metrik wird der Zeitpunkt gemessen, zu dem der Benutzer die Aktion ausführt, mit der die Spracheingabe initiiert wird.The ListeningTrigger metric measures the time when the user executes the action that initiates speech input. Die ListeningTrigger-Metrik ist optional, aber für Clients, die diese Metrik bereitstellen können, wird die Verwendung empfohlen.The ListeningTrigger metric is optional, but clients that can provide this metric are encouraged to do so.

Verwenden Sie die folgenden Beispiele als Richtlinien für die Aufzeichnung von Start- und End-Zeitwerten für die ListeningTrigger-Metrik in Ihrer Clientanwendung.Use the following examples as guidelines for recording Start and End time values for the ListeningTrigger metric in your client application.

  • Für eine Clientanwendung ist es erforderlich, dass ein Benutzer eine physische Taste drücken muss, um die Mikrofonnutzung zu starten.A client application requires that a user must press a physical button to start the microphone. Mit dem Start-Wert für diese Metrik wird der Zeitpunkt der Tastenbetätigung aufgezeichnet.The Start value for this metric records the time of the button push. Mit dem End-Wert wird der Zeitpunkt aufgezeichnet, zu dem die Betätigung der Taste beendet wurde.The End value records the time when the button push finishes.

  • Eine Clientanwendung nutzt eine Schlüsselworterkennung („Keyword Spotter“), die „immer“ lauscht.A client application uses a keyword spotter that is "always" listening. Nachdem die Schlüsselworterkennung einen gesprochenen Triggerausdruck erkannt hat, liest die Clientanwendung die Eingabe über das Mikrofon und sendet sie an den Spracherkennungsdienst.After the keyword spotter detects a spoken trigger phrase, the client application reads the input from the microphone and sends it to Speech Service. Mit dem Start-Wert für diese Metrik wird der Zeitpunkt aufgezeichnet, zu dem die Schlüsselworterkennung Audiodaten empfangen hat, die dann als Triggerausdruck erkannt wurden.The Start value for this metric records the time when the keyword spotter received audio that was then detected as the trigger phrase. Mit dem End-Wert wird der Zeitpunkt aufgezeichnet, zu dem das letzte Wort des Triggerausdrucks vom Benutzer gesprochen wurde.The End value records the time when the last word of the trigger phrase was spoken by the user.

  • Eine Clientanwendung hat Zugriff auf einen konstanten Audiodatenstrom und führt die Erkennung von Schweigen bzw. Sprache für diesen Audiodatenstrom in einem Spracherkennungsmodul durch.A client application has access to a constant audio stream and performs silence/speech detection on that audio stream in a speech detection module. Mit dem Start-Wert für diese Metrik wird der Zeitpunkt aufgezeichnet, zu dem das Spracherkennungsmodul Audiodaten empfangen hat, die dann als Sprache erkannt wurden.The Start value for this metric records the time that the speech detection module received audio that was then detected as speech. Mit dem End-Wert wird der Zeitpunkt aufgezeichnet, zu dem das Spracherkennungsmodul Sprache erkannt hat.The End value records the time when the speech detection module detected speech.

  • Eine Clientanwendung verarbeitet den zweiten „Turn“ einer Anforderung mit mehreren „Turns“ und wird per Dienstantwortnachricht aufgefordert, das Mikrofon einzuschalten, um Eingabedaten für den zweiten „Turn“ zu sammeln.A client application is processing the second turn of a multi-turn request and is informed by a service response message to turn on the microphone to gather input for the second turn. Die Clientanwendung sollte keine ListeningTrigger-Metrik für diesen „Turn“ enthalten.The client application should not include a ListeningTrigger metric for this turn.

FeldField BESCHREIBUNGDescription VerwendungUsage
NameName ListeningTriggerListeningTrigger OptionalOptional
StartStart Der Zeitpunkt, zu dem der Lauschtrigger für den Client gestartet wurde.The time when the client listening trigger started ErforderlichRequired
EndEnd Der Zeitpunkt, zu dem der Lauschtrigger für den Client beendet wurde.The time when the client listening trigger finished ErforderlichRequired
ErrorError Eine Beschreibung des Fehlers, der aufgetreten ist (falls zutreffend).A description of the error that occurred, if any. Wenn dieser Triggervorgang erfolgreich war, sollten Clients dieses Feld weglassen.If the trigger operation was successful, clients should omit this field. Dieses Feld darf maximal 50 Zeichen lang sein.The maximum length of this field is 50 characters. Erforderlich für Fehlerfälle, andernfalls weggelassenRequired for error cases, omitted otherwise

BeispielnachrichtSample message

Das folgende Beispiel enthält eine Telemetrienachricht mit den Teilen „ReceivedMessages“ und „Metrics“:The following sample shows a telemetry message with both ReceivedMessages and Metrics parts:

Path: telemetry
Content-Type: application/json; charset=utf-8
X-RequestId: 123e4567e89b12d3a456426655440000
X-Timestamp: 2016-08-16T15:03:54.183Z

{
  "ReceivedMessages": [
    { "speech.hypothesis": [ "2016-08-16T15:03:48.171Z", "2016-08-16T15:03:48.331Z", "2016-08-16T15:03:48.881Z" ] },
    { "speech.endDetected": "2016-08-16T15:03:49.721Z" },
    { "speech.phrase": "2016-08-16T15:03:50.001Z" },
    { "turn.end": "2016-08-16T15:03:51.021Z" }
  ],
  "Metrics": [
    {
      "Name": "Connection",
      "Id": "A140CAF92F71469FA41C72C7B5849253",
      "Start": "2016-08-16T15:03:47.921Z",
      "End": "2016-08-16T15:03:48.000Z",
    },
    {
      "Name": "ListeningTrigger",
      "Start": "2016-08-16T15:03:48.776Z",
      "End": "2016-08-16T15:03:48.777Z",
    },
    {
      "Name": "Microphone",
      "Start": "2016-08-16T15:03:47.921Z",
      "End": "2016-08-16T15:03:51.921Z",
    },
  ],
}

FehlerbehandlungError handling

In diesem Abschnitt werden die Arten von Fehlermeldungen und -bedingungen beschrieben, die von Ihrer Anwendung verarbeitet werden müssen.This section describes the kinds of error messages and conditions that your application needs to handle.

HTTP-StatuscodesHTTP status codes

Während der WebSocket-Upgradeanforderung kann der Spracherkennungsdienst HTTP-Standardstatuscodes zurückgeben, z.B. 400 Bad Request usw. Ihre Anwendung muss diese Fehlerbedingungen richtig verarbeiten.During the WebSocket upgrade request, Speech Service might return any of the standard HTTP status codes, such as 400 Bad Request, etc. Your application must correctly handle these error conditions.

AutorisierungsfehlerAuthorization errors

Wenn die fehlerhafte Autorisierung während des WebSocket-Upgrades bereitgestellt wird, gibt der Spracherkennungsdienst den HTTP-Statuscode 403 Forbidden zurück.If incorrect authorization is provided during the WebSocket upgrade, Speech Service returns an HTTP 403 Forbidden status code. Beispiele für die Bedingungen, die diesen Fehlercode auslösen können, sind:Among the conditions that can trigger this error code are:

  • Fehlender Authorization-HeaderMissing Authorization header

  • Ungültiges AutorisierungstokenInvalid authorization token

  • Abgelaufenes AutorisierungstokenExpired authorization token

Die Fehlermeldung 403 Forbidden weist nicht auf ein Problem mit dem Spracherkennungsdienst hin.The 403 Forbidden error message doesn't indicate a problem with Speech Service. Diese Fehlermeldung steht für ein Problem mit der Clientanwendung.This error message indicates a problem with the client application.

ProtokollverletzungsfehlerProtocol violation errors

Wenn der Spracherkennungsdienst Protokollverletzungen eines Clients erkennt, beendet der Dienst die WebSocket-Verbindung, nachdem ein Statuscode und ein Grund für die Beendigung zurückgegeben wurde.If Speech Service detects any protocol violations from a client, the service terminates the WebSocket connection after returning a status code and reason for the termination. Clientanwendungen können diese Informationen nutzen, um die Problembehandlung durchzuführen und Verletzungen zu beheben.Client applications can use this information to troubleshoot and fix the violations.

Fehlerhaftes NachrichtenformatIncorrect message format

Wenn ein Client eine Textnachricht oder binäre Nachricht an den Dienst sendet, die nicht im richtigen Format gemäß dieser Spezifikation codiert ist, schließt der Dienst die Verbindung mit dem Statuscode 1007 Invalid Payload Data.If a client sends a text or binary message to the service that is not encoded in the correct format given in this specification, the service closes the connection with a 1007 Invalid Payload Data status code.

Der Dienst gibt diesen Statuscode aus verschiedenen Gründen zurück. Dies wird anhand der folgenden Beispiele veranschaulicht:The service returns this status code for a variety of reasons, as shown in the following examples:

  • „Incorrect message format."Incorrect message format. Binary message has invalid header size prefix.“ (Fehlerhaftes Nachrichtenformat. Die binäre Nachricht enthält ein ungültiges Präfix für die Headergröße.)Binary message has invalid header size prefix." Der Client hat eine binäre Nachricht mit einem ungültigen Präfix für die Headergröße gesendet.The client sent a binary message that has an invalid header size prefix.

  • „Incorrect message format."Incorrect message format. Binary message has invalid header size." (Fehlerhaftes Nachrichtenformat. Die binäre Nachricht enthält einen Header mit ungültiger Größe.)Binary message has invalid header size." Der Client hat eine binäre Nachricht gesendet, in der eine ungültige Headergröße enthalten war.The client sent a binary message that specified an invalid header size.

  • „Incorrect message format."Incorrect message format. Binary message headers decoding into UTF-8 failed.“ (Fehlerhaftes Nachrichtenformat. Fehler beim Decodieren von Headern binärer Nachrichten in UTF-8.)Binary message headers decoding into UTF-8 failed." Der Client hat eine binäre Nachricht gesendet, die Header mit einer fehlerhaften Codierung in UTF-8 enthält.The client sent a binary message that contains headers that were not correctly encoded in UTF-8.

  • „Incorrect message format."Incorrect message format. Text message contains no data.“ (Fehlerhaftes Nachrichtenformat. Textnachricht enthält keine Daten.)Text message contains no data." Der Client hat eine Textnachricht ohne Textdaten gesendet.The client sent a text message that contains no body data.

  • „Incorrect message format."Incorrect message format. Text message decoding into UTF-8 failed.“ (Fehlerhaftes Nachrichtenformat. Fehler beim Decodieren der Textnachricht in UTF-8.)Text message decoding into UTF-8 failed." Der Client hat eine Textnachricht gesendet, die nicht richtig für UTF-8 codiert war.The client sent a text message that was not correctly encoded in UTF-8.

  • „Incorrect message format."Incorrect message format. Text message contains no header separator.“ (Fehlerhaftes Nachrichtenformat. Die Textnachricht enthält kein Headertrennzeichen.)Text message contains no header separator." Der Client hat eine Textnachricht gesendet, die kein Headertrennzeichen oder ein falsches Headertrennzeichen enthalten hat.The client sent a text message that did not contain a header separator or used the wrong header separator.

Fehlende oder leere HeaderMissing or empty headers

Wenn ein Client eine Nachricht sendet, die nicht über die erforderlichen Header X-RequestId oder Path verfügt, schließt der Dienst die Verbindung mit dem Statuscode 1002 Protocol Error.If a client sends a message that doesn't have the required headers X-RequestId or Path, the service closes the connection with a 1002 Protocol Error status code. Die Meldung lautet „Missing/Empty header.The message is "Missing/Empty header. {Header name}.“ (Fehlender/leerer Header. {Headername}.){Header name}."

RequestId-WerteRequestId values

Wenn ein Client eine Nachricht sendet, für die ein X-RequestId-Header mit einem fehlerhaften Format angegeben wurde, schließt der Dienst die Verbindung und gibt den Status 1002 Protocol Error zurück.If a client sends a message that specifies an X-RequestId header with an incorrect format, the service closes the connection and returns a 1002 Protocol Error status. Die Meldung lautet „Invalid request.The message is "Invalid request. X-RequestId header value was not specified in no-dash UUID format.“ (Ungültige Anforderung. X-RequestId-Headerwert wurde nicht im UUID-Format „no-dash“ angegeben.)X-RequestId header value was not specified in no-dash UUID format."

AudiocodierungsfehlerAudio encoding errors

Wenn ein Client einen Audioblock sendet, mit dem ein „Turn“ initiiert wird, und das Audioformat oder die Codierung nicht mit der erforderlichen Spezifikation konform ist, schließt der Dienst die Verbindung und gibt den Statuscode 1007 Invalid Payload Data zurück.If a client sends an audio chunk that initiates a turn and the audio format or encoding doesn't conform to the required specification, the service closes the connection and returns a 1007 Invalid Payload Data status code. In der Meldung ist die Quelle für den Formatcodierungsfehler angegeben.The message indicates the format encoding error source.

Wiederverwendung der RequestIdRequestId reuse

Wenn ein Client nach Abschluss eines „Turns“ eine Nachricht sendet, in der der Anforderungsbezeichner dieses „Turns“ wiederverwendet wird, schließt der Dienst die Verbindung und gibt den Statuscode 1002 Protocol Error zurück.After a turn is finished, if a client sends a message that reuses the request identifier from that turn, the service closes the connection and returns a 1002 Protocol Error status code. Die Meldung lautet „Invalid request.The message is "Invalid request. Reuse of request identifiers is not allowed.“ (Ungültige Anforderung. Die Wiederverwendung von Anforderungsbezeichnern ist nicht zulässig.)Reuse of request identifiers is not allowed."

Telemetriedaten für VerbindungsfehlerConnection failure telemetry

Zur Sicherstellung der bestmöglichen Benutzerfreundlichkeit müssen Clients den Spracherkennungsdienst über die Zeitstempel für wichtige Prüfpunkte innerhalb einer Verbindung informieren, indem sie die telemetry-Nachricht verwenden.To ensure the best possible user experience, clients must inform Speech Service of the time stamps for important checkpoints within a connection by using the telemetry message. Es ist genauso wichtig, dass Clients den Dienst über Verbindungen informieren, bei denen beim Versuch, die Verbindung herzustellen, ein Fehler aufgetreten ist.It's equally important that clients inform the service of connections that were attempted but failed.

Für jeden nicht erfolgreichen Verbindungsversuch erstellen Clients eine telemetry-Nachricht mit einem eindeutigen X-RequestId-Headerwert.For each connection attempt that failed, clients create a telemetry message with a unique X-RequestId header value. Da der Client keine Verbindung herstellen konnte, kann das Feld ReceivedMessages im JSON-Text weggelassen werden.Because the client was unable to establish a connection, the ReceivedMessages field in the JSON body can be omitted. Nur der Connection-Eintrag im Feld Metrics wird verwendet.Only the Connection entry in the Metrics field is included. Dieser Eintrag enthält die Zeitstempel für Start und Ende sowie die Fehlerbedingung, die erkannt wurde.This entry includes the start and end time stamps as well as the error condition that was encountered.

Wiederholungsversuche zum Herstellen einer Verbindung in der TelemetrieConnection retries in telemetry

Clients sollten Wiederholungsversuche von mehreren Verbindungsversuchen anhand des Ereignisses unterscheiden, mit dem der Verbindungsversuch ausgelöst wird.Clients should distinguish retries from multiple connection attempts by the event that triggers the connection attempt. Verbindungsversuche, die programmgesteuert ohne Benutzereingabe durchgeführt werden, sind Wiederholungsversuche.Connection attempts that are carried out programmatically without any user input are retries. Mehrere Verbindungsversuche erfolgen als Reaktion auf die Benutzereingabe.Multiple connection attempts that are carried out in response to user input are multiple connection attempts. Clients ordnen jedem vom Benutzer ausgelösten Verbindungsversuch eine eindeutige X-RequestId- und telemetry-Nachricht zu.Clients give each user-triggered connection attempt a unique X-RequestId and telemetry message. X-RequestId wird von Clients für programmgesteuerte Wiederholungen wiederverwendet.Clients reuse the X-RequestId for programmatic retries. Wenn für einen einzelnen Verbindungsversuch mehrere Wiederholungsversuche durchgeführt wurden, wird jeder Versuch als Connection-Eintrag in die telemetry-Nachricht eingefügt.If multiple retries were made for a single connection attempt, each retry attempt is included as a Connection entry in the telemetry message.

Angenommen, ein Benutzer spricht das auslösende Schlüsselwort aus, um eine Verbindung zu starten, und der erste Verbindungsversuch ist aufgrund von DNS-Fehlern nicht erfolgreich.For example, suppose a user speaks the keyword trigger to start a connection and the first connection attempt fails because of DNS errors. Ein zweiter Versuch, der programmgesteuert vom Client unternommen wird, ist erfolgreich.However, a second attempt that is made programmatically by the client succeeds. Da der Client den Verbindungsversuch wiederholt hat, ohne dass eine zusätzliche Eingabe durch den Benutzer erforderlich war, nutzt der Client eine einzelne telemetry-Nachricht mit mehreren Connection-Einträgen, um die Verbindung zu beschreiben.Because the client retried the connection without requiring additional input from the user, the client uses a single telemetry message with multiple Connection entries to describe the connection.

Ein weiteres Beispiel: Ein Benutzer spricht das auslösende Schlüsselwort aus, um eine Verbindung zu starten, und dieser Verbindungsversuch schlägt nach drei Wiederholungen fehl.As another example, suppose a user speaks the keyword trigger to start a connection and this connection attempt fails after three retries. Der Client gibt auf, beendet die Versuche zum Herstellen einer Verbindung mit dem Dienst und informiert den Benutzer darüber, dass ein Fehler aufgetreten ist.The client then gives up, stops attempting to connect to the service, and informs the user that something went wrong. Der Benutzer spricht dann erneut das auslösende Schlüsselwort aus.The user then speaks the keyword trigger again. Jetzt gehen wir davon aus, dass der Client die Verbindung mit dem Dienst herstellt.This time, suppose the client connects to the service. Nach der Verbindungsherstellung sendet der Client sofort eine telemetry-Nachricht an den Dienst, die die drei Connection-Einträge zum Beschreiben der Verbindungsfehler enthält.After connecting, the client immediately sends a telemetry message to the service that contains three Connection entries that describe the connection failures. Nach Erhalt der turn.end-Nachricht sendet der Client eine weitere telemetry-Nachricht, in der die erfolgreiche Verbindungsherstellung beschrieben ist.After receiving the turn.end message, the client sends another telemetry message that describes the successful connection.

Referenz zu FehlermeldungenError message reference

HTTP-StatuscodesHTTP status codes

HTTP-StatuscodeHTTP status code BESCHREIBUNGDescription ProblembehandlungTroubleshooting
400 – Ungültige Anforderung400 Bad Request Der Client hat eine fehlerhafte WebSocket-Verbindungsanforderung gesendet.The client sent a WebSocket connection request that was incorrect. Überprüfen Sie, ob alle erforderlichen Parameter und HTTP-Header angegeben wurden und die Werte korrekt sind.Check that you supplied all the required parameters and HTTP headers and that the values are correct.
401 – Nicht autorisiert401 Unauthorized Der Client hat die erforderlichen Informationen für die Autorisierung nicht eingefügt.The client did not include the required authorization information. Überprüfen Sie, ob Sie für die WebSocket-Verbindung den Authorization-Header senden.Check that you're sending the Authorization header in the WebSocket connection.
403 Verboten403 Forbidden Der Client hat Informationen zur Autorisierung gesendet, aber diese waren ungültig.The client sent authorization information, but it was invalid. Stellen Sie sicher, dass Sie im Authorization-Header keinen abgelaufenen oder ungültigen Wert senden.Check that you're not sending an expired or invalid value in the Authorization header.
404 – Nicht gefunden404 Not Found Der Client hat versucht, auf einen nicht unterstützten URL-Pfad zuzugreifen.The client attempted to access a URL path that is not supported. Überprüfen Sie, ob Sie die richtige URL für die WebSocket-Verbindung verwenden.Check that you're using the correct URL for the WebSocket connection.
500 Serverfehler500 Server Error Der Dienst hat einen internen Fehler erkannt und konnte die Anforderung nicht erfüllen.The service encountered an internal error and could not satisfy the request. In den meisten Fällen ist dies ein vorübergehender Fehler.In most cases, this error is transient. Wiederholen Sie die Anforderung.Retry the request.
503 Dienst nicht verfügbar503 Service Unavailable Der Dienst konnte die Anforderung nicht verarbeiten.The service was unavailable to handle the request. In den meisten Fällen ist dies ein vorübergehender Fehler.In most cases, this error is transient. Wiederholen Sie die Anforderung.Retry the request.

WebSocket-FehlercodesWebSocket error codes

WebSocketsStatus-CodeWebSocketsStatus code BESCHREIBUNGDescription ProblembehandlungTroubleshooting
1000 Normales Schließen1000 Normal Closure Der Dienst hat die WebSocket-Verbindung ohne Fehler geschlossen.The service closed the WebSocket connection without an error. Falls das Schließen der WebSocket-Verbindung unerwartet aufgetreten ist, sollten Sie in der Dokumentation nachlesen. Stellen Sie sicher, dass Sie verstanden haben, wie und wann der Dienst die WebSocket-Verbindung beenden kann.If the WebSocket closure was unexpected, reread the documentation to ensure that you understand how and when the service can terminate the WebSocket connection.
1002 Protokollfehler1002 Protocol Error Der Client hat die Protokollanforderungen nicht erfüllt.The client failed to adhere to protocol requirements. Stellen Sie sicher, dass Sie die Protokolldokumentation verstehen und mit den Anforderungen vertraut sind.Ensure that you understand the protocol documentation and are clear about the requirements. Lesen Sie die Dokumentation zu den Fehlerursachen, um zu ermitteln, ob Sie gegen die Protokollanforderungen verstoßen.Read the previous documentation about error reasons to see if you're violating protocol requirements.
1007 Ungültige Nutzlastdaten1007 Invalid Payload Data Der Client hat eine ungültige Nutzlast in einer Protokollnachricht gesendet.The client sent an invalid payload in a protocol message. Überprüfen Sie die letzte Meldung, die Sie an den Dienst gesendet haben, auf Fehler.Check the last message that you sent to the service for errors. Lesen Sie die Dokumentation zu Nutzlastfehlern.Read the previous documentation about payload errors.
1011 Serverfehler1011 Server Error Der Dienst hat einen internen Fehler erkannt und konnte die Anforderung nicht erfüllen.The service encountered an internal error and could not satisfy the request. In den meisten Fällen ist dies ein vorübergehender Fehler.In most cases, this error is transient. Wiederholen Sie die Anforderung.Retry the request.

Sehen Sie sich ein JavaScript SDK an, bei dem es sich um eine Implementierung des WebSocket-basierten Spracherkennungsdienst-Protokolls handelt.See a JavaScript SDK that is an implementation of the WebSocket-based Speech Service protocol.