Bing Speech WebSocket 프로토콜Bing Speech WebSocket protocol

참고

The new Speech Service and SDK is replacing Bing Speech, which will no longer work starting October 15, 2019. For information on switching to the Speech Service, see Migrating from Bing Speech to the Speech Service.

Bing Speech는 음성 오디오를 텍스트로 변환할 수 있는 최고급 알고리즘을 탑재한 클라우드 기반 플랫폼입니다.Bing Speech is a cloud-based platform that features the most advanced algorithms available for converting spoken audio to text. Bing Speech 프로토콜은 클라이언트 응용 프로그램과 서비스 간의 연결 설정 및 상대 간에 교환하는 음성 인식 메시지(클라이언트 시작 메시지서비스 시작 메시지)를 정의합니다.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). 또한 원격 분석 메시지오류 처리를 설명합니다.In addition, telemetry messages and error handling are described.

연결 설정Connection establishment

음성 서비스 프로토콜은 WebSocket 표준 사양 IETF RFC 6455를 따릅니다.The Speech Service protocol follows the WebSocket standard specification IETF RFC 6455. WebSocket 연결은 HTTP 헤더를 포함한 HTTP 요청으로 시작하며, 이 헤더는 HTTP 의미 체계를 사용하는 대신에 WebSocket에 대한 연결을 업그레이드하고자 하는 클라이언트의 바람을 나타냅니다.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. 서버는 HTTP 101 Switching Protocols 응답을 반환하여 WebSocket 연결에 참가할 자신의 의향을 나타냅니다.The server indicates its willingness to participate in the WebSocket connection by returning an HTTP 101 Switching Protocols response. 이 핸드셰이크를 교환한 후 클라이언트와 서버는 모두 소켓을 개방 상태로 유지하고 메시지 기반 프로토콜을 사용하여 정보를 보내고 받기 시작합니다.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.

WebSocket 핸드셰이크를 시작하려면 클라이언트 응용 프로그램은 HTTPS GET 요청을 서비스에 보냅니다.To begin the WebSocket handshake, the client application sends an HTTPS GET request to the service. 이는 음성 특유의 다른 헤더와 함께 표준 WebSocket 업그레이드 헤더를 포함합니다.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

서비스는 다음 내용으로 응답합니다.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

모든 음성 요청에 대해 TLS 암호화가 필요합니다.All speech requests require the TLS encryption. 암호화되지 않은 음성 요청의 사용은 지원하지 않습니다.The use of unencrypted speech requests is not supported. 다음 TLS 버전을 지원합니다.The following TLS version is supported:

  • TLS 1.2TLS 1.2

연결 식별자Connection identifier

음성 서비스는 모든 클라이언트가 연결을 식별하기 위한 고유한 ID를 포함할 것을 요구합니다.Speech Service requires that all clients include a unique ID to identify the connection. 클라이언트는 WebSocket 핸드셰이크를 시작할 때 X-ConnectionId 헤더를 포함해야 합니다.Clients must include the X-ConnectionId header when they start a WebSocket handshake. X-ConnectionId 헤더는 UUID(universally unique identifier) 값이어야 합니다.The X-ConnectionId header must be a universally unique identifier (UUID) value. X-ConnectionId를 포함하지 않거나 X-ConnectionId 헤더에 대한 값을 지정하지 않거나 유효한 UUID 값을 포함하지 않은 WebSocket 업그레이드 요청은 서비스에서 400 Bad Request 응답과 함께 거부됩니다.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.

권한 부여Authorization

표준 WebSocket 핸드셰이크 헤더 외에 음성 요청에서는 인증 헤더가 필요합니다.In addition to the standard WebSocket handshake headers, speech requests require an Authorization header. 이 헤더가 없는 연결 요청은 서비스에서 HTTP 403 Forbidden 응답과 함께 거부됩니다.Connection requests without this header are rejected by the service with an HTTP 403 Forbidden response.

인증 헤더는 JWT(JSON Web Token) 액세스 토큰을 포함해야 합니다.The Authorization header must contain a JSON Web Token (JWT) access token.

유효한 JWT 액세스 토큰을 검색하는 데 사용되는 API 키를 구독하고 가져오는 방법에 대한 자세한 내용은 Cognitive Services 구독 페이지를 참조하세요.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.

API 키는 토큰 서비스에 전달됩니다.The API key is passed to the token service. 예: For example:

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

액세스 토큰을 위해 다음 헤더 정보가 필요합니다.The following header information is required for token access.

이름Name 형식Format 설명Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key ASCIIASCII 구독 키Your subscription key

토큰 서비스는 JWT 액세스 토큰을 text/plain으로 반환합니다.The token service returns the JWT access token as text/plain. 그런 다음, JWT는 문자열 Bearer가 앞에 추가된 인증 헤더로 핸드셰이크에 Base64 access_token으로 전달됩니다.Then the JWT is passed as a Base64 access_token to the handshake as an Authorization header prefixed with the string Bearer. 예: For example:

Authorization: Bearer [Base64 access_token]

쿠키Cookies

클라이언트는 RFC 6265에 지정한 대로 HTTP 쿠키를 지원해야 합니다.Clients must support HTTP cookies as specified in RFC 6265.

Http 리디렉션HTTP redirection

클라이언트는 HTTP 프로토콜 사양에서 지정한 표준 리디렉션 메커니즘을 지원해야 합니다.Clients must support the standard redirection mechanisms specified by the HTTP protocol specification.

음성 엔드포인트Speech endpoints

클라이언트는 음성 서비스의 적절한 엔드포인트를 사용해야 합니다.Clients must use an appropriate endpoint of Speech Service. 엔드포인트는 인식 모드 및 언어를 기반으로 합니다.The endpoint is based on recognition mode and language. 다음 표가 몇 가지 예를 보여줍니다.The table shows some examples.

ModeMode pathPath 서비스 URIService URI
대화형Interactive /speech/recognition/interactive/cognitiveservices/v1/speech/recognition/interactive/cognitiveservices/v1 https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=pt-BR
대화Conversation /speech/recognition/conversation/cognitiveservices/v1/speech/recognition/conversation/cognitiveservices/v1 https://speech.platform.bing.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US
받아쓰기Dictation /speech/recognition/dictation/cognitiveservices/v1/speech/recognition/dictation/cognitiveservices/v1 https://speech.platform.bing.com/speech/recognition/dictation/cognitiveservices/v1?language=fr-FR

자세한 내용은 서비스 URI 페이지를 참조하세요.For more information, see the Service URI page.

연결 문제 보고Report connection problems

클라이언트는 연결하는 중에 발견된 모든 문제를 즉시 보고하는 것이 좋습니다.Clients should immediately report all problems encountered while making a connection. 실패한 연결을 보고하기 위한 메시지 프로토콜은 연결 실패 원격 분석에서 설명합니다.The message protocol for reporting failed connections is described in Connection failure telemetry.

연결 지속 시간 제한Connection duration limitations

대표적인 웹 서비스 HTTP 연결과 비교할 때, WebSocket 연결은 오랜 시간 동안 지속됩니다.When compared with typical web service HTTP connections, WebSocket connections last a long time. 음성 서비스는 서비스에 대한 WebSocket 연결의 지속시간을 제한합니다.Speech Service places limitations on the duration of the WebSocket connections to the service:

  • 활성 WebSocket 연결에 대한 최대 지속 시간은 10분입니다.The maximum duration for any active WebSocket connection is 10 minutes. 연결은 서비스 또는 클라이언트가 해당 연결을 통해 WebSocket 메시지를 보내면 활성화됩니다.A connection is active if either the service or the client sends WebSocket messages over that connection. 서비스는 제한에 도달하면 경고 없이 연결을 종료합니다.The service terminates the connection without warning when the limit is reached. 클라이언트는 연결이 최대 연결 수명 시간 또는 임박한 시간까지 활성 상태로 유지되는 것을 요구하지 않는 사용자 시나리오를 개발하는 것이 좋습니다.Clients should develop user scenarios that do not require the connection to remain active at or near the maximum connection lifetime.

  • 비활성 WebSocket 연결에 대한 최대 지속 시간은 180초입니다.The maximum duration for any inactive WebSocket connection is 180 seconds. 연결은 서버도 클라이언트도 해당 연결을 통해 WebSocket 메시지를 보내지 않으면 비활성화됩니다.A connection is inactive if neither the service nor the client sent a WebSocket message over the connection. 최대 비활성 수명에 도달한 후 서비스는 비활성 WebSocket 연결을 종료합니다.After the maximum inactive lifetime is reached, the service terminates the inactive WebSocket connection.

메시지 유형Message types

클라이언트와 서비스 간에 WebSocket 연결이 설정된 후 클라이언트와 서비스가 모두 메시지를 보낼 수 있습니다.After a WebSocket connection is established between the client and the service, both the client and the service can send messages. 이 섹션에서는 이러한 WebSocket 메시지의 형식을 설명합니다.This section describes the format of these WebSocket messages.

IETF RFC 6455는 WebSocket 메시지가 텍스트 또는 이진 인코딩을 사용하여 데이터를 송신할 수 있도록 할 것을 지정합니다.IETF RFC 6455 specifies that WebSocket messages can transmit data by using either a text or a binary encoding. 두 인코딩은 서로 다른 실시간 형식을 사용합니다.The two encodings use different on-the-wire formats. 각 형식은 효율적인 인코딩, 전송 및 메시지 페이로드의 디코딩을 위해 최적화됩니다.Each format is optimized for efficient encoding, transmission, and decoding of the message payload.

