bowen liu
ex
Fork of
mbed-os-example-mbed5-blinky
by 
mbed-os-examples
Diff: dumi_doc-master/doc/BOTAPI_README.md
- Revision:
- 49:b9eb462f36a9
- Parent:
- 48:c7ee67edcf1d
- Child:
- 50:9ecaa144d1f3
--- a/dumi_doc-master/doc/BOTAPI_README.md Tue Jul 18 16:56:22 2017 +0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,515 +0,0 @@
-# 度秘开放平台-BotApi接口说明
-
-
-## Table of Contents
-
-
- * [度秘开放平台-BotApi接口说明](#度秘开放平台-botapi接口说明)
- * [Table of Contents](#table-of-contents)
- * [文档目的](#文档目的)
- * [整体格式说明](#整体格式说明)
- * [架构描述](#架构描述)
- * [交互模式说明（confirm）](#交互模式说明confirm)
- * [请求格式](#请求格式)
- * [请求字段中，.supported_content_type字段的解释](#请求字段中supported_content_type字段的解释)
- * [请求字段中，.msg.device_data字段的解释](#请求字段中msgdevice_data字段的解释)
- * [正常返回格式](#正常返回格式)
- * [和策略相关的字段](#和策略相关的字段)
- * [正常返回的字段中，content字段的解释](#正常返回的字段中content字段的解释)
-
-
-## 文档目的
-
-目的：
- * 为了让能够让度秘内部的rd开发下游bot
- * 为了给未来的bot开放平台做准备
-
-整理度秘系统和bot之间的接口
-
-## 整体格式说明
-
-### 架构描述
-
-
-
-这篇文档整理的是下游bot的输入输出接口
-
-
-## 交互模式说明（confirm）
-
-
-
- * 之所以有confirm请求，是因为us会把同一个请求发给多个bot，然后挑选较好的一个。bot返回的结果，有可能不被使用
- * 按bot对请求的处理有无副作用，分为幂等请求和非幂等请求
- * 幂等请求如：
- * 通用信息
- * 天气
- * 非幂等请求如：
- * 提醒（bot会为用户创建提醒）
- * 打车（bot会帮用户叫车）
-
-### 请求格式
-
-以下是现有的协议
-
-```javascript
-{
- //最终返回值里的bot_id，相当于以前的source_type，在中控配置。以后bot_id不再由bot返回的source_type决定
- "bot_name": "ai.dueros.bot.information_general",
- "launch":true,//标识是第一次open这个bot的请求，默认是false
- "end_session":true,//标识是第一次open这个bot的请求，默认是false
- "user_id": "3101", ///用户id，如果非登录用户会改成
- "query": "张岩", //原始query
- "version": 1, //版本号
- "msg": { ///老的协议格式，原始的msg，不知为何result_content是个字符串
- "id": "1454319650_5906bphzi",
- "debug": 1,
- "mode": 0,
- "operation_system": "ios",
- "app_ver": "1.4.0",
- "from": "ios",
- "ctime": 1454319650,
- "type": "user",
- "query_type": "1",
- "device_data":"{}",//target_device_id,device_interface, device_event, device_status 三个字段的打包json，因为现在idl定义不了这三个字段的结构
- "result_list": [
- {
- "result_confidence": 100,
- "result_content": "{\"answer\":\"张岩\"}\n",
- "result_type": "txt",
- "source_type": ""
- }
- ],
- "request_uid": "1463803763",
- "client_msg_id": "20674",
- "request_from": "0",
- "request_type": "0",
- "sample_name": "bear_brain_wireless"
- },
- "log_id": "5969bdd5126d493387a6b127d8c45ce7", //串起整个请求的id
- "request_type": "dumi", //现在的策略分支
- "params": {
- "loc": "%7B%22crd%22%3A%2212944500.486221_4845580.669330_200%22%2C%22city%22%3A%22%5Cu5317%5Cu4eac%5Cu5e02%22%2C%22addr%22%3A%22%5Cu5317%5Cu4eac%5Cu5e02%5Cu6d77%5Cu6dc0%5Cu533a%5Cu8f6f%5Cu4ef6%5Cu56ed%5Cu897f%5Cu4e09%5Cu8def%22%7D",//其实是地址信息，但有了location之后这个已经没用了
- "cip": "1.2.2.1",//客户端ip
- "bear_params": {
- "nlu_response": "{\"analysis\":{},\"parsed_text\":\"张 岩\",\"raw_text\":\"张岩\",\"results\":[{\"demand\":0,\"domain\":\"universal_search\",\"intent\":\"search\",\"object\":{},\"pushleft_switch\":\"0\",\"score\":1,\"str_result_content\":{},\"str_result_type\":\"\"}],\"sugs\":\"张岩\",\"sugs_types\":\"PAT_EC\"}\n"
- },
- "client_from": "NA",
- "intervene_from": "na",
- "sc_response": "{}"
- },
- //完整的地址信息
- "location": {
- "la": 40.0433,
- "lo": 116.269,
- "bd_la": 40.0508,
- "bd_lo": 116.281,
- "mi_la": 4845580,
- "mi_lo": 12944500,
- "address": "北京市海淀区软件园西三路",
- "city": "北京市",
- "city_code": 131,
- "country": "中国",
- "country_code": 0,
- "direction": "",
- "distance": "",
- "district": "海淀区",
- "province": "北京市",
- "street": "软件园西三路",
- "street_number": "",
- "cip": "1.2.2.1",
- "cip_type": "mockbycity",
- "location_type": "real",
- "sematic_description": "百度科技园内"
- },
- "page_cnt": 10,
- "page_num": 1,
- //没有多轮就可以忽略session字段
-/*
- "sessions": [
- {
- "action": "get",
- "type": "string",
- "name": "phone",
- "key": "3101",
- "list_sessions": [],
- "list_sessions_str": [
- "{\"SendSMS\":{\"intent\":\"SendSMS\",\"score\":42,\"objects\":[{\"key\":\"MSMOmit\",\"value\":\"\\u8bf4\",\"score\":1},{\"key\":\"_MSMOmit\",\"value\":\"\\u8bf4\",\"score\":1},{\"key\":\"MSGBody\",\"value\":\"\\u4e0d\\u56de\\u5bb6\\u5403\\u996d\",\"score\":1},{\"key\":\"_MSGBody\",\"value\":\"\\u4e0d\\u56de\\u5bb6\\u5403\\u996d\",\"score\":1},{\"key\":\"SendKey\",\"value\":\"\\u53d1\",\"score\":1},{\"key\":\"_SendKey\",\"value\":\"\\u53d1\",\"score\":1},{\"key\":\"WantKey\",\"value\":\"\\u6211\\u8981\",\"score\":1},{\"key\":\"_WantKey\",\"value\":\"\\u6211\\u8981\",\"score\":1}]}}"
- ],
- "hash_sessions": []
- }
- ],
-*/
- "safe_mode":false, //儿童模式开关，true为打开状态，fasle为关闭状态
- "bot_sessions": [
- {
- "action": "get",
- "type": "string",
- "key": "3101",
- "list_sessions": [],
- "list_sessions_str": [
- "{\"SendSMS\":{\"intent\":\"SendSMS\",\"score\":42,\"objects\":[{\"key\":\"MSMOmit\",\"value\":\"\\u8bf4\",\"score\":1},{\"key\":\"_MSMOmit\",\"value\":\"\\u8bf4\",\"score\":1},{\"key\":\"MSGBody\",\"value\":\"\\u4e0d\\u56de\\u5bb6\\u5403\\u996d\",\"score\":1},{\"key\":\"_MSGBody\",\"value\":\"\\u4e0d\\u56de\\u5bb6\\u5403\\u996d\",\"score\":1},{\"key\":\"SendKey\",\"value\":\"\\u53d1\",\"score\":1},{\"key\":\"_SendKey\",\"value\":\"\\u53d1\",\"score\":1},{\"key\":\"WantKey\",\"value\":\"\\u6211\\u8981\",\"score\":1},{\"key\":\"_WantKey\",\"value\":\"\\u6211\\u8981\",\"score\":1}]}}"
- ],
- "hash_sessions": []
- }
- ],
- //////////上次返回new_bot_session, 这次也会用new_bot_session带下来，这是新的session机制，协议简单点 @zhanggang
- "new_bot_session" :{
- "value":"{\"empty\":true}" //需要写入到session中的内容
- },
- //如果是百度登录用户的话，会有信息
- "user_info": {
- "user_id": "",
- "extra": []
- },
- "data": {
- "status": 0,
- "msg": "OK",
- "da_query_info": [ //现在的qu结果，数组，type是服务（第二级的type是domain，第三级result_list里的type是intent）
- {
- "query": "张岩",
- "type": "qu",
- "result_list": [
- {
- "type": "query",
- "score": 0,
- "result_list": []
- },
- {
- "type": "session",
- "score": 0,
- "result_list": []
- }
- ]
- }
- ],
- "params": [ //其他几个qu结果的原始数据，一般情况都不用看
- {
- "key": "nlu_responce",
- "value": "{\"analysis\":{},\"parsed_text\":\"张 岩\",\"raw_text\":\"张岩\",\"results\":[{\"demand\":0,\"domain\":\"universal_search\",\"intent\":\"search\",\"object\":{},\"pushleft_switch\":\"0\",\"score\":1,\"str_result_content\":{},\"str_result_type\":\"\"}],\"sugs\":\"张岩\",\"sugs_types\":\"PAT_EC\"}\n"
- },
- {
- "key": "qu_responce",
- "value": "{\"err_no\":0, \"result\":[{\"normal\":{}, \"qu\":{\"query_voice\":{\"res\":[{\"domain\":\"phone\", \"intent\":\"F->Phone->Context\", \"score\":1, \"objects\":[{\"key\":\"CallTarget\", \"value\":\"张岩\", \"score\":1}, {\"key\":\"_CallTarget\", \"value\":\"张岩\", \"score\":1}], \"reduce_tree_info\":\"(query(F->Phone->Context(CallTarget(Person 张岩))))\"}, {\"domain\":\"UNDEFINED\", \"intent\":\"F->alarmlocation\", \"score\":5502, \"objects\":[{\"key\":\"Route\", \"value\":\"张岩\", \"score\":1}, {\"key\":\"_Route\", \"value\":\"张岩\", \"score\":1}], \"reduce_tree_info\":\"(query(F->alarmlocation(Route(F->route(Arrival(F->arrival(ARRIVAL(VILLAGE 张岩))))))))\"}, {\"domain\":\"UNDEFINED\", \"intent\":\"F->alarmlocation\", \"score\":5503, \"objects\":[{\"key\":\"Route\", \"value\":\"张岩\", \"score\":1}, {\"key\":\"_Route\", \"value\":\"张岩\", \"score\":1}], \"reduce_tree_info\":\"(query(F->alarmlocation(Route(F->route(Arrival(F->arrival(ARRIVAL(POI(VILLAGE 张岩)))))))))\"}]}}, \"queryId\":1}]}"
- }
- ]
- },
- //数组每一个元素为一类资源类型;audio(mp3(16000,128000),aac)代表音频格式只支持mp3和aac，其中mp3只支持码率在16k~128k之间
- "supported_content_type":["audio(mp3(16000,128000),aac)","video","image","webview","speech"],
- //keep_silence=1的时候，中控不给客户端返回tts或者显示的信息，但会做写session等处理
- "keep_silence":1
-}
-
-
-
-```
-
-#### 请求字段中，.supported_content_type字段的解释
-表示了端支持的内容类型，bot应该召回端支持的内容类型，**不召回**端不支持的内容
- * audio
- * video
- * image
- * webview
- * speech
-
-#### 请求字段中，.msg.device_data字段的解释
-
-.msg.device_data字段，是一个json_encode后的字符串
-
-会把[请求里的几个字段](api/request.md#客户端能力相关device_interface-device_event-device_status)映射过来
-
-下面是这个json展开后的结构
-```javascript
-{
-
- "target_device_id":"xxxxxx",
- "device_interface":{
- "Alerts":{},
- "AudioPlayer":{
- //"no_pause":1,
- //"no_seek":1,
- },
- "PlaybackController":{},
- "Speaker":{},
- "Settings":{},
- "System":{}
- },
- "device_event":{
- //query_type==30 的时候才会有 device_event
- "header": {
- "namespace": "AudioPlayer",
- "name": "PlaybackStarted",
- "message_id": "message_id-1344"
- },
- "payload": {
- //AudioPlayer里可能出现的payload
- "token": "156",
- "offset_ms": 10000,
- //Speaker里可能出现的payload
- "volume": 1,
- //SpeechSynthesizer可能出现的payload
- "token": "156",
- "type": "{{Text/SSML}}",
- "content": ["xxxx1", "xxxx2"],
- "speak_behavior": "REPLACE_ALL",
- "should_get_next_speech": true
- }
- },
- "device_status":{
- "AudioPlayer":{
- "token":"xxx",//正在播放的音频流id
- "offset_ms":20000,//播放到多少ms了
- "player_activity":"IDLE PAUSED PLAYING BUFFER_UNDERRUN FINISHED STOPPED"
- },
- }
-}
-```
-
-
-### 正常返回格式
-
-
-```javascript
-
-{
- "status": 0,
- "msg": "ok",
- "data": {
- "result_list": [
- {
- //内容质量得分，可选
- "confidence": 100,
- //bot的id，必须有
- "source_type": "phone",
- //统计字段，可以用来给bot的返回值分类，可以不传
- "source_sub_type": "contact",
- //真正拼的消息其实是这个content字段，现在对外返回的resource、directives等字段都放在这个里面，和result_list平级，下一段详细讲这个content
- "content": "{\"result_list\":[{\"result_content\":{\"answer\":\"<SYSTEM-NAME>为你查看联系人“张岩”\"},\"result_type\":\"txt\",\"source_type\":\"phone\",\"source_sub_type\":\"contact\",\"voice\":\"<SYSTEM-NAME>为你查看联系人“张岩”\"}],\"type\":\"server\",\"generator\":\"phone_function\",\"user_id\":\"3101\"}",
- //会用于us排序的字段，为了让排序策略起作用，尽可能传一下
- "stategy_middle_data": {
- "bot_intent":{
- "query":"raw query" ////请求的query，如果有bot_intent，这个就必须有
- "query_score":100 ////和需求的匹配度,可选
- },
- "raw_answer": [
- {
- "title": "",
- "subtitle": "",
- "answer": "<SYSTEM-NAME>为你查看联系人“张岩”",
- "url": ""
- }
- ]
- }
- }
- ],
- //页码，总页数，总结果数，都可以不传
- "page_num": 1,
- "page_cnt": 1,
- "result_num": 1,
- ////和请求中的da_query_info格式一致，表示下游bot实际使用的da_query_info（也可以说就是把请求中不使用的），可以为空
- "service_query_info": [
- {
- "query": "张岩",
- "type": "phone",
- "result_list": [
- {
- "type": "phone",
- "score": 100,
- "result_list": [
- {
- "type": "contact",
- "score": 0,
- "content": "",
- "result_list": [
- {
- "key": "name_for_view",
- "type": "text",
- "score": 0,
- "value": [
- {
- "name": "name_for_view",
- "value": "张岩"
- }
- ]
- },
- {
- "key": "pinyin_for_view",
- "type": "text",
- "score": 0,
- "value": [
- {
- "name": "pinyin_for_view",
- "value": "zhang+yan"
- }
- ]
- },
- {
- "key": "action_type",
- "type": "text",
- "score": 0,
- "value": [
- {
- "name": "action_type",
- "value": "1"
- }
- ]
- },
- {
- "key": "show_query",
- "type": "text",
- "score": 0,
- "value": [
- {
- "name": "show_query",
- "value": "张岩"
- }
- ]
- }
- ]
- }
- ]
- }
- ]
- }
- ],
- "server_query_intent": "\"\""
- },
- /////如果不是多轮，此字段可没有
- ///sessions字段已经废弃，现在是bot_sessions和decision_sessions, 不再有name
-/*
- "sessions": [
- {
- "status": 0,
- "msg": "ok",
- "action": "set",
- "type": "string",
- "name": "phone",
- "key": "3101",
- "list_sessions_str": [
- "{\"empty\":true}"
- ]
- }
- ]
-*/
- "bot_sessions": [
- {
- "status": 0,
- "msg": "ok",
- "action": "set",
- "type": "string",
- "key": "3101",
- "list_sessions_str": [
- "{\"empty\":true}"
- ]
- }
- ],
- //////////用new_bot_session的话，请求也会带new_bot_session下来，这是新的session机制，协议简单点 @zhanggang
- "new_bot_session" :{
- "value":"{\"empty\":true}",//需要写入到session中的内容
- "expire":0,//这个Session的过期时间
- },
- ///////////////////////////////
- "decision_sessions": [
- {
- "status": 0,
- "msg": "ok",
- "action": "set",
- "type": "string",
- "key": "3101",
- "list_sessions_str": [
- "{\"empty\":true}"
- ]
- }
- ],
- //可选，默认为true，如果为false，客户端应该立即进入收听用户query的状态，不用重新唤醒
- "should_end_session":false,
-
-}
-
-```
-
-所以，极简单情况下（没有多轮，没有使用da结果），bot可以只返回以下结构
-```javascript
-{
- "status": 0,
- "msg": "ok",
- "data": {
- "result_list": [
- {
- //内容质量得分，可选
- "confidence": 100,
- //bot的id，必须有
- "source_type": "phone",
- //真正拼的消息其实是这个content字段，现在对外返回的resource、directives等字段都放在这个里面，和result_list平级，下一段详细讲这个content
- "content": "{\"result_list\":[{\"result_content\":{\"answer\":\"<SYSTEM-NAME>为你查看联系人“张岩”\"},\"result_type\":\"txt\",\"source_type\":\"phone\",\"source_sub_type\":\"contact\",\"voice\":\"<SYSTEM-NAME>为你查看联系人“张岩”\"}],\"type\":\"server\",\"generator\":\"phone_function\",\"user_id\":\"3101\"}",
- //会用于us排序的字段，为了让排序策略起作用，尽可能传一下
- "stategy_middle_data": {
- "bot_intent":{
- "query":"raw query" ////请求的query，如果有bot_intent，这个就必须有
- "query_score":100 ////和需求的匹配度,可选
- },
- "raw_answer": [
- {
- "title": "",
- "subtitle": "",
- "answer": "<SYSTEM-NAME>为你查看联系人“张岩”",
- "url": ""
- }
- ]
- }
- }
- ]
- },
- //可选，默认为true，如果为false，客户端应该立即进入收听用户query的状态，不用重新唤醒
- "should_end_session":false
-}
-
-```
-
-#### 和策略相关的字段
- * data.result_list[].stategy_middle_data.bot_intent.query_score，取值0-100 ，标识内容的质量
- * data.result_list[].confidence，取值0-100 ，标识和query的匹配度
-
-#### 正常返回的字段中，content字段的解释
-
-.data.result_list[].content字段，是一个json_encode后的字符串
-
-下面是这个json展开后的结构
-
-内部可以加入新协议的字段，如resource、speech、views等等，但一定要有一个result_list。
- * 如果有传views、speech、resource等字段，result_list的内容可以随意，不会在新的输出接口中生效
- * 如果不传views、speech、resource等字段，api2.0接口输出时，会把result_list按一定规则转换成这些新字段
- * views、speech、resource等字段的数据结构，参见[度秘api2.0文档](api/response.md)
- * 老的result_list内部的详细格式，可参考[度秘api1.0文档](http://agroup.baidu.com/duer/md/article/17301)，主要是定义了result_list可以放的卡片格式
-
-```javascript
-{
- //result_list是老的结构，现在无论如何要传一个
- "result_list": [
- {
- "result_content": {
- "answer": "<SYSTEM-NAME>为你查看联系人“张岩”"
- },
- "result_type": "txt",
- "source_type": "phone",
- //可选，用于统计
- "source_sub_type": "contact",
- //语音播报的内容，可选
- "voice": "<SYSTEM-NAME>为你查看联系人“张岩”"
- }
- ],
- //可选，内容见api2.0接口
- views:[],
- //可选，内容见api2.0接口
- resource:{},
- //可选，内容见api2.0接口
- speech:{},
- //可选，内容见api2.0接口
- directives:{},
- //可选，内容见api2.0接口
- hint:[],
- //可选，最好是传下来的nlu数据里选一个返回，内容见api2.0接口
- nlu:{},
- "type": "server"
-}
-```