bowen liu / Mbed OS mbed-os-example-blinky

ex

Fork of mbed-os-example-mbed5-blinky by mbed-os-examples

dumi_doc-master/doc/BOTAPI_README.md@44:c1d8923072ba, 2017-07-18 (annotated)

Committer:
TMBOY
Date:
Tue Jul 18 16:27:22 2017 +0800
Revision:
44:c1d8923072ba
?

Who changed what in which revision?

UserRevisionLine numberNew contents of line
TMBOY 44:c1d8923072ba 1 # 度秘开放平台-BotApi接口说明
TMBOY 44:c1d8923072ba 2
TMBOY 44:c1d8923072ba 3
TMBOY 44:c1d8923072ba 4 ## Table of Contents
TMBOY 44:c1d8923072ba 5
TMBOY 44:c1d8923072ba 6
TMBOY 44:c1d8923072ba 7 * [度秘开放平台-BotApi接口说明](#度秘开放平台-botapi接口说明)
TMBOY 44:c1d8923072ba 8 * [Table of Contents](#table-of-contents)
TMBOY 44:c1d8923072ba 9 * [文档目的](#文档目的)
TMBOY 44:c1d8923072ba 10 * [整体格式说明](#整体格式说明)
TMBOY 44:c1d8923072ba 11 * [架构描述](#架构描述)
TMBOY 44:c1d8923072ba 12 * [交互模式说明（confirm）](#交互模式说明confirm)
TMBOY 44:c1d8923072ba 13 * [请求格式](#请求格式)
TMBOY 44:c1d8923072ba 14 * [请求字段中，.supported_content_type字段的解释](#请求字段中supported_content_type字段的解释)
TMBOY 44:c1d8923072ba 15 * [请求字段中，.msg.device_data字段的解释](#请求字段中msgdevice_data字段的解释)
TMBOY 44:c1d8923072ba 16 * [正常返回格式](#正常返回格式)
TMBOY 44:c1d8923072ba 17 * [和策略相关的字段](#和策略相关的字段)
TMBOY 44:c1d8923072ba 18 * [正常返回的字段中，content字段的解释](#正常返回的字段中content字段的解释)
TMBOY 44:c1d8923072ba 19
TMBOY 44:c1d8923072ba 20
TMBOY 44:c1d8923072ba 21 ## 文档目的
TMBOY 44:c1d8923072ba 22
TMBOY 44:c1d8923072ba 23 目的：
TMBOY 44:c1d8923072ba 24 * 为了让能够让度秘内部的rd开发下游bot
TMBOY 44:c1d8923072ba 25 * 为了给未来的bot开放平台做准备
TMBOY 44:c1d8923072ba 26
TMBOY 44:c1d8923072ba 27 整理度秘系统和bot之间的接口
TMBOY 44:c1d8923072ba 28
TMBOY 44:c1d8923072ba 29 ## 整体格式说明
TMBOY 44:c1d8923072ba 30
TMBOY 44:c1d8923072ba 31 ### 架构描述
TMBOY 44:c1d8923072ba 32
TMBOY 44:c1d8923072ba 33 ![dumi_system](http://e.hiphotos.baidu.com/xiaodu/pic/item/2934349b033b5bb53d4d4c7c3fd3d539b700bc9e.jpg)
TMBOY 44:c1d8923072ba 34
TMBOY 44:c1d8923072ba 35 这篇文档整理的是下游bot的输入输出接口
TMBOY 44:c1d8923072ba 36
TMBOY 44:c1d8923072ba 37
TMBOY 44:c1d8923072ba 38 ## 交互模式说明（confirm）
TMBOY 44:c1d8923072ba 39
TMBOY 44:c1d8923072ba 40 ![confirm](http://d.hiphotos.baidu.com/xiaodu/pic/item/f9dcd100baa1cd1111c81ea2b012c8fcc3ce2d31.jpg)
TMBOY 44:c1d8923072ba 41
TMBOY 44:c1d8923072ba 42 * 之所以有confirm请求，是因为us会把同一个请求发给多个bot，然后挑选较好的一个。bot返回的结果，有可能不被使用
TMBOY 44:c1d8923072ba 43 * 按bot对请求的处理有无副作用，分为幂等请求和非幂等请求
TMBOY 44:c1d8923072ba 44 * 幂等请求如：
TMBOY 44:c1d8923072ba 45 * 通用信息
TMBOY 44:c1d8923072ba 46 * 天气
TMBOY 44:c1d8923072ba 47 * 非幂等请求如：
TMBOY 44:c1d8923072ba 48 * 提醒（bot会为用户创建提醒）
TMBOY 44:c1d8923072ba 49 * 打车（bot会帮用户叫车）
TMBOY 44:c1d8923072ba 50
TMBOY 44:c1d8923072ba 51 ### 请求格式
TMBOY 44:c1d8923072ba 52
TMBOY 44:c1d8923072ba 53 以下是现有的协议
TMBOY 44:c1d8923072ba 54
TMBOY 44:c1d8923072ba 55 ```javascript
TMBOY 44:c1d8923072ba 56 {
TMBOY 44:c1d8923072ba 57 //最终返回值里的bot_id，相当于以前的source_type，在中控配置。以后bot_id不再由bot返回的source_type决定
TMBOY 44:c1d8923072ba 58 "bot_name": "ai.dueros.bot.information_general",
TMBOY 44:c1d8923072ba 59 "launch":true,//标识是第一次open这个bot的请求，默认是false
TMBOY 44:c1d8923072ba 60 "end_session":true,//标识是第一次open这个bot的请求，默认是false
TMBOY 44:c1d8923072ba 61 "user_id": "3101", ///用户id，如果非登录用户会改成
TMBOY 44:c1d8923072ba 62 "query": "张岩", //原始query
TMBOY 44:c1d8923072ba 63 "version": 1, //版本号
TMBOY 44:c1d8923072ba 64 "msg": { ///老的协议格式，原始的msg，不知为何result_content是个字符串
TMBOY 44:c1d8923072ba 65 "id": "1454319650_5906bphzi",
TMBOY 44:c1d8923072ba 66 "debug": 1,
TMBOY 44:c1d8923072ba 67 "mode": 0,
TMBOY 44:c1d8923072ba 68 "operation_system": "ios",
TMBOY 44:c1d8923072ba 69 "app_ver": "1.4.0",
TMBOY 44:c1d8923072ba 70 "from": "ios",
TMBOY 44:c1d8923072ba 71 "ctime": 1454319650,
TMBOY 44:c1d8923072ba 72 "type": "user",
TMBOY 44:c1d8923072ba 73 "query_type": "1",
TMBOY 44:c1d8923072ba 74 "device_data":"{}",//target_device_id,device_interface, device_event, device_status 三个字段的打包json，因为现在idl定义不了这三个字段的结构
TMBOY 44:c1d8923072ba 75 "result_list": [
TMBOY 44:c1d8923072ba 76 {
TMBOY 44:c1d8923072ba 77 "result_confidence": 100,
TMBOY 44:c1d8923072ba 78 "result_content": "{\"answer\":\"张岩\"}\n",
TMBOY 44:c1d8923072ba 79 "result_type": "txt",
TMBOY 44:c1d8923072ba 80 "source_type": ""
TMBOY 44:c1d8923072ba 81 }
TMBOY 44:c1d8923072ba 82 ],
TMBOY 44:c1d8923072ba 83 "request_uid": "1463803763",
TMBOY 44:c1d8923072ba 84 "client_msg_id": "20674",
TMBOY 44:c1d8923072ba 85 "request_from": "0",
TMBOY 44:c1d8923072ba 86 "request_type": "0",
TMBOY 44:c1d8923072ba 87 "sample_name": "bear_brain_wireless"
TMBOY 44:c1d8923072ba 88 },
TMBOY 44:c1d8923072ba 89 "log_id": "5969bdd5126d493387a6b127d8c45ce7", //串起整个请求的id
TMBOY 44:c1d8923072ba 90 "request_type": "dumi", //现在的策略分支
TMBOY 44:c1d8923072ba 91 "params": {
TMBOY 44:c1d8923072ba 92 "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之后这个已经没用了
TMBOY 44:c1d8923072ba 93 "cip": "1.2.2.1",//客户端ip
TMBOY 44:c1d8923072ba 94 "bear_params": {
TMBOY 44:c1d8923072ba 95 "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"
TMBOY 44:c1d8923072ba 96 },
TMBOY 44:c1d8923072ba 97 "client_from": "NA",
TMBOY 44:c1d8923072ba 98 "intervene_from": "na",
TMBOY 44:c1d8923072ba 99 "sc_response": "{}"
TMBOY 44:c1d8923072ba 100 },
TMBOY 44:c1d8923072ba 101 //完整的地址信息
TMBOY 44:c1d8923072ba 102 "location": {
TMBOY 44:c1d8923072ba 103 "la": 40.0433,
TMBOY 44:c1d8923072ba 104 "lo": 116.269,
TMBOY 44:c1d8923072ba 105 "bd_la": 40.0508,
TMBOY 44:c1d8923072ba 106 "bd_lo": 116.281,
TMBOY 44:c1d8923072ba 107 "mi_la": 4845580,
TMBOY 44:c1d8923072ba 108 "mi_lo": 12944500,
TMBOY 44:c1d8923072ba 109 "address": "北京市海淀区软件园西三路",
TMBOY 44:c1d8923072ba 110 "city": "北京市",
TMBOY 44:c1d8923072ba 111 "city_code": 131,
TMBOY 44:c1d8923072ba 112 "country": "中国",
TMBOY 44:c1d8923072ba 113 "country_code": 0,
TMBOY 44:c1d8923072ba 114 "direction": "",
TMBOY 44:c1d8923072ba 115 "distance": "",
TMBOY 44:c1d8923072ba 116 "district": "海淀区",
TMBOY 44:c1d8923072ba 117 "province": "北京市",
TMBOY 44:c1d8923072ba 118 "street": "软件园西三路",
TMBOY 44:c1d8923072ba 119 "street_number": "",
TMBOY 44:c1d8923072ba 120 "cip": "1.2.2.1",
TMBOY 44:c1d8923072ba 121 "cip_type": "mockbycity",
TMBOY 44:c1d8923072ba 122 "location_type": "real",
TMBOY 44:c1d8923072ba 123 "sematic_description": "百度科技园内"
TMBOY 44:c1d8923072ba 124 },
TMBOY 44:c1d8923072ba 125 "page_cnt": 10,
TMBOY 44:c1d8923072ba 126 "page_num": 1,
TMBOY 44:c1d8923072ba 127 //没有多轮就可以忽略session字段
TMBOY 44:c1d8923072ba 128 /*
TMBOY 44:c1d8923072ba 129 "sessions": [
TMBOY 44:c1d8923072ba 130 {
TMBOY 44:c1d8923072ba 131 "action": "get",
TMBOY 44:c1d8923072ba 132 "type": "string",
TMBOY 44:c1d8923072ba 133 "name": "phone",
TMBOY 44:c1d8923072ba 134 "key": "3101",
TMBOY 44:c1d8923072ba 135 "list_sessions": [],
TMBOY 44:c1d8923072ba 136 "list_sessions_str": [
TMBOY 44:c1d8923072ba 137 "{\"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}]}}"
TMBOY 44:c1d8923072ba 138 ],
TMBOY 44:c1d8923072ba 139 "hash_sessions": []
TMBOY 44:c1d8923072ba 140 }
TMBOY 44:c1d8923072ba 141 ],
TMBOY 44:c1d8923072ba 142 */
TMBOY 44:c1d8923072ba 143 "safe_mode":false, //儿童模式开关，true为打开状态，fasle为关闭状态
TMBOY 44:c1d8923072ba 144 "bot_sessions": [
TMBOY 44:c1d8923072ba 145 {
TMBOY 44:c1d8923072ba 146 "action": "get",
TMBOY 44:c1d8923072ba 147 "type": "string",
TMBOY 44:c1d8923072ba 148 "key": "3101",
TMBOY 44:c1d8923072ba 149 "list_sessions": [],
TMBOY 44:c1d8923072ba 150 "list_sessions_str": [
TMBOY 44:c1d8923072ba 151 "{\"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}]}}"
TMBOY 44:c1d8923072ba 152 ],
TMBOY 44:c1d8923072ba 153 "hash_sessions": []
TMBOY 44:c1d8923072ba 154 }
TMBOY 44:c1d8923072ba 155 ],
TMBOY 44:c1d8923072ba 156 //////////上次返回new_bot_session, 这次也会用new_bot_session带下来，这是新的session机制，协议简单点 @zhanggang
TMBOY 44:c1d8923072ba 157 "new_bot_session" :{
TMBOY 44:c1d8923072ba 158 "value":"{\"empty\":true}" //需要写入到session中的内容
TMBOY 44:c1d8923072ba 159 },
TMBOY 44:c1d8923072ba 160 //如果是百度登录用户的话，会有信息
TMBOY 44:c1d8923072ba 161 "user_info": {
TMBOY 44:c1d8923072ba 162 "user_id": "",
TMBOY 44:c1d8923072ba 163 "extra": []
TMBOY 44:c1d8923072ba 164 },
TMBOY 44:c1d8923072ba 165 "data": {
TMBOY 44:c1d8923072ba 166 "status": 0,
TMBOY 44:c1d8923072ba 167 "msg": "OK",
TMBOY 44:c1d8923072ba 168 "da_query_info": [ //现在的qu结果，数组，type是服务（第二级的type是domain，第三级result_list里的type是intent）
TMBOY 44:c1d8923072ba 169 {
TMBOY 44:c1d8923072ba 170 "query": "张岩",
TMBOY 44:c1d8923072ba 171 "type": "qu",
TMBOY 44:c1d8923072ba 172 "result_list": [
TMBOY 44:c1d8923072ba 173 {
TMBOY 44:c1d8923072ba 174 "type": "query",
TMBOY 44:c1d8923072ba 175 "score": 0,
TMBOY 44:c1d8923072ba 176 "result_list": []
TMBOY 44:c1d8923072ba 177 },
TMBOY 44:c1d8923072ba 178 {
TMBOY 44:c1d8923072ba 179 "type": "session",
TMBOY 44:c1d8923072ba 180 "score": 0,
TMBOY 44:c1d8923072ba 181 "result_list": []
TMBOY 44:c1d8923072ba 182 }
TMBOY 44:c1d8923072ba 183 ]
TMBOY 44:c1d8923072ba 184 }
TMBOY 44:c1d8923072ba 185 ],
TMBOY 44:c1d8923072ba 186 "params": [ //其他几个qu结果的原始数据，一般情况都不用看
TMBOY 44:c1d8923072ba 187 {
TMBOY 44:c1d8923072ba 188 "key": "nlu_responce",
TMBOY 44:c1d8923072ba 189 "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"
TMBOY 44:c1d8923072ba 190 },
TMBOY 44:c1d8923072ba 191 {
TMBOY 44:c1d8923072ba 192 "key": "qu_responce",
TMBOY 44:c1d8923072ba 193 "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}]}"
TMBOY 44:c1d8923072ba 194 }
TMBOY 44:c1d8923072ba 195 ]
TMBOY 44:c1d8923072ba 196 },
TMBOY 44:c1d8923072ba 197 //数组每一个元素为一类资源类型;audio(mp3(16000,128000),aac)代表音频格式只支持mp3和aac，其中mp3只支持码率在16k~128k之间
TMBOY 44:c1d8923072ba 198 "supported_content_type":["audio(mp3(16000,128000),aac)","video","image","webview","speech"],
TMBOY 44:c1d8923072ba 199 //keep_silence=1的时候，中控不给客户端返回tts或者显示的信息，但会做写session等处理
TMBOY 44:c1d8923072ba 200 "keep_silence":1
TMBOY 44:c1d8923072ba 201 }
TMBOY 44:c1d8923072ba 202
TMBOY 44:c1d8923072ba 203
TMBOY 44:c1d8923072ba 204
TMBOY 44:c1d8923072ba 205 ```
TMBOY 44:c1d8923072ba 206
TMBOY 44:c1d8923072ba 207 #### 请求字段中，.supported_content_type字段的解释
TMBOY 44:c1d8923072ba 208 表示了端支持的内容类型，bot应该召回端支持的内容类型，**不召回**端不支持的内容
TMBOY 44:c1d8923072ba 209 * audio
TMBOY 44:c1d8923072ba 210 * video
TMBOY 44:c1d8923072ba 211 * image
TMBOY 44:c1d8923072ba 212 * webview
TMBOY 44:c1d8923072ba 213 * speech
TMBOY 44:c1d8923072ba 214
TMBOY 44:c1d8923072ba 215 #### 请求字段中，.msg.device_data字段的解释
TMBOY 44:c1d8923072ba 216
TMBOY 44:c1d8923072ba 217 .msg.device_data字段，是一个json_encode后的字符串
TMBOY 44:c1d8923072ba 218
TMBOY 44:c1d8923072ba 219 会把[请求里的几个字段](api/request.md#客户端能力相关device_interface-device_event-device_status)映射过来
TMBOY 44:c1d8923072ba 220
TMBOY 44:c1d8923072ba 221 下面是这个json展开后的结构
TMBOY 44:c1d8923072ba 222 ```javascript
TMBOY 44:c1d8923072ba 223 {
TMBOY 44:c1d8923072ba 224
TMBOY 44:c1d8923072ba 225 "target_device_id":"xxxxxx",
TMBOY 44:c1d8923072ba 226 "device_interface":{
TMBOY 44:c1d8923072ba 227 "Alerts":{},
TMBOY 44:c1d8923072ba 228 "AudioPlayer":{
TMBOY 44:c1d8923072ba 229 //"no_pause":1,
TMBOY 44:c1d8923072ba 230 //"no_seek":1,
TMBOY 44:c1d8923072ba 231 },
TMBOY 44:c1d8923072ba 232 "PlaybackController":{},
TMBOY 44:c1d8923072ba 233 "Speaker":{},
TMBOY 44:c1d8923072ba 234 "Settings":{},
TMBOY 44:c1d8923072ba 235 "System":{}
TMBOY 44:c1d8923072ba 236 },
TMBOY 44:c1d8923072ba 237 "device_event":{
TMBOY 44:c1d8923072ba 238 //query_type==30 的时候才会有 device_event
TMBOY 44:c1d8923072ba 239 "header": {
TMBOY 44:c1d8923072ba 240 "namespace": "AudioPlayer",
TMBOY 44:c1d8923072ba 241 "name": "PlaybackStarted",
TMBOY 44:c1d8923072ba 242 "message_id": "message_id-1344"
TMBOY 44:c1d8923072ba 243 },
TMBOY 44:c1d8923072ba 244 "payload": {
TMBOY 44:c1d8923072ba 245 //AudioPlayer里可能出现的payload
TMBOY 44:c1d8923072ba 246 "token": "156",
TMBOY 44:c1d8923072ba 247 "offset_ms": 10000,
TMBOY 44:c1d8923072ba 248 //Speaker里可能出现的payload
TMBOY 44:c1d8923072ba 249 "volume": 1,
TMBOY 44:c1d8923072ba 250 //SpeechSynthesizer可能出现的payload
TMBOY 44:c1d8923072ba 251 "token": "156",
TMBOY 44:c1d8923072ba 252 "type": "{{Text/SSML}}",
TMBOY 44:c1d8923072ba 253 "content": ["xxxx1", "xxxx2"],
TMBOY 44:c1d8923072ba 254 "speak_behavior": "REPLACE_ALL",
TMBOY 44:c1d8923072ba 255 "should_get_next_speech": true
TMBOY 44:c1d8923072ba 256 }
TMBOY 44:c1d8923072ba 257 },
TMBOY 44:c1d8923072ba 258 "device_status":{
TMBOY 44:c1d8923072ba 259 "AudioPlayer":{
TMBOY 44:c1d8923072ba 260 "token":"xxx",//正在播放的音频流id
TMBOY 44:c1d8923072ba 261 "offset_ms":20000,//播放到多少ms了
TMBOY 44:c1d8923072ba 262 "player_activity":"IDLE PAUSED PLAYING BUFFER_UNDERRUN FINISHED STOPPED"
TMBOY 44:c1d8923072ba 263 },
TMBOY 44:c1d8923072ba 264 }
TMBOY 44:c1d8923072ba 265 }
TMBOY 44:c1d8923072ba 266 ```
TMBOY 44:c1d8923072ba 267
TMBOY 44:c1d8923072ba 268
TMBOY 44:c1d8923072ba 269 ### 正常返回格式
TMBOY 44:c1d8923072ba 270
TMBOY 44:c1d8923072ba 271
TMBOY 44:c1d8923072ba 272 ```javascript
TMBOY 44:c1d8923072ba 273
TMBOY 44:c1d8923072ba 274 {
TMBOY 44:c1d8923072ba 275 "status": 0,
TMBOY 44:c1d8923072ba 276 "msg": "ok",
TMBOY 44:c1d8923072ba 277 "data": {
TMBOY 44:c1d8923072ba 278 "result_list": [
TMBOY 44:c1d8923072ba 279 {
TMBOY 44:c1d8923072ba 280 //内容质量得分，可选
TMBOY 44:c1d8923072ba 281 "confidence": 100,
TMBOY 44:c1d8923072ba 282 //bot的id，必须有
TMBOY 44:c1d8923072ba 283 "source_type": "phone",
TMBOY 44:c1d8923072ba 284 //统计字段，可以用来给bot的返回值分类，可以不传
TMBOY 44:c1d8923072ba 285 "source_sub_type": "contact",
TMBOY 44:c1d8923072ba 286 //真正拼的消息其实是这个content字段，现在对外返回的resource、directives等字段都放在这个里面，和result_list平级，下一段详细讲这个content
TMBOY 44:c1d8923072ba 287 "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\"}",
TMBOY 44:c1d8923072ba 288 //会用于us排序的字段，为了让排序策略起作用，尽可能传一下
TMBOY 44:c1d8923072ba 289 "stategy_middle_data": {
TMBOY 44:c1d8923072ba 290 "bot_intent":{
TMBOY 44:c1d8923072ba 291 "query":"raw query" ////请求的query，如果有bot_intent，这个就必须有
TMBOY 44:c1d8923072ba 292 "query_score":100 ////和需求的匹配度,可选
TMBOY 44:c1d8923072ba 293 },
TMBOY 44:c1d8923072ba 294 "raw_answer": [
TMBOY 44:c1d8923072ba 295 {
TMBOY 44:c1d8923072ba 296 "title": "",
TMBOY 44:c1d8923072ba 297 "subtitle": "",
TMBOY 44:c1d8923072ba 298 "answer": "<SYSTEM-NAME>为你查看联系人“张岩”",
TMBOY 44:c1d8923072ba 299 "url": ""
TMBOY 44:c1d8923072ba 300 }
TMBOY 44:c1d8923072ba 301 ]
TMBOY 44:c1d8923072ba 302 }
TMBOY 44:c1d8923072ba 303 }
TMBOY 44:c1d8923072ba 304 ],
TMBOY 44:c1d8923072ba 305 //页码，总页数，总结果数，都可以不传
TMBOY 44:c1d8923072ba 306 "page_num": 1,
TMBOY 44:c1d8923072ba 307 "page_cnt": 1,
TMBOY 44:c1d8923072ba 308 "result_num": 1,
TMBOY 44:c1d8923072ba 309 ////和请求中的da_query_info格式一致，表示下游bot实际使用的da_query_info（也可以说就是把请求中不使用的），可以为空
TMBOY 44:c1d8923072ba 310 "service_query_info": [
TMBOY 44:c1d8923072ba 311 {
TMBOY 44:c1d8923072ba 312 "query": "张岩",
TMBOY 44:c1d8923072ba 313 "type": "phone",
TMBOY 44:c1d8923072ba 314 "result_list": [
TMBOY 44:c1d8923072ba 315 {
TMBOY 44:c1d8923072ba 316 "type": "phone",
TMBOY 44:c1d8923072ba 317 "score": 100,
TMBOY 44:c1d8923072ba 318 "result_list": [
TMBOY 44:c1d8923072ba 319 {
TMBOY 44:c1d8923072ba 320 "type": "contact",
TMBOY 44:c1d8923072ba 321 "score": 0,
TMBOY 44:c1d8923072ba 322 "content": "",
TMBOY 44:c1d8923072ba 323 "result_list": [
TMBOY 44:c1d8923072ba 324 {
TMBOY 44:c1d8923072ba 325 "key": "name_for_view",
TMBOY 44:c1d8923072ba 326 "type": "text",
TMBOY 44:c1d8923072ba 327 "score": 0,
TMBOY 44:c1d8923072ba 328 "value": [
TMBOY 44:c1d8923072ba 329 {
TMBOY 44:c1d8923072ba 330 "name": "name_for_view",
TMBOY 44:c1d8923072ba 331 "value": "张岩"
TMBOY 44:c1d8923072ba 332 }
TMBOY 44:c1d8923072ba 333 ]
TMBOY 44:c1d8923072ba 334 },
TMBOY 44:c1d8923072ba 335 {
TMBOY 44:c1d8923072ba 336 "key": "pinyin_for_view",
TMBOY 44:c1d8923072ba 337 "type": "text",
TMBOY 44:c1d8923072ba 338 "score": 0,
TMBOY 44:c1d8923072ba 339 "value": [
TMBOY 44:c1d8923072ba 340 {
TMBOY 44:c1d8923072ba 341 "name": "pinyin_for_view",
TMBOY 44:c1d8923072ba 342 "value": "zhang+yan"
TMBOY 44:c1d8923072ba 343 }
TMBOY 44:c1d8923072ba 344 ]
TMBOY 44:c1d8923072ba 345 },
TMBOY 44:c1d8923072ba 346 {
TMBOY 44:c1d8923072ba 347 "key": "action_type",
TMBOY 44:c1d8923072ba 348 "type": "text",
TMBOY 44:c1d8923072ba 349 "score": 0,
TMBOY 44:c1d8923072ba 350 "value": [
TMBOY 44:c1d8923072ba 351 {
TMBOY 44:c1d8923072ba 352 "name": "action_type",
TMBOY 44:c1d8923072ba 353 "value": "1"
TMBOY 44:c1d8923072ba 354 }
TMBOY 44:c1d8923072ba 355 ]
TMBOY 44:c1d8923072ba 356 },
TMBOY 44:c1d8923072ba 357 {
TMBOY 44:c1d8923072ba 358 "key": "show_query",
TMBOY 44:c1d8923072ba 359 "type": "text",
TMBOY 44:c1d8923072ba 360 "score": 0,
TMBOY 44:c1d8923072ba 361 "value": [
TMBOY 44:c1d8923072ba 362 {
TMBOY 44:c1d8923072ba 363 "name": "show_query",
TMBOY 44:c1d8923072ba 364 "value": "张岩"
TMBOY 44:c1d8923072ba 365 }
TMBOY 44:c1d8923072ba 366 ]
TMBOY 44:c1d8923072ba 367 }
TMBOY 44:c1d8923072ba 368 ]
TMBOY 44:c1d8923072ba 369 }
TMBOY 44:c1d8923072ba 370 ]
TMBOY 44:c1d8923072ba 371 }
TMBOY 44:c1d8923072ba 372 ]
TMBOY 44:c1d8923072ba 373 }
TMBOY 44:c1d8923072ba 374 ],
TMBOY 44:c1d8923072ba 375 "server_query_intent": "\"\""
TMBOY 44:c1d8923072ba 376 },
TMBOY 44:c1d8923072ba 377 /////如果不是多轮，此字段可没有
TMBOY 44:c1d8923072ba 378 ///sessions字段已经废弃，现在是bot_sessions和decision_sessions, 不再有name
TMBOY 44:c1d8923072ba 379 /*
TMBOY 44:c1d8923072ba 380 "sessions": [
TMBOY 44:c1d8923072ba 381 {
TMBOY 44:c1d8923072ba 382 "status": 0,
TMBOY 44:c1d8923072ba 383 "msg": "ok",
TMBOY 44:c1d8923072ba 384 "action": "set",
TMBOY 44:c1d8923072ba 385 "type": "string",
TMBOY 44:c1d8923072ba 386 "name": "phone",
TMBOY 44:c1d8923072ba 387 "key": "3101",
TMBOY 44:c1d8923072ba 388 "list_sessions_str": [
TMBOY 44:c1d8923072ba 389 "{\"empty\":true}"
TMBOY 44:c1d8923072ba 390 ]
TMBOY 44:c1d8923072ba 391 }
TMBOY 44:c1d8923072ba 392 ]
TMBOY 44:c1d8923072ba 393 */
TMBOY 44:c1d8923072ba 394 "bot_sessions": [
TMBOY 44:c1d8923072ba 395 {
TMBOY 44:c1d8923072ba 396 "status": 0,
TMBOY 44:c1d8923072ba 397 "msg": "ok",
TMBOY 44:c1d8923072ba 398 "action": "set",
TMBOY 44:c1d8923072ba 399 "type": "string",
TMBOY 44:c1d8923072ba 400 "key": "3101",
TMBOY 44:c1d8923072ba 401 "list_sessions_str": [
TMBOY 44:c1d8923072ba 402 "{\"empty\":true}"
TMBOY 44:c1d8923072ba 403 ]
TMBOY 44:c1d8923072ba 404 }
TMBOY 44:c1d8923072ba 405 ],
TMBOY 44:c1d8923072ba 406 //////////用new_bot_session的话，请求也会带new_bot_session下来，这是新的session机制，协议简单点 @zhanggang
TMBOY 44:c1d8923072ba 407 "new_bot_session" :{
TMBOY 44:c1d8923072ba 408 "value":"{\"empty\":true}",//需要写入到session中的内容
TMBOY 44:c1d8923072ba 409 "expire":0,//这个Session的过期时间
TMBOY 44:c1d8923072ba 410 },
TMBOY 44:c1d8923072ba 411 ///////////////////////////////
TMBOY 44:c1d8923072ba 412 "decision_sessions": [
TMBOY 44:c1d8923072ba 413 {
TMBOY 44:c1d8923072ba 414 "status": 0,
TMBOY 44:c1d8923072ba 415 "msg": "ok",
TMBOY 44:c1d8923072ba 416 "action": "set",
TMBOY 44:c1d8923072ba 417 "type": "string",
TMBOY 44:c1d8923072ba 418 "key": "3101",
TMBOY 44:c1d8923072ba 419 "list_sessions_str": [
TMBOY 44:c1d8923072ba 420 "{\"empty\":true}"
TMBOY 44:c1d8923072ba 421 ]
TMBOY 44:c1d8923072ba 422 }
TMBOY 44:c1d8923072ba 423 ],
TMBOY 44:c1d8923072ba 424 //可选，默认为true，如果为false，客户端应该立即进入收听用户query的状态，不用重新唤醒
TMBOY 44:c1d8923072ba 425 "should_end_session":false,
TMBOY 44:c1d8923072ba 426
TMBOY 44:c1d8923072ba 427 }
TMBOY 44:c1d8923072ba 428
TMBOY 44:c1d8923072ba 429 ```
TMBOY 44:c1d8923072ba 430
TMBOY 44:c1d8923072ba 431 所以，极简单情况下（没有多轮，没有使用da结果），bot可以只返回以下结构
TMBOY 44:c1d8923072ba 432 ```javascript
TMBOY 44:c1d8923072ba 433 {
TMBOY 44:c1d8923072ba 434 "status": 0,
TMBOY 44:c1d8923072ba 435 "msg": "ok",
TMBOY 44:c1d8923072ba 436 "data": {
TMBOY 44:c1d8923072ba 437 "result_list": [
TMBOY 44:c1d8923072ba 438 {
TMBOY 44:c1d8923072ba 439 //内容质量得分，可选
TMBOY 44:c1d8923072ba 440 "confidence": 100,
TMBOY 44:c1d8923072ba 441 //bot的id，必须有
TMBOY 44:c1d8923072ba 442 "source_type": "phone",
TMBOY 44:c1d8923072ba 443 //真正拼的消息其实是这个content字段，现在对外返回的resource、directives等字段都放在这个里面，和result_list平级，下一段详细讲这个content
TMBOY 44:c1d8923072ba 444 "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\"}",
TMBOY 44:c1d8923072ba 445 //会用于us排序的字段，为了让排序策略起作用，尽可能传一下
TMBOY 44:c1d8923072ba 446 "stategy_middle_data": {
TMBOY 44:c1d8923072ba 447 "bot_intent":{
TMBOY 44:c1d8923072ba 448 "query":"raw query" ////请求的query，如果有bot_intent，这个就必须有
TMBOY 44:c1d8923072ba 449 "query_score":100 ////和需求的匹配度,可选
TMBOY 44:c1d8923072ba 450 },
TMBOY 44:c1d8923072ba 451 "raw_answer": [
TMBOY 44:c1d8923072ba 452 {
TMBOY 44:c1d8923072ba 453 "title": "",
TMBOY 44:c1d8923072ba 454 "subtitle": "",
TMBOY 44:c1d8923072ba 455 "answer": "<SYSTEM-NAME>为你查看联系人“张岩”",
TMBOY 44:c1d8923072ba 456 "url": ""
TMBOY 44:c1d8923072ba 457 }
TMBOY 44:c1d8923072ba 458 ]
TMBOY 44:c1d8923072ba 459 }
TMBOY 44:c1d8923072ba 460 }
TMBOY 44:c1d8923072ba 461 ]
TMBOY 44:c1d8923072ba 462 },
TMBOY 44:c1d8923072ba 463 //可选，默认为true，如果为false，客户端应该立即进入收听用户query的状态，不用重新唤醒
TMBOY 44:c1d8923072ba 464 "should_end_session":false
TMBOY 44:c1d8923072ba 465 }
TMBOY 44:c1d8923072ba 466
TMBOY 44:c1d8923072ba 467 ```
TMBOY 44:c1d8923072ba 468
TMBOY 44:c1d8923072ba 469 #### 和策略相关的字段
TMBOY 44:c1d8923072ba 470 * data.result_list[].stategy_middle_data.bot_intent.query_score，取值0-100 ，标识内容的质量
TMBOY 44:c1d8923072ba 471 * data.result_list[].confidence，取值0-100 ，标识和query的匹配度
TMBOY 44:c1d8923072ba 472
TMBOY 44:c1d8923072ba 473 #### 正常返回的字段中，content字段的解释
TMBOY 44:c1d8923072ba 474
TMBOY 44:c1d8923072ba 475 .data.result_list[].content字段，是一个json_encode后的字符串
TMBOY 44:c1d8923072ba 476
TMBOY 44:c1d8923072ba 477 下面是这个json展开后的结构
TMBOY 44:c1d8923072ba 478
TMBOY 44:c1d8923072ba 479 内部可以加入新协议的字段，如resource、speech、views等等，但一定要有一个result_list。
TMBOY 44:c1d8923072ba 480 * 如果有传views、speech、resource等字段，result_list的内容可以随意，不会在新的输出接口中生效
TMBOY 44:c1d8923072ba 481 * 如果不传views、speech、resource等字段，api2.0接口输出时，会把result_list按一定规则转换成这些新字段
TMBOY 44:c1d8923072ba 482 * views、speech、resource等字段的数据结构，参见[度秘api2.0文档](api/response.md)
TMBOY 44:c1d8923072ba 483 * 老的result_list内部的详细格式，可参考[度秘api1.0文档](http://agroup.baidu.com/duer/md/article/17301)，主要是定义了result_list可以放的卡片格式
TMBOY 44:c1d8923072ba 484
TMBOY 44:c1d8923072ba 485 ```javascript
TMBOY 44:c1d8923072ba 486 {
TMBOY 44:c1d8923072ba 487 //result_list是老的结构，现在无论如何要传一个
TMBOY 44:c1d8923072ba 488 "result_list": [
TMBOY 44:c1d8923072ba 489 {
TMBOY 44:c1d8923072ba 490 "result_content": {
TMBOY 44:c1d8923072ba 491 "answer": "<SYSTEM-NAME>为你查看联系人“张岩”"
TMBOY 44:c1d8923072ba 492 },
TMBOY 44:c1d8923072ba 493 "result_type": "txt",
TMBOY 44:c1d8923072ba 494 "source_type": "phone",
TMBOY 44:c1d8923072ba 495 //可选，用于统计
TMBOY 44:c1d8923072ba 496 "source_sub_type": "contact",
TMBOY 44:c1d8923072ba 497 //语音播报的内容，可选
TMBOY 44:c1d8923072ba 498 "voice": "<SYSTEM-NAME>为你查看联系人“张岩”"
TMBOY 44:c1d8923072ba 499 }
TMBOY 44:c1d8923072ba 500 ],
TMBOY 44:c1d8923072ba 501 //可选，内容见api2.0接口
TMBOY 44:c1d8923072ba 502 views:[],
TMBOY 44:c1d8923072ba 503 //可选，内容见api2.0接口
TMBOY 44:c1d8923072ba 504 resource:{},
TMBOY 44:c1d8923072ba 505 //可选，内容见api2.0接口
TMBOY 44:c1d8923072ba 506 speech:{},
TMBOY 44:c1d8923072ba 507 //可选，内容见api2.0接口
TMBOY 44:c1d8923072ba 508 directives:{},
TMBOY 44:c1d8923072ba 509 //可选，内容见api2.0接口
TMBOY 44:c1d8923072ba 510 hint:[],
TMBOY 44:c1d8923072ba 511 //可选，最好是传下来的nlu数据里选一个返回，内容见api2.0接口
TMBOY 44:c1d8923072ba 512 nlu:{},
TMBOY 44:c1d8923072ba 513 "type": "server"
TMBOY 44:c1d8923072ba 514 }
TMBOY 44:c1d8923072ba 515 ```