텍스트 WebSocket 메시지Text WebSocket messages

텍스트 WebSocket 메시지는 헤더 섹션 및 HTTP 메시지에 사용되는 친숙한 이중 캐리지 리턴 줄 바꿈 쌍으로 구분된 본문으로 구성된 텍스트 정보의 페이로드를 전달합니다.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. 그리고 HTTP 메시지와 마찬가지로 텍스트 WebSocket 메시지는 단일 캐리지 리턴 줄 바꿈 쌍으로 구분된 이름:값 형식으로 헤더를 지정합니다.And, like HTTP messages, text WebSocket messages specify headers in name: value format separated by a single-carriage-return newline pair. 텍스트 WebSocket 메시지에 포함된 텍스트는 UTF-8 인코딩을 사용해야 합니다.Any text included in a text WebSocket message must use UTF-8 encoding.

텍스트 WebSocket 메시지는 헤더 경로에 메시지 경로를 지정해야 합니다.Text WebSocket messages must specify a message path in the header Path. 이 헤더의 값은 이 문서에서 나중에 정의하는 음성 프로토콜 메시지 유형 중 하나이어야 합니다.The value of this header must be one of the speech protocol message types defined later in this document.

이진 WebSocket 메시지Binary WebSocket messages

이진 WebSocket 메시지는 이진 페이로드를 전달합니다.Binary WebSocket messages carry a binary payload. 음성 서비스 프로토콜에서 오디오는 이진 WebSocket 메시지를 사용하여 서비스에서 송신 및 수신됩니다.In the Speech Service protocol, audio is transmitted to and received from the service by using binary WebSocket messages. 모든 다른 메시지는 텍스트 WebSocket 메시지입니다.All other messages are text WebSocket messages.

텍스트 WebSocket 메시지와 마찬가지로 이진 WebSocket 메시지도 헤더와 본문 섹션으로 구성됩니다.Like text WebSocket messages, binary WebSocket messages consist of a header and a body section. 이진 WebSocket 메시지의 처음 2바이트는 헤더 섹션의 16비트 정수 크기를 big-endian 순서로 지정합니다.The first 2 bytes of the binary WebSocket message specify, in big-endian order, the 16-bit integer size of the header section. 최소 헤더 섹션 크기는 0바이트입니다.The minimum header section size is 0 bytes. 최대 크기는 8,192바이트입니다.The maximum size is 8,192 bytes. 이진 WebSocket 메시지의 헤더의 텍스트는 US-ASCII 인코딩을 사용해야 합니다.The text in the headers of binary WebSocket messages must use US-ASCII encoding.

이진 WebSocket 메시지의 헤더는 텍스트 WebSocket 메시지에서와 같은 형식으로 인코딩됩니다.Headers in a binary WebSocket message are encoded in the same format as in text WebSocket messages. 이름:값 형식은 단일 캐리지 리턴 줄 바꿈 쌍으로 구분됩니다.The name:value format is separated by a single-carriage-return newline pair. 이진 WebSocket 메시지는 헤더 경로에 메시지 경로를 지정해야 합니다.Binary WebSocket messages must specify a message path in the header Path. 이 헤더의 값은 이 문서에서 나중에 정의하는 음성 프로토콜 메시지 유형 중 하나이어야 합니다.The value of this header must be one of the speech protocol message types defined later in this document.

텍스트 및 이진 WebSocket 메시지 모두 음성 서비스 프로토콜에 사용됩니다.Both text and binary WebSocket messages are used in the Speech Service protocol.

클라이언트 시작 메시지Client-originated messages

연결이 설정된 후 클라이언트와 서비스가 모두 메시지를 보내기 시작할 수 있습니다.After the connection is established, both the client and the service can start to send messages. 이 섹션에서는 클라이언트 응용 프로그램이 음성 서비스에 보내는 메시지의 형식 및 페이로드를 설명합니다.This section describes the format and payload of messages that client applications send to Speech Service. 서비스 시작 메시지 섹션에서는 음성 서비스에서 시작하고 클라이언트 응용 프로그램에 보내지는 메시지를 보여줍니다.The section Service-originated messages presents the messages that originate in Speech Service and are sent to the client applications.

클라이언트가 서비스에 보내는 주 메시지는 speech.config, audiotelemetry 메시지입니다.The main messages sent by the client to the services are speech.config, audio, and telemetry messages. 각 메시지를 자세히 검토하기 전에 이러한 모든 메시지에 공통적으로 필요한 메시지 헤더를 설명합니다.Before we consider each message in detail, the common required message headers for all these messages are described.

필요한 메시지 헤더Required message headers

모든 클라이언트 시작 메시지에 대해 다음 헤더가 필요합니다.The following headers are required for all client-originated messages.

헤더Header Value
pathPath 이 문서에 지정된 메시지 경로The message path as specified in this document
X-RequestIdX-RequestId "대시 없는" 형식의 UUIDUUID in "no-dash" format
X-TimestampX-Timestamp ISO 8601 형식의 UTC 시계 타임스탬프Client UTC clock time stamp in ISO 8601 format

X-RequestId 헤더X-RequestId header

클라이언트 시작 요청은 X-RequestId 메시지 헤더에 의해 고유하게 식별됩니다.Client-originated requests are uniquely identified by the X-RequestId message header. 이 헤더는 모든 클라이언트 시작 메시지에 대해 필요합니다.This header is required for all client-originated messages. X-RequestId 헤더 값은 "대시 없는" 형식의 UUID이어야 합니다(예: 123e4567e89b12d3a456426655440000).The X-RequestId header value must be a UUID in "no-dash" form, for example, 123e4567e89b12d3a456426655440000. 이는 Canonical 형식 123e4567-e89b-12d3-a456-426655440000일 수 없습니다.It cannot be in the canonical form 123e4567-e89b-12d3-a456-426655440000. X-RequestId 헤더가 없거나 UUID에 대해 잘못된 형식을 사용하는 헤더 값을 가진 요청은 서비스가 WebSocket 연결을 종료하게 합니다.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 헤더X-Timestamp header

클라이언트 응용 프로그램이 음성 서비스에 보낸 각 메시지는 X-Timestamp 헤더를 포함해야 합니다.Each message sent to Speech Service by a client application must include an X-Timestamp header. 이 헤더에 대한 값은 클라이언트가 메시지를 보내는 시간입니다.The value for this header is the time when the client sends the message. X-Timestamp 헤더가 없거나 잘못된 형식을 사용하는 헤더 값을 가진 요청은 서비스가 WebSocket 연결을 종료하게 합니다.Requests without an X-Timestamp header or with a header value that uses the wrong format cause the service to terminate the WebSocket connection.

X-Timestamp 헤더 값은 'yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffZ' 형식이어야 합니다. 단, 'fffffff'는 초의 분수입니다.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. 예를 들어 '12.5'는 '12 + 5/10초'를 의미하며 '12.526'은 '12 plus 526/1000초'를 의미합니다.For example, '12.5' means '12 + 5/10 seconds' and '12.526' means '12 plus 526/1000 seconds'. 이 형식은 ISO 8601를 준수하며 표준 HTTP Date 헤더와 달리 밀리초 분해능을 제공할 수 있습니다.This format complies with ISO 8601 and, unlike the standard HTTP Date header, it can provide millisecond resolution. 클라이언트 응용 프로그램은 타임스탬프를 가장 가까운 밀리초로 반올림할 수 있습니다.Client applications might round time stamps to the nearest millisecond. 클라이언트 응용 프로그램은 NTP(Network Time Protocol) 서버를 사용하여 장치 시계가 시간을 정확히 추적하도록 해야 합니다.Client applications need to ensure that the device clock accurately tracks time by using a Network Time Protocol (NTP) server.

메시지 speech.configMessage speech.config

음성 서비스가 최상의 예상 음성 인식을 제공하려면 응용 프로그램의 특성을 알아야 합니다.Speech Service needs to know the characteristics of your application to provide the best possible speech recognition. 필요한 특성 데이터는 응용 프로그램을 구동하는 장치 및 OS에 관한 정보를 포함합니다.The required characteristics data includes information about the device and OS that powers your application. 이 정보를 speech.config 메시지에 제공합니다.You supply this information in the speech.config message.

클라이언트는 음성 서비스에 대한 연결을 설정한 후 audio 메시지를 보내기 전에 speech.config 메시지를 보내야 합니다.Clients must send a speech.config message immediately after they establish the connection to Speech Service and before they send any audio messages. speech.config 메시지를 연결당 한 번만 보내야 합니다.You need to send a speech.config message only once per connection.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
본문Body JSON 구조인 페이로드The payload as a JSON structure

필요한 메시지 헤더Required message headers

헤더 이름Header name Value
pathPath speech.config
X-TimestampX-Timestamp ISO 8601 형식의 UTC 시계 타임스탬프Client UTC clock time stamp in ISO 8601 format
콘텐츠 형식Content-Type application/json; charset=utf-8application/json; charset=utf-8

