TVS 设备可以通过 HTTP/1.1 与天猫精灵服务端进行通讯，请求称为event，响应称为diretive，端状态称为context。
使用 HTTP/2.0 作为传输协议的接口服务正在开发中，文档见：https://doc-bot.tmall.com/docs/doc.htm?treeId=566&articleId=114947&docType=1
目前使用TVS HTTP1.1
测试联调环境 :g1-aicloud.alibaba.com
稳定测试环境 :gdev-aicloud.alibaba.com
线上环境 :g-aicloud.alibaba.com
TVS协议基于HTTP1.1的请求和响应，在Message Body中传递JSON消息，必要时一个HTTP请求/响应中会有多个Message Body（即multipart的HTTP请求/响应），除了JSON消息外，可能附带额外的附件数据（如音频数据）。设备端请求中的JSON消息由端状态(context)和事件(event)两个部分组成，服务端响应的JSON消息由指令(directive)一个部分组成。
所有的 directive / event / context 都遵循同一种格式。
以Recognize指令为例，格式如下：
{
"header":{
"namespace":"SpeechRecognizer",
"name":"Recognize",
"messageId":"mid_0001",
"dialogRequestId":"did_0001"
},
"payload":{
"profile":"NEAR_FIELD",
"format":"AUDIO_L16_RATE_16000_CHANNELS_1",
"initiator":{
"type":"TAP"
}
}
}
请求方式使用POST。
1、采用Multipart方式，请求体可以携带JSON文本数据，也可以携带二进制数据：
Content-Type: multipart/form-data
2、event的JSON数据参数设置：
Content-Disposition: form-data; name="metadata" Content-Type: application/json; charset=UTF-8
3、携带的音频参数设置：
Content-Disposition: form-data; name="audio" Content-Type: application/octet-stream
POST https://g1-aicloud.alibaba.com/tvs/v1/events HTTP/1.1
Content-Type: multipart/form-data; boundary=this-is-a-boundary
Content-Length: 1024
Authorization: Bearer token_001
--this-is-a-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{
"context": [
{
"header": {
"namespace": "AudioPlayer",
"name": "PlaybackState"
},
"payload": {
"token": "play_token_0001",
"offsetInMilliseconds": "30000",
"playerActivity": "PLAYING"
}
},
{
"header": {
"namespace": "SpeechSynthesizer",
"name": "SpeechState"
},
"payload": {
"token": "speech_token_0001",
"offsetInMilliseconds": 0,
"playerActivity": "FINISHED"
}
}
],
"event": {
"header": {
"namespace": "SpeechRecognizer",
"name": "Recognize",
"messageId": "mid_123",
"dialogRequestId": "did_123"
},
"payload": {
"profile": "NEAR_FIELD",
"format": "AUDIO_L16_RATE_16000_CHANNELS_1",
"initiator":{
"type":"TAP"
}
}
}
}
--this-is-a-boundary
Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream
{{binary audio attachment}}
--this-is-a-boundary--
设备端向服务端上报事件的JSON消息为application/json格式，JSON数据分为2部分：
* context
* 端状态：服务端在处理某些事件时，需要了解在请求当时设备端各模块所处的状态。比如端上是否正在播放音乐，是否正在播报等等。
* 只有部分事件上报需要附带设备端状态，一个事件是否需要携带设备端状态，需要携带哪些状态，详见事件的说明文档。
* event
* 事件：设备端上发生任何事情，需要通过事件来通知服务端。比如开始播放音乐了，音乐播放结束了，闹铃响了，用户开始了语音请求等等，都对应一个个事件。
有些事件的上报，需要在请求中附带额外的二进制附件。比如用户开始语音请求，设备端开始收音是要上报Recognize事件，此时请求中需要附带录制的语音数据。
在json消息之后，用boundary隔开，可以附上下一个HTTP消息，此消息为application/octet-stream格式，即二进制格式，消息内容为所需要附上的二进制数据。
响应的指令数据也以Multipart方式返回。如果出现异常，则以application/json方式返回。
1、采用Multipart方式，响应体携带JSON文本数据，同时可能携带二进制数据：
Content-Type: multipart/related
2、directive的JSON数据参数设置：
Content-Type: application/json; charset=UTF-8
3、携带的音频参数设置：
Content-Type: application/octet-stream
HTTP1.1 200 OK
Content-Type: multipart/related; boundary=this-is-a-boundary
Content-Length: 2048
--this-is-a-boundary
Content-Type: application/json; charset=UTF-8
{
"directive": {
"header": {
"namespace": "SpeechSynthesizer",
"name": "Speak",
"messageId": "mid_123",
"dialogRequestId": "did_123"
},
"payload": {
"url": "cid:1234",
"format": "AUDIO_MPEG",
"token": "tts_token_0001"
}
}
}
--this-is-a-boundary
Content-Type: application/octet-stream
Content-ID: 1234
{{binary audio attachment}}
--this-is-a-boundary
Content-Type: application/json; charset=UTF-8
{
"directive": {
"header": {
"namespace": "SpeechRecognizer",
"name": "ExpectSpeech",
"messageId": "mid_123",
"dialogRequestId": "did_123"
},
"payload": {
"timeoutInMilliseconds": 8000
}
}
}
--this-is-a-boundary--
服务端响应设备端的JSON消息为application/json格式：
* diretive
* 指令：服务端下发给设备端的指令，需要设备端执行。比如播放一个语音，设置一个闹钟，播放一个音乐等等
有些指令需要附带额外的附件。比如播报需要附带播报语音，屏幕展示指令需要附带所需要展示的内容。此时，附件作为JSON消息之后下一个HTTP消息返回，消息Header中的Content-ID为附件的ID，一般对应指令中的cid:<1234>。附带的播报语音通过name=“audio”与其他类型附件区分开，端上可以先行解码音频。