음성 서비스 프로토콜의 모든 클라이언트 시작 메시지와 마찬가지로 speech.config 메시지도 메시지를 서비스에 보낸 클라이언트 UTC 시계 시간을 기록하는 X-Timestamp 헤더를 포함해야 합니다.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. speech.config 메시지는 특정 음성 요청과 연결되지 않으므로 X-RequestId 헤더를 요구하지 않습니다.The speech.config message does not require an X-RequestId header because this message isn't associated with a particular speech request.

메시지 페이로드Message payload

speech.config 메시지의 페이로드는 응용 프로그램에 관한 정보를 포함하는 JSON 구조입니다.The payload of the speech.config message is a JSON structure that contains information about the application. 다음 예제는 이 정보를 보여줍니다.The following example shows this information. 클라이언트 및 장치 컨텍스트 정보는 JSON 구조의 context 요소에 포함됩니다.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"
      }
    },
  }
}
시스템 요소System element

speech.config 메시지의 system.version 요소는 클라이언트 응용 프로그램 또는 장치가 사용한 음성 SDK 소프트웨어의 버전을 포함합니다.The system.version element of the speech.config message contains the version of the speech SDK software used by the client application or device. 이 값은 major.minor.build.branch 형식입니다.The value is in the form major.minor.build.branch. branch 구성 요소는 해당하지 않는 경우 생략할 수 있습니다.You can omit the branch component if it's not applicable.

OS 요소OS element
필드Field 설명Description 사용 현황Usage
os.platformos.platform 응용 프로그램을 호스팅하는 OS 플랫폼. 예: Windows, Android, iOS 또는 LinuxThe OS platform that hosts the application, for example, Windows, Android, iOS, or Linux 필수Required
os.nameos.name OS 제품 이름. 예: Debian 또는 Windows 10The OS product name, for example, Debian or Windows 10 필수Required
os.versionos.version major.minor.build.branch 형식의 OS 버전The version of the OS in the form major.minor.build.branch 필수Required
장치 요소Device element
필드Field 설명Description 사용 현황Usage
device.manufacturerdevice.manufacturer 장치 하드웨어 제조업체The device hardware manufacturer 필수Required
device.modeldevice.model 장치 모델The device model 필수Required
device.versiondevice.version 장치 제조업체가 제공한 장치 소프트웨어 버전.The device software version provided by the device manufacturer. 이 값은 제조업체가 추적할 수 있는 장치의 버전을 지정합니다.This value specifies a version of the device that can be tracked by the manufacturer. 필수Required

메시지 audioMessage audio

음성 지원 클라이언트 응용 프로그램은 오디오 스트림을 일련의 오디오 청크로 변환하여 오디오를 음성 서비스에 보냅니다.Speech-enabled client applications send audio to Speech Service by converting the audio stream into a series of audio chunks. 각 오디오 청크는 서비스에서 전사할 음성 오디오의 세그먼트를 전달합니다.Each chunk of audio carries a segment of the spoken audio that's to be transcribed by the service. 단일 오디오 청크의 최대 크기는 8,192바이트입니다.The maximum size of a single audio chunk is 8,192 bytes. 오디오 스트림 메시지는 이진 WebSocket 메시지입니다.Audio stream messages are Binary WebSocket messages.

클라이언트는 audio 메시지를 사용하여 오디오 청크를 서비스에 보냅니다.Clients use the audio message to send an audio chunk to the service. 클라이언트는 마이크에서 오디오를 청크 단위로 읽고 이 청크를 전사하기 위해 음성 서비스에 보냅니다.Clients read audio from the microphone in chunks and send these chunks to Speech Service for transcription. 첫 번째 audio 메시지는 오디오가 서비스에서 지원하는 인코딩 형식 중 하나에 적합함을 올바르게 지정하는 잘 구성된 헤더를 포함해야 합니다.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. 추가 audio 메시지는 마이크에서 읽은 이진 오디오 스트림 데이터만 포함합니다.Additional audio messages contain only the binary audio stream data read from the microphone.

클라이언트는 선택적으로 0 길이 본문을 가진 audio 메시지를 보내도 됩니다.Clients might optionally send an audio message with a zero-length body. 이 메시지는 사용자가 말하기를 중단하고 발성이 완료되고 마이크가 꺼졌음을 클라이언트가 알고 있다는 것을 서비스에 알립니다.This message tells the service that the client knows that the user stopped speaking, the utterance is finished, and the microphone is turned off.

음성 서비스는 고유한 요청 식별자를 포함하는 첫 번째 audio 메시지를 사용하여 새 요청/응답 사이클 또는 회차의 시작을 신호합니다.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. 서비스는 새 요청 식별자를 포함한 audio 메시지를 수신한 후 이전 회차와 연결된 큐에 저장되거나 보내지 않은 메시지를 버립니다.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.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 이진Binary
본문Body 오디오 청크에 대한 이진 데이터입니다.The binary data for the audio chunk. 최대 크기는 8,192바이트입니다.Maximum size is 8,192 bytes.

필요한 메시지 헤더Required message headers

모든 audio 메시지에 대해 다음 헤더가 필요합니다.The following headers are required for all audio messages.

헤더Header Value
pathPath audio
X-RequestIdX-RequestId "대시 없는" 형식의 UUIDUUID in "no-dash" format
X-TimestampX-Timestamp ISO 8601 형식의 UTC 시계 타임스탬프Client UTC clock time stamp in ISO 8601 format
콘텐츠 형식Content-Type 오디오 콘텐츠 형식입니다.The audio content type. 형식은 audio/x-wav(PCM) 또는 audio/silk(SILK)이어야 합니다.The type must be either audio/x-wav (PCM) or audio/silk (SILK).

지원되는 오디오 인코딩Supported audio encodings

이 섹션에서는 음성 서비스에서 지원하는 오디오 코덱을 설명합니다.This section describes the audio codecs supported by Speech Service.

PCMPCM

음성 서비스는 압축되지 않은 PCM(펄스 코드 변조) 오디오를 수용합니다.Speech Service accepts uncompressed pulse code modulation (PCM) audio. 오디오는 WAV 형식으로 서비스에 보내지므로 첫 번째 오디오 청크는 유효한 RIFF(Resource Interchange File Format) 헤더를 포함해야 합니다.Audio is sent to the service in WAV format, so the first audio chunk must contain a valid Resource Interchange File Format (RIFF) header. 클라이언트가 유효한 RIFF 헤더를 포함하지 않은 오디오 청크로 회차를 시작한 경우 서비스는 요청을 거부하고 WebSocket 연결을 종료합니다.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.

PCM 오디오는 샘플당 16비트 및 채널(riff-16khz-16bit-mono-pcm) 한 개를 사용하여 16 kHz 속도로 샘플링해야 합니다.PCM audio must be sampled at 16 kHz with 16 bits per sample and one channel (riff-16khz-16bit-mono-pcm). 음성 서비스는 스테레오 오디오 스트림을 지원하지 않으며 지정된 비트 전송률, 샘플 속도 또는 채널 수를 사용하지 않은 오디오 스트림을 거부합니다.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는 공개되고 사용료가 없고 매우 용도가 다양한 오디오 코덱입니다.Opus is an open, royalty-free, highly versatile audio codec. 음성 서비스는 Opus를 32000 또는 16000의 일정한 비트 전송률로 지원합니다.Speech Service supports Opus at a constant bit rate of 32000 or 16000. audio/ogg MIME 형식에서 지정하는 Opus용 OGG 컨테이너만이 현재 지원됩니다.Only the OGG container for Opus is currently supported that is specified by the audio/ogg mime type.

Opus를 사용하려면 JavaScript 샘플을 수정하고 RecognizerSetup 메서드를 반환하도록 변경합니다.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
                     }
              )
          ));

음성 끝 검색Detect end of speech

사람은 말하기를 마친 시기를 명시적으로 신호하지 않습니다.Humans do not explicitly signal when they're finished speaking. 음성을 입력으로 수용하는 응용 프로그램은 오디오 스트림에서 음성의 끝을 처리하기 위한 두 가지 선택: 서비스 음성 끝 검색 및 클라이언트 음성 끝 검색을 포함합니다.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. 이 두 선택 중에서 서비스 음성 끝 검색이 일반적으로 더 나은 경험을 제공합니다.Of these two choices, service end-of-speech detection usually provides a better user experience.

서비스 음성 끝 검색Service end-of-speech detection

손이 가지 않는 최적의 음성 경험을 만들기 위해 응용 프로그램은 서비스에서 사용자가 말하기를 마친 시기를 검색할 수 있도록 합니다.To build the ideal hands-free speech experience, applications allow the service to detect when the user has finished speaking. 클라이언트는 서비스가 무음을 검색하고 speech.endDetected 메시지로 다시 응답할 때까지 마이크의 오디오를 오디오 청크로 보냅니다.Clients send audio from the microphone as audio chunks until the service detects silence and responds back with a speech.endDetected message.

클라이언트 음성 끝 검색Client end-of-speech detection

사용자가 어떤 방법으로든 음성 끝을 신호할 수 있도록 하는 클라이언트 응용 프로그램은 서비스에도 해당 신호를 제공할 수 있습니다.Client applications that allow the user to signal the end of speech in some way also can give the service that signal. 예를 들어 클라이언트 응용 프로그램은 사용자가 누를 수 있는 "정지" 또는 "음소거" 단추를 포함할 수 있습니다.For example, a client application might have a "Stop" or "Mute" button that the user can press. 음성 끝을 신호하려면 클라이언트 응용 프로그램은 0 길이 본문을 가진 오디오 청크를 보냅니다.To signal end-of-speech, client applications send an audio chunk message with a zero-length body. 음성 서비스는 이 메시지를 수신 오디오 스트림의 끝으로 해석합니다.Speech Service interprets this message as the end of the incoming audio stream.

메시지 telemetryMessage telemetry

클라이언트 응용 프로그램은 회차에 관한 원격 분석을 음성 서비스에 보내서 각 회차의 끝을 수신 확인해야 합니다.Client applications must acknowledge the end of each turn by sending telemetry about the turn to Speech Service. 회차 끝 수신 확인을 사용하여 음성 서비스는 요청 완료에 필요한 모든 메시지와 해당 응답이 클라이언트에서 올바르게 수신되도록 할 수 있습니다.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. 회차 끝 수신 확인을 사용하여 음성 서비스는 클라이언트 응용 프로그램이 예상한 대로 수행하고 있는지 확인할 수 있습니다.Turn-end acknowledgment also allows Speech Service to verify that the client applications are performing as expected. 이 정보는 음성 지원 응용 프로그램의 문제 해결에 도움을 주어야 하는 경우 매우 중요합니다.This information is invaluable if you need help troubleshooting your speech-enabled application.

클라이언트는 turn.end 메시지를 수신한 직후 telemetry 메시지를 보내서 회차 끝을 수신 확인해야 합니다.Clients must acknowledge the end of a turn by sending a telemetry message soon after receiving a turn.end message. 클라이언트는 가능하면 일찍 turn.end 수신 확인을 시도하는 것이 좋습니다.Clients should attempt to acknowledge the turn.end as soon as possible. 클라이언트 응용 프로그램이 회차 끝을 수신 확인하는 데 실패한 경우 음성 서비스는 오류와 함께 연결을 종료할 수 있습니다.If a client application fails to acknowledge the turn end, Speech Service might terminate the connection with an error. 클라이언트는 X-RequestId 값에 의해 식별된 각 요청 및 응답에 대해 telemetry 메시지를 한 개만 보내야 합니다.Clients must send only one telemetry message for each request and response identified by the X-RequestId value.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath telemetry
X-TimestampX-Timestamp ISO 8601 형식의 UTC 시계 타임스탬프Client UTC clock time stamp in ISO 8601 format
콘텐츠 형식Content-Type application/json
본문Body 회차에 관한 클라이언트 정보를 포함하는 JSON 구조A JSON structure that contains client information about the turn

telemetry 메시지의 본문에 대한 스키마는 원격 분석 스키마 섹션에서 정의합니다.The schema for the body of the telemetry message is defined in the Telemetry schema section.

중단된 연결에 대한 원격 분석Telemetry for interrupted connections

네트워크 연결이 회차 중에 어떤 이유로든 실패하고 클라이언트가 서비스에서 turn.end 메시지를 수신하지 않는 경우 클라이언트는 telemetry 메시지를 보냅니다.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. 이 메시지는 다음에 클라이언트가 서비스에 연결할 때 실패한 요청을 설명합니다.This message describes the failed request the next time the client makes a connection to the service. 클라이언트가 telemetry 메시지를 보내기 위해 즉시 연결을 시도할 필요는 없습니다.Clients do not have to immediately attempt a connection to send the telemetry message. 메시지를 클라이언트에 버퍼링했다가 나중에 사용자가 요청한 연결에 대해 보낼 수 있습니다.The message might be buffered on the client and sent over a future user-requested connection. 실패한 요청에 대한 telemetry 메시지는 실패한 요청에서 온 X-RequestId 값을 사용해야 합니다.The telemetry message for the failed request must use the X-RequestId value from the failed request. 이 값을 연결이 설정되자마자 서비스에 보낼 수 있으므로 다른 메시지에 대한 보내기 또는 수신을 기다릴 필요가 없습니다.It might be sent to the service as soon as a connection is established, without waiting to send or receive for other messages.

서비스 시작 메시지Service-originated messages

이 섹션에서는 음성 서비스에서 시작하고 클라이언트에 보내지는 메시지를 설명합니다.This section describes the messages that originate in Speech Service and are sent to the client. 음성 서비스는 클라이언트 기능의 레지스트리를 유지하며 각 클라이언트가 요구하는 메시지를 생성하므로 일부 클라이언트는 여기서 설명하는 일부 메시지를 수신하지 않을 수도 있습니다.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. 요약하자면 메시지는 경로 헤더에 의해 참조됩니다.For brevity, messages are referenced by the value of the Path header. 예를 들어 경로speech.hypothesis를 포함한 WebSocket 텍스트 메시지를 speech.hypothesis 메시지라고 합니다.For example, we refer to a WebSocket text message with the Path value speech.hypothesis as a speech.hypothesis message.

메시지 speech.startDetectedMessage speech.startDetected

speech.startDetected 메시지는 음성 서비스가 오디오 스트림에서 음성을 검색했음을 나타냅니다.The speech.startDetected message indicates that Speech Service detected speech in the audio stream.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath speech.startDetected
콘텐츠 형식Content-Type application/json; charset=utf-8application/json; charset=utf-8
본문Body 음성 시작이 검색된 경우 조건에 관한 정보를 포함하는 JSON 구조입니다.The JSON structure that contains information about the conditions when the start of speech was detected. 이 구조의 오프셋 필드는 스트림의 시작을 기준으로 오디오 스트림에서 음성이 검색된 시간의 오프셋(100나노초 단위)을 지정합니다.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.

샘플 메시지Sample message

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

{
  "Offset": 100000
}

메시지 speech.hypothesisMessage speech.hypothesis

음성 인식 중에 음성 서비스는 주기적으로 서비스가 인식한 단어에 관한 가설을 생성합니다.During speech recognition, Speech Service periodically generates hypotheses about the words the service recognized. 음성 서비스는 이 가설을 대략 300밀리초마다 클라이언트에 보냅니다.Speech Service sends these hypotheses to the client approximately every 300 milliseconds. speech.hypothesis는 사용자 음성 경험을 향상시키기 위해서만 적합합니다.The speech.hypothesis is suitable only for enhancing the user speech experience. 이러한 메시지의 텍스트 내용 또는 정확도에 의존하지 않아야 합니다.You must not take any dependency on the content or accuracy of the text in these messages.

speech.hypothesis 메시지는 일부 텍스트 렌더링 기능을 포함하고 진행 중인 인식의 실시간에 가까운 피드백을 말하는 사람에게 제공하려는 클라이언트에 적용됩니다.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.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath speech.hypothesis
X-RequestIdX-RequestId "대시 없는" 형식의 UUIDUUID in "no-dash" format
콘텐츠 형식Content-Type application/jsonapplication/json
본문Body 음성 가설 JSON 구조The speech hypothesis JSON structure

샘플 메시지Sample message

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

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

오프셋 요소는 오디오 스트림의 시작을 기준으로 구가 인식된 오프셋(100나노초 단위)을 지정합니다.The Offset element specifies the offset (in 100-nanosecond units) when the phrase was recognized, relative to the start of the audio stream.

지속 시간 요소는 이 음성 구의 지속 시간(100나노초 단위)을 지정합니다.The Duration element specifies the duration (in 100-nanosecond units) of this speech phrase.

클라이언트는 음성 가설에 포함된 주파수, 타이밍 또는 텍스트, 또는 두 음성 가설의 텍스트 일관성에 관하여 가정을 하지 않아야 합니다.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. 가설은 단지 서비스의 전사 프로세스에 대한 스냅숏일 뿐이며,The hypotheses are just snapshots into the transcription process in the service. 전사의 안정된 누적을 나타내지 않습니다.They do not represent a stable accumulation of transcription. 예를 들어 첫 번째 음성 가설이 단어 "fine fun"을 포함하고 두 번째 가설이 단어 "find funny"를 포함할 수 있습니다.For example, a first speech hypothesis might contain the words "fine fun," and the second hypothesis might contain the words "find funny." 음성 서비스는 음성 가설의 텍스트에 관하여 사후 처리(예: 대문자화, 문장 부호)를 수행하지 않습니다.Speech Service doesn't perform any post-processing (for example, capitalization, punctuation) on the text in the speech hypothesis.

메시지 speech.phraseMessage speech.phrase

음성 서비스가 변경하지 않을 인식 결과를 생성하기에 충분한 정보를 확보했다고 결정하면 서비스는 speech.phrase 메시지를 생성합니다.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. 음성 서비스는 사용자가 문장 또는 구를 마친 것을 검색한 후 이러한 결과를 생성합니다.Speech Service produces these results after it detects that the user has finished a sentence or phrase.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath speech.phrase
콘텐츠 형식Content-Type application/jsonapplication/json
본문Body 음성 구 JSON 구조The speech phrase JSON structure

음성 구 JSON 스키마는 RecognitionStatus, DisplayText, OffsetDuration 필드를 포함합니다.The speech phrase JSON schema includes the following fields: RecognitionStatus, DisplayText, Offset, and Duration. 이러한 필드에 대한 자세한 내용은 전사 응답을 참조하세요.For more information about these fields, see Transcription responses.

샘플 메시지Sample 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.endDetectedMessage speech.endDetected

speech.endDetected 메시지는 클라이언트 응용 프로그램이 서비스에 대한 오디오 스트리밍을 중단하는 것이 좋음을 지정합니다.The speech.endDetected message specifies that the client application should stop streaming audio to the service.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath speech.endDetected
본문Body 음성 끝이 검색된 시간의 오프셋을 포함하는 JSON 구조입니다.The JSON structure that contains the offset when the end of speech was detected. 오프셋은 인식을 위해 사용한 오디오의 시작에서 100나노초 단위 오프셋으로 나타냅니다.The offset is represented in 100-nanosecond units offset from the start of audio that's used for recognition.
콘텐츠 형식Content-Type application/json; charset=utf-8application/json; charset=utf-8

샘플 메시지Sample message

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

{
  "Offset": 0
}

오프셋 요소는 오디오 스트림의 시작을 기준으로 구가 인식된 오프셋(100나노초 단위)을 지정합니다.The Offset element specifies the offset (in 100-nanosecond units) when the phrase was recognized, relative to the start of the audio stream.

메시지 turn.startMessage turn.start

turn.start는 서비스 관점에서 회차의 시작을 신호합니다.The turn.start signals the start of a turn from the perspective of the service. turn.start 메시지는 언제나 요청에 대해 수신하는 첫 번째 응답 메시지입니다.The turn.start message is always the first response message you receive for any request. turn.start 메시지를 수신하지 않은 경우 서비스 연결의 시작이 잘못되었다고 가정합니다.If you don't receive a turn.start message, assume that the state of the service connection is invalid.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath turn.start
콘텐츠 형식Content-Type application/json; charset=utf-8application/json; charset=utf-8
본문Body JSON 구조JSON structure

샘플 메시지Sample message

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

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

turn.start 메시지의 본문은 회차의 시작에 대한 컨텍스트를 포함하는 JSON 구조입니다.The body of the turn.start message is a JSON structure that contains context for the start of the turn. 컨텍스트 요소는 serviceTag 속성을 포함합니다.The context element contains a serviceTag property. 이 속성은 서비스가 회차와 연결된 태그 값을 지정합니다.This property specifies a tag value that the service has associated with the turn. 이 값은 Microsoft가 고객의 응용 프로그램의 문제 해결을 도와야 하는 경우에 사용할 수 있습니다.This value can be used by Microsoft if you need help troubleshooting failures in your application.

메시지 turn.endMessage turn.end

turn.end는 서비스 관점에서 회차의 끝을 신호합니다.The turn.end signals the end of a turn from the perspective of the service. turn.end 메시지는 언제나 요청에 대해 수신하는 마지막 응답 메시지입니다.The turn.end message is always the last response message you receive for any request. 클라이언트는 이 메시지의 수신을 정리 작업 및 유휴 상태로 전환의 신호로 사용할 수 있습니다.Clients can use the receipt of this message as a signal for cleanup activities and transitioning to an idle state. turn.end 메시지를 수신하지 않은 경우 서비스 연결의 시작이 잘못되었다고 가정합니다.If you don't receive a turn.end message, assume that the state of the service connection is invalid. 그러한 경우 서비스에 대한 기존 연결을 닫고 다시 연결합니다.In those cases, close the existing connection to the service and reconnect.

필드Field 설명Description
WebSocket 메시지 인코딩WebSocket message encoding 텍스트Text
pathPath turn.end
본문Body 없음None

샘플 메시지Sample message

Path: turn.end
X-RequestId: 123e4567e89b12d3a456426655440000

원격 분석 스키마Telemetry schema

원격 분석 메시지의 본문은 회차 또는 시도한 연결에 관한 클라이언트 정보를 포함하는 JSON 구조입니다.The body of the telemetry message is a JSON structure that contains client information about a turn or an attempted connection. 이 구조는 클라이언트 이벤트가 발생하는 시간을 기록하는 클라이언트 타임스탬프로 구성됩니다.The structure is made up of client time stamps that record when client events occur. 각 타임스탬프는 "X-Timestamp 헤더"라는 제목의 섹션에서 설명한 대로 ISO 8601 형식이어야 합니다.Each time stamp must be in ISO 8601 format as described in the section titled "X-Timestamp header." JSON 구조에 일부 필수 필드를 지정하지 않거나 정확한 타임스탬프 형식을 사용하지 않은 원격 분석 메시지는 서비스가 클라이언트에 대한 연결을 종료하게 할 수 있습니다.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 must supply valid values for all required fields. 클라이언트는 해당하는 경우 언제나 선택 필드에 대한 값을 제공하는 것이 좋습니다.Clients should supply values for optional fields whenever appropriate. 이 섹션의 샘플에 나오는 값은 예시용일 뿐입니다.The values shown in samples in this section are for illustration only.

원격 분석 스키마는 수신된 메시지 타임스탬프와 메트릭 부분으로 나누어집니다.Telemetry schema is divided into the following parts: received message time stamps and metrics. 각 부분의 형식과 사용을 다음 섹션에서 지정합니다.The format and usage of each part is specified in the following sections.

수신된 메시지 타임스탬프Received message time stamps

클라이언트는 서비스에 성공적으로 연결한 후 수신하는 모든 메시지에 대해 수신 시간 값을 포함해야 합니다.Clients must include time-of-receipt values for all messages that they receive after successfully connecting to the service. 이러한 값은 클라이언트가 네트워크에서 각 메시지를 수신한 시간을 기록해야 합니다.These values must record the time when the client received each message from the network. 이 값은 다른 시간을 기록하지 않는 것이 좋습니다.The value should not record any other time. 예를 들어 클라이언트는 메시지에 대해 작업한 시간을 기록하지 않는 것이 좋습니다.For example, the client should not record the time when it acted on the message. 수신된 메시지 타임스탬프는 이름:값 쌍의 배열에 지정됩니다.The received message time stamps are specified in an array of name:value pairs. 쌍의 이름은 메시지의 경로 값을 지정합니다.The name of the pair specifies the Path value of the message. 쌍의 값은 메시지가 수신된 클라이언트 시간을 지정합니다.The value of the pair specifies the client time when the message was received. 또는 지정된 이름의 메시지가 두 개 이상 수신된 경우 쌍의 값은 해당 메시지가 수신된 시간을 나타내는 타임스탬프의 배열입니다.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" }
  ]

클라이언트는 서비스에서 보낸 모든 메시지의 타임스탬프를 JSON 본문에 포함하여 해당 메시지의 수신을 확인해야 합니다.Clients must acknowledge the receipt of all messages sent by the service by including time stamps for those messages in the JSON body. 클라이언트가 메시지의 수신을 확인하지 않으면 서비스가 연결을 종료할 수 있습니다.If a client fails to acknowledge the receipt of a message, the service might terminate the connection.

메트릭Metrics

클라이언트는 요청의 수명 중에 발생한 이벤트에 관한 정보를 포함해야 합니다.Clients must include information about events that occurred during the lifetime of a request. 다음 메트릭이 지원됩니다. Connection, MicrophoneListeningTrigger.The following metrics are supported: Connection, Microphone, and ListeningTrigger.

메트릭 ConnectionMetric Connection

Connection 메트릭은 클라이언트의 연결 시도에 관한 세부 정보를 지정합니다.The Connection metric specifies details about connection attempts by the client. 이 메트릭은 WebSocket 연결이 시작된 시간과 종료된 시간의 타임스탬프를 포함해야 합니다.The metric must include time stamps of when the WebSocket connection was started and finished. Connection 메트릭은 첫 번째 연결 회차에 대해서만 필요합니다.The Connection metric is required only for the first turn of a connection. 이후 회차는 이 정보를 포함하지 않아도 됩니다.Subsequent turns are not required to include this information. 클라이언트가 연결이 설정되기 전에 여러 번 연결을 시도한 경우 시도한 모든 연결에 관한 정보를 포함하는 것이 좋습니다.If a client makes multiple connection attempts before a connection is established, information about all the connection attempts should be included. 자세한 내용은 연결 실패 원격 분석을 참조하세요.For more information, see Connection failure telemetry.

필드Field 설명Description 사용 현황Usage
이름Name Connection 필수Required
IdId 이 연결 요청에 대한 X-ConnectionId 헤더에 사용한 연결 식별자 값The connection identifier value that was used in the X-ConnectionId header for this connection request 필수Required
시작Start 클라이언트가 연결 요청을 보낸 시간The time when the client sent the connection request 필수Required
End 클라이언트가 연결이 성공적으로 설정된 사실 또는 오류가 발생한 경우 거부, 거절 또는 실패한 사실의 알림을 받은 시간The time when the client received notification that the connection was established successfully or, in error cases, rejected, refused, or failed 필수Required
오류Error 발생한 오류(있는 경우)에 대한 설명.A description of the error that occurred, if any. 연결이 성공한 경우 클라이언트는 이 필드를 생략하는 것이 좋습니다.If the connection was successful, clients should omit this field. 이 필드의 최대 길이는 50자입니다.The maximum length of this field is 50 characters. 오류의 경우 필수, 그렇지 않으면 생략됨Required for error cases, omitted otherwise

오류 설명은 50문자 이하로 하는 것이 좋으며 다음 표에 나열한 값 중 하나로 하는 것이 가장 좋습니다.The error description should be at most 50 characters and ideally should be one of the values listed in the following table. 오류 조건이 이러한 값 중 하나와 일치하지 않는 경우 클라이언트는 CamelCasing을 공백 없이 사용하여 오류 조건에 대한 간결한 설명을 사용할 수 있습니다.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. 서비스에 연결해야 원격 분석 메시지를 보낼 수 있으므로 과도적 또는 일시적 오류 조건만이 원격 분석 메시지에 보고될 수 있습니다.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. 클라이언트가 서비스에 대한 연결을 설정하는 것을 영구적으로 차단하는 오류 조건은 클라이언트가 원격 분석 메시지를 포함하여 메시지를 서비스에 보내지 못하게 합니다.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.

오류Error 사용 현황Usage
DNSfailureDNSfailure 클라이언트가 네트워크 스택의 DNS 실패 때문에 서비스에 연결할 수 없었습니다.The client was unable to connect to the service because of a DNS failure in the network stack.
NoNetworkNoNetwork 클라이언트가 연결을 시도했지만 네트워크 스택이 사용 가능한 실제 네트워크가 없다고 보고했습니다.The client attempted a connection, but the network stack reported that no physical network was available.
NoAuthorizationNoAuthorization 연결에 대한 인증 토큰의 획득을 시도하는 중에 클라이언트 연결이 실패했습니다.The client connection failed while attempting to acquire an authorization token for the connection.
NoResourcesNoResources 클라이언트가 연결을 시도하는 중에 일부 로컬 리소스(예: 메모리)가 부족했습니다.The client ran out of some local resource (for example, memory) while trying to make a connection.
사용할 수 없음Forbidden 서비스가 WebSocket 업그레이드 요청에 대해 HTTP 403 Forbidden 상태 코드를 반환했기 때문에 클라이언트가 서비스에 연결할 수 없었습니다.The client was unable to connect to the service because the service returned an HTTP 403 Forbidden status code on the WebSocket upgrade request.
권한 없음Unauthorized 서비스가 WebSocket 업그레이드 요청에 대해 HTTP 401 Unauthorized 상태 코드를 반환했기 때문에 클라이언트가 서비스에 연결할 수 없었습니다.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 서비스가 WebSocket 업그레이드 요청에 대해 HTTP 400 Bad Request 상태 코드를 반환했기 때문에 클라이언트가 서비스에 연결할 수 없었습니다.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 서비스가 WebSocket 업그레이드 요청에 대해 HTTP 503 Server Unavailable 상태 코드를 반환했기 때문에 클라이언트가 서비스에 연결할 수 없었습니다.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 서비스가 WebSocket 업그레이드 요청에 대해 HTTP 500 내부 오류 상태 코드를 반환했기 때문에 클라이언트가 서비스에 연결할 수 없었습니다.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.
시간 제한Timeout 클라이언트 연결 요청이 서비스에서의 응답 없이 시간 초과했습니다.The client's connection request timed out without a response from the service. 종료 필드는 클라이언트가 시간 초과하여 연결 대기를 중단한 시간을 포함합니다.The End field contains the time when the client timed out and stopped waiting for the connection.
ClientErrorClientError 클라이언트가 일부 내부 클라이언트 오류 때문에 연결을 종료했습니다.The client terminated the connection because of some internal client error.

메트릭 MicrophoneMetric Microphone

Microphone 메트릭은 모든 음성 회차에 대해 필요합니다.The Microphone metric is required for all speech turns. 이 메트릭은 오디오 입력이 음성 요청에 대해 활발하게 사용되고 있는 동안 클라이언트에 대한 시간을 측정합니다.This metric measures the time on the client during which audio input is being actively used for a speech request.

클라이언트 응용 프로그램에서 Microphone 메트릭에 대한 시작 시간 값을 기록하려면 다음 예제를 지침으로 사용하세요.Use the following examples as guidelines for recording Start time values for the Microphone metric in your client application:

  • 클라이언트 응용 프로그램이 사용자가 실제 단추를 눌러 마이크를 시작해야 한다고 요구합니다.A client application requires that a user must press a physical button to start the microphone. 단추를 누른 후 클라이언트 응용 프로그램이 마이크에서 입력을 읽고 이를 음성 서비스에 보냅니다.After the button press, the client application reads the input from the microphone and sends it to Speech Service. Microphone 메트릭에 대한 시작 값은 단추를 누른 후 마이크가 초기화되고 입력을 제공할 준비가 되었을 때의 시간을 기록합니다.The Start value for the Microphone metric records the time after the button push when the microphone is initialized and ready to provide input. Microphone 메트릭에 대한 종료 값은 클라이언트 응용 프로그램이 서비스에서 speech.endDetected 메시지를 수신한 후 서비스에 대한 오디오 스트리밍을 중단한 시간을 기록합니다.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.

  • 클라이언트 응용 프로그램은 "항상" 수신 대기하는 키워드 스포터(keyword spotter)를 사용합니다.A client application uses a keyword spotter that is "always" listening. 키워드 스포터가 말한 트리거 구를 검색한 후에만 클라이언트 응용 프로그램이 마이크에서 입력을 수집하고 이를 음성 서비스에 보냅니다.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. Microphone 메트릭에 대한 시작 값은 키워드 스포터가 클라이언트에 대해 마이크에서 오는 입력을 사용하기 시작하라고 알린 시간을 기록합니다.The Start value for the Microphone metric records the time when the keyword spotter notified the client to start using input from the microphone. Microphone 메트릭에 대한 종료 값은 클라이언트 응용 프로그램이 서비스에서 speech.endDetected 메시지를 수신한 후 서비스에 대한 오디오 스트리밍을 중단한 시간을 기록합니다.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.

  • 클라이언트 응용 프로그램은 일정한 오디오 스트림에 대한 액세스 권한을 가지고 음성 검색 모듈의 해당 오디오 스트림에 대해 무음/음성 검색을 수행합니다.A client application has access to a constant audio stream and performs silence/speech detection on that audio stream in a speech detection module. Microphone 메트릭에 대한 시작 값은 음성 검색 모듈이 클라이언트에 대해 오디오 스트림에서 오는 입력을 사용하기 시작하라고 알린 시간을 기록합니다.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. Microphone 메트릭에 대한 종료 값은 클라이언트 응용 프로그램이 서비스에서 speech.endDetected 메시지를 수신한 후 서비스에 대한 오디오 스트리밍을 중단한 시간을 기록합니다.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.

  • 클라이언트 응용 프로그램이 다회차 요청의 2회차를 처리 중인데 서비스 응답 메시지에서 2회차에 대한 입력을 수집하기 위해 마이크를 켜라는 알림을 받습니다.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. Microphone 메트릭에 대한 시작 값은 클라이언트 응용 프로그램이 마이크를 활성화하고 해당 오디오 소스에서 입력을 사용하기 시작하는 시간을 기록합니다.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. Microphone 메트릭에 대한 종료 값은 클라이언트 응용 프로그램이 서비스에서 speech.endDetected 메시지를 수신한 후 서비스에 대한 오디오 스트리밍을 중단한 시간을 기록합니다.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.

Microphone 메트릭에 대한 종료 시간은 클라이언트 응용 프로그램이 오디오 입력 스트리밍을 중단한 시간을 기록합니다.The End time value for the Microphone metric records the time when the client application stopped streaming audio input. 대부분의 상황에서 이 이벤트는 클라이언트가 서비스에서 speech.endDetected 메시지를 수신한 직후에 발생합니다.In most situations, this event occurs shortly after the client received the speech.endDetected message from the service. 클라이언트 응용 프로그램은 Microphone 메트릭에 대한 종료 시간 값이 speech.endDetected 메시지에 대한 수신 시간 값보다 이후에 발생하는지 확인하여 프로토콜을 적절히 준수했음을 확인할 수 있습니다.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. 그리고 일반적으로 한 회차의 종료와 다른 회차의 시작 간에 지연이 있으므로 클라이언트는 이후 회차에 대한 Microphone 메트릭의 시작 시간 값이 클라이언트가 마이크를 사용하여 오디오 입력을 서비스에 스트리밍하기 시작한 시간을 정확히 기록하는지 확인하여 프로토콜 적합성을 확인할 수 있습니다.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.

필드Field 설명Description 사용 현황Usage
이름Name 마이크Microphone 필수Required
시작Start 클라이언트가 마이크 또는 다른 오디오 스트림에서 오는 오디오 입력을 사용하기 시작했거나 키워드 스포터에서 트리거를 수신한 시간The time when the client started using audio input from the microphone or other audio stream or received a trigger from the keyword spotter 필수Required
End 클라이언트가 마이크 또는 오디오 스트림 사용을 중단한 시간The time when the client stopped using the microphone or audio stream 필수Required
오류Error 발생한 오류(있는 경우)에 대한 설명.A description of the error that occurred, if any. 마이크 작동이 성공적인 경우 클라이언트는 이 필드를 생략하는 것이 좋습니다.If the microphone operations were successful, clients should omit this field. 이 필드의 최대 길이는 50자입니다.The maximum length of this field is 50 characters. 오류의 경우 필수, 그렇지 않으면 생략됨Required for error cases, omitted otherwise

메트릭 ListeningTriggerMetric ListeningTrigger

ListeningTrigger 메트릭은 사용자가 음성 입력을 시작하는 작업을 실행하는 시간을 측정합니다.The ListeningTrigger metric measures the time when the user executes the action that initiates speech input. ListeningTrigger 메트릭은 선택적이지만 이 메트릭을 제공할 수 있는 클라이언트는 그렇게 하는 것이 좋습니다.The ListeningTrigger metric is optional, but clients that can provide this metric are encouraged to do so.

클라이언트 응용 프로그램에서 ListeningTrigger 메트릭에 대한 시작종료 시간 값을 기록하려면 다음 예제를 지침으로 사용하세요.Use the following examples as guidelines for recording Start and End time values for the ListeningTrigger metric in your client application.

  • 클라이언트 응용 프로그램이 사용자가 실제 단추를 눌러 마이크를 시작해야 한다고 요구합니다.A client application requires that a user must press a physical button to start the microphone. 이 메트릭에 대한 시작 값은 단추를 누른 시간을 기록합니다.The Start value for this metric records the time of the button push. 종료 값은 단추 누르기를 마친 시간을 기록합니다.The End value records the time when the button push finishes.

  • 클라이언트 응용 프로그램은 "항상" 수신 대기하는 키워드 스포터(keyword spotter)를 사용합니다.A client application uses a keyword spotter that is "always" listening. 키워드 스포터가 말한 트리거 구를 검색한 후 클라이언트 응용 프로그램은 마이크에서 입력을 읽고 이를 음성 서비스에 보냅니다.After the keyword spotter detects a spoken trigger phrase, the client application reads the input from the microphone and sends it to Speech Service. 이 메트릭에 대한 시작 값은 키워드 스포터가 나중에 트리거 구로 검색한 오디오를 수신한 시간을 기록합니다.The Start value for this metric records the time when the keyword spotter received audio that was then detected as the trigger phrase. 종료 값은 트리거 구의 마지막 단어를 사용자가 말한 시간을 기록합니다.The End value records the time when the last word of the trigger phrase was spoken by the user.

  • 클라이언트 응용 프로그램은 일정한 오디오 스트림에 대한 액세스 권한을 가지고 음성 검색 모듈의 해당 오디오 스트림에 대해 무음/음성 검색을 수행합니다.A client application has access to a constant audio stream and performs silence/speech detection on that audio stream in a speech detection module. 이 메트릭에 대한 시작 값은 음성 검색 모듈이 나중에 음성으로 검색된 오디오를 수신한 시간을 기록합니다.The Start value for this metric records the time that the speech detection module received audio that was then detected as speech. 종료 값은 음성 검색 모듈이 음성을 검색한 시간을 기록합니다.The End value records the time when the speech detection module detected speech.

  • 클라이언트 응용 프로그램이 다회차 요청의 2회차를 처리 중인데 서비스 응답 메시지에서 2회차에 대한 입력을 수집하기 위해 마이크를 켜라는 알림을 받습니다.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. 클라이언트 응용 프로그램은 이 회차에 대한 ListeningTrigger 메트릭을 포함하지 않는 것이 좋습니다.The client application should not include a ListeningTrigger metric for this turn.

필드Field 설명Description 사용 현황Usage
이름Name ListeningTriggerListeningTrigger 옵션Optional
시작Start 클라이언트 수신 대기 트리거가 시작된 시간The time when the client listening trigger started 필수Required
End 클라이언트 수신 대기 트리거가 종료된 시간The time when the client listening trigger finished 필수Required
오류Error 발생한 오류(있는 경우)에 대한 설명.A description of the error that occurred, if any. 트리거 작업이 성공한 경우 클라이언트는 이 필드를 생략하는 것이 좋습니다.If the trigger operation was successful, clients should omit this field. 이 필드의 최대 길이는 50자입니다.The maximum length of this field is 50 characters. 오류의 경우 필수, 그렇지 않으면 생략됨Required for error cases, omitted otherwise

샘플 메시지Sample message

다음 샘플은 ReceivedMessages 부분과 메트릭 부분을 모두 포함한 원격 분석 메시지를 보여줍니다.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",
    },
  ],
}

오류 처리Error handling

이 섹션에서는 응용 프로그램이 처리해야 하는 오류 메시지 및 조건의 종류를 설명합니다.This section describes the kinds of error messages and conditions that your application needs to handle.

HTTP 상태 코드HTTP status codes

WebSocket 업그레이드 요청 중에 음성 서비스는 표준 HTTP 상태 코드(예: 400 Bad Request) 등을 반환할 수 있습니다. 응용 프로그램은 이러한 오류 조건을 올바르게 처리해야 합니다.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.

권한 부여 오류Authorization errors

WebSocket 업그레이드 중에 잘못된 인증이 제공된 경우 음성 서비스는 HTTP 403 Forbidden 상태 코드를 반환합니다.If incorrect authorization is provided during the WebSocket upgrade, Speech Service returns an HTTP 403 Forbidden status code. 이 오류 코드를 트리거할 수 있는 조건:Among the conditions that can trigger this error code are:

  • 인증 헤더 누락Missing Authorization header

  • 잘못된 인증 토큰Invalid authorization token

  • 만료된 인증 토큰Expired authorization token

403 Forbidden 오류 메시지는 음성 서비스의 문제를 나타내지 않습니다.The 403 Forbidden error message doesn't indicate a problem with Speech Service. 이 오류 메시지는 클라이언트 응용 프로그램의 문제를 나타냅니다.This error message indicates a problem with the client application.

프로토콜 위반 오류Protocol violation errors

음성 서비스가 클라이언트에서 프로토콜 위반을 검색한 경우 서비스는 상태 코드 및 종료 이유를 반환한 후 WebSocket 연결을 종료합니다.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. 클라이언트 응용 프로그램은 이 정보를 사용하여 위반을 추적하고 해결할 수 있습니다.Client applications can use this information to troubleshoot and fix the violations.

잘못된 메시지 형식Incorrect message format

클라이언트가 이 사양에 나오는 올바른 형식으로 인코딩되지 않은 텍스트 또는 이진 메시지를 서비스에 보내면 서비스는 1007 잘못된 페이로드 데이터 상태 코드와 함께 연결을 닫습니다.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.

서비스는 다음 예제와 같이 다양한 이유로 이 상태 코드를 반환합니다.The service returns this status code for a variety of reasons, as shown in the following examples:

  • "잘못된 메시지 형식."Incorrect message format. 이진 메시지가 잘못된 헤더 크기 접두사를 포함합니다."Binary message has invalid header size prefix." 클라이언트가 잘못된 헤더 크기 접두사를 포함하는 이진 메시지를 보냈습니다.The client sent a binary message that has an invalid header size prefix.

  • "잘못된 메시지 형식."Incorrect message format. 이진 메시지의 헤더 크기가 잘못되었습니다."Binary message has invalid header size." 클라이언트가 잘못된 헤더 크기를 지정한 이진 메시지를 보냈습니다.The client sent a binary message that specified an invalid header size.

  • "잘못된 메시지 형식."Incorrect message format. UTF-8로 이진 메시지 헤더 디코딩이 실패했습니다."Binary message headers decoding into UTF-8 failed." 클라이언트가 UTF-8로 올바르게 인코딩되지 않은 헤더를 포함하는 이진 메시지를 보냈습니다.The client sent a binary message that contains headers that were not correctly encoded in UTF-8.

  • "잘못된 메시지 형식."Incorrect message format. 텍스트 메시지가 데이터를 포함하지 않습니다."Text message contains no data." 클라이언트가 본문 데이터를 포함하지 않은 텍스트 메시지를 보냈습니다.The client sent a text message that contains no body data.

  • "잘못된 메시지 형식."Incorrect message format. UTF-8로 텍스트 메시지 디코잉이 실패했습니다."Text message decoding into UTF-8 failed." 클라이언트가 UTF-8로 올바르게 인코딩되지 않은 텍스트 메시지를 보냈습니다.The client sent a text message that was not correctly encoded in UTF-8.

  • "잘못된 메시지 형식."Incorrect message format. 텍스트 메시지가 헤더 구분 기호를 포함하지 않습니다."Text message contains no header separator." 클라이언트가 헤더 구분 기호를 포함하지 않았거나 잘못된 헤더 구분 기호를 사용한 텍스트 메시지를 보냈습니다.The client sent a text message that did not contain a header separator or used the wrong header separator.

누락 또는 빈 헤더Missing or empty headers

클라이언트가 필수 헤더 X-RequestId 또는 경로를 포함하지 않은 메시지를 보내면 서비스는 1002 프로토콜 오류 상태 코드와 함께 연결을 닫습니다.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. 메시지는 "누락/빈 헤더.The message is "Missing/Empty header. {헤더 이름}"입니다.{Header name}."

RequestId 값RequestId values

클라이언트가 X-RequestId 헤더를 잘못된 형식으로 지정하는 메시지를 보내는 경우 서비스는 연결을 닫고 1002 프로토콜 오류 상태를 반환합니다.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. 메시지는 "잘못된 요청.The message is "Invalid request. X-RequestId 헤더 값을 대시 없는 UUID 형식으로 지정하지 않았습니다."X-RequestId header value was not specified in no-dash UUID format."

오디오 인코딩 오류Audio encoding errors

클라이언트가 회차를 시작하는 오디오 청크를 보내는데 오디오 형식 또는 인코딩이 필요한 사양을 준수하지 않는 경우 서비스는 연결을 닫고 1007 잘못된 페이로드 데이터 상태 코드를 반환합니다.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. 이 메시지는 형식 인코딩 오류 원본을 나타냅니다.The message indicates the format encoding error source.

RequestId 다시 사용RequestId reuse

회차가 종료된 후 클라이언트가 해당 회차에서 요청 식별자를 다시 사용하는 메시지를 보내면 서비스는 연결을 닫고 1002 프로토콜 오류 상태 코드를 반환합니다.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. 메시지는 "잘못된 요청.The message is "Invalid request. 요청 식별자의 다시 사용은 허용되지 않습니다."Reuse of request identifiers is not allowed."

연결 실패 원격 분석Connection failure telemetry

가장 좋은 예상 사용자 경험을 확보하려면 클라이언트는 원격 분석 메시지를 사용하여 연결 내의 중요 검사점에 대한 타임스탬프를 음성 서비스에 알려야 합니다.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. 클라이언트가 시도했지만 실패한 연결을 서비스에 알리는 것도 마찬가지로 중요합니다.It's equally important that clients inform the service of connections that were attempted but failed.

실패한 각 연결 시도에 대해 클라이언트는 고유한 X-RequestId 헤더 값을 사용하여 원격 분석 메시지를 만듭니다.For each connection attempt that failed, clients create a telemetry message with a unique X-RequestId header value. 클라이언트는 연결을 설정할 수 없으므로 JSON 본문의 ReceivedMessages 필드는 생략할 수 있습니다.Because the client was unable to establish a connection, the ReceivedMessages field in the JSON body can be omitted. 메트릭 필드에 Connection 항목만 포함하면 됩니다.Only the Connection entry in the Metrics field is included. 이 항목은 발견된 오류 조건뿐만 아니라 시작 및 종료 타임스탬프도 포함합니다.This entry includes the start and end time stamps as well as the error condition that was encountered.

원격 분석의 연결 다시 시도Connection retries in telemetry

클라이언트는 연결 시도를 트리거하는 이벤트에 의해 다시 시도여러 번 연결 시도와 구분할 수 있습니다.Clients should distinguish retries from multiple connection attempts by the event that triggers the connection attempt. 사용자 입력 없이 프로그램에 의해 수행된 연결 시도는 다시 시도입니다.Connection attempts that are carried out programmatically without any user input are retries. 사용자 입력에 응답하여 수행하는 여러 번의 연결 시도는 여러 번 연결 시도입니다.Multiple connection attempts that are carried out in response to user input are multiple connection attempts. 클라이언트가 각 사용자 트리거 연결 시도에 대해 고유한 X-RequestId원격 분석 메시지를 제공합니다.Clients give each user-triggered connection attempt a unique X-RequestId and telemetry message. 클라이언트가 프로그램에 의한 다시 시도에 대해 X-RequestId를 다시 사용합니다.Clients reuse the X-RequestId for programmatic retries. 단일 연결 시도에 대해 여러 번 다시 시도가 이루어진 경우 각 다시 시도는 원격 분석 메시지에 Connection 항목으로 포함됩니다.If multiple retries were made for a single connection attempt, each retry attempt is included as a Connection entry in the telemetry message.

예를 들어 사용자가 연결을 시작하는 키워드 트리거를 말하고 첫 번째 연결 시도가 DNS 오류 때문에 실패한다고 가정해 보겠습니다.For example, suppose a user speaks the keyword trigger to start a connection and the first connection attempt fails because of DNS errors. 그러나 클라이언트에서 프로그램에 의해 수행한 두 번째 시도는 성공합니다.However, a second attempt that is made programmatically by the client succeeds. 클라이언트가 사용자의 추가 입력을 요구하지 않고 연결을 다시 시도했으므로 클라이언트는 Connection 항목 여러 개와 함께 단일 원격 분석 메시지를 사용하여 연결을 설명합니다.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.

또 다른 예로, 사용자가 연결을 시작하는 키워드 트리거를 말하는데 이 연결 시도가 세 번 다시 시도 후 실패한다고 가정해 보겠습니다.As another example, suppose a user speaks the keyword trigger to start a connection and this connection attempt fails after three retries. 그러면 클라이언트는 포기하고 서비스에 연결 시도를 중단하고 사용자에게 무언가 잘못되었다고 알립니다.The client then gives up, stops attempting to connect to the service, and informs the user that something went wrong. 그러면 사용자가 키워드 트리거를 다시 말합니다.The user then speaks the keyword trigger again. 이번에는 클라이언트가 서비스에 연결한다고 가정해 보겠습니다.This time, suppose the client connects to the service. 연결 후 클라이언트는 즉시 연결 실패를 설명하는 Connection 항목 세 개를 포함하는 원격 분석 메시지를 서비스에 보냅니다.After connecting, the client immediately sends a telemetry message to the service that contains three Connection entries that describe the connection failures. turn.end 메시지를 수신한 후 클라이언트는 연결 성공을 설명하는 또 다른 원격 분석 메시지를 보냅니다.After receiving the turn.end message, the client sends another telemetry message that describes the successful connection.

오류 메시지 참조Error message reference

HTTP 상태 코드HTTP status codes

HTTP 상태 코드HTTP status code 설명Description 문제 해결Troubleshooting
400 잘못된 요청400 Bad Request 클라이언트가 잘못된 WebSocket 연결 요청을 보냈습니다.The client sent a WebSocket connection request that was incorrect. 모든 필수 매개 변수 및 HTTP 헤더를 제공했는지 그리고 값이 올바른지 확인합니다.Check that you supplied all the required parameters and HTTP headers and that the values are correct.
401 권한 없음401 Unauthorized 클라이언트가 필수 권한 정보를 포함하지 않았습니다.The client did not include the required authorization information. WebSocket 연결의 권한 헤더를 보냈는지 확인합니다.Check that you're sending the Authorization header in the WebSocket connection.
403 사용할 수 없음403 Forbidden 클라이언트가 권한 정보를 보냈지만 해당 정보가 잘못되었습니다.The client sent authorization information, but it was invalid. 권한 헤더에 만료되거나 잘못된 값을 보내고 있지 않은지 확인합니다.Check that you're not sending an expired or invalid value in the Authorization header.
404 찾을 수 없음404 Not Found 클라이언트가 지원되지 않는 URL 경로에 액세스를 시도했습니다.The client attempted to access a URL path that is not supported. WebSocket 연결에 올바른 URL을 사용하고 있는지 확인합니다.Check that you're using the correct URL for the WebSocket connection.
500 서버 오류500 Server Error 서버가 내부 오류를 발견했으며 요청을 수행할 수 없습니다.The service encountered an internal error and could not satisfy the request. 대부분의 경우 이 오류는 과도적입니다.In most cases, this error is transient. 요청을 다시 시도하십시오.Retry the request.
503 서비스를 사용할 수 없음503 Service Unavailable 서비스가 요청을 처리할 수 없었습니다.The service was unavailable to handle the request. 대부분의 경우 이 오류는 과도적입니다.In most cases, this error is transient. 요청을 다시 시도하십시오.Retry the request.

WebSocket 오류 코드WebSocket error codes

WebSocketsStatus 코드WebSocketsStatus code 설명Description 문제 해결Troubleshooting
1000 기본 닫기1000 Normal Closure 서비스가 WebSocket 연결을 오류 없이 닫았습니다.The service closed the WebSocket connection without an error. WebSocket 닫기가 예기치 않은 경우 설명서를 다시 읽고 서비스가 WebSocket 연결을 종료할 수 있는 방법 및 경우를 확인하세요.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 프로토콜 오류1002 Protocol Error 클라이언트가 프로토콜 요구 사항을 준수하지 않았습니다.The client failed to adhere to protocol requirements. 프로토콜 설명서를 이해하고 있는지 그리고 요구 사항에 대해 명확히 알고 있는지 확인합니다.Ensure that you understand the protocol documentation and are clear about the requirements. 오류 이유에 대한 이전 설명서를 읽고 프로토콜 요구 사항을 위반하지 않는지 확인합니다.Read the previous documentation about error reasons to see if you're violating protocol requirements.
1007 잘못된 페이로드 데이터1007 Invalid Payload Data 클라이언트가 프로토콜 메시지에 잘못된 페이로드를 보냈습니다.The client sent an invalid payload in a protocol message. 서비스에 보낸 마지막 메시지에 오류가 있는지 확인합니다.Check the last message that you sent to the service for errors. 페이로드 오류에 관한 이전 설명서를 읽습니다.Read the previous documentation about payload errors.
1011 서버 오류1011 Server Error 서버가 내부 오류를 발견했으며 요청을 수행할 수 없습니다.The service encountered an internal error and could not satisfy the request. 대부분의 경우 이 오류는 과도적입니다.In most cases, this error is transient. 요청을 다시 시도하십시오.Retry the request.

WebSocket 기반 음성 서비스 프로토콜의 구현인 JavaScript SDK를 참조하세요.See a JavaScript SDK that is an implementation of the WebSocket-based Speech Service protocol.