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

ex

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

dumi_doc-master/doc/BOTAPI2.0_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 # 度秘开放平台-BotApi2.0接口说明
TMBOY 44:c1d8923072ba 2
TMBOY 44:c1d8923072ba 3 ## Table of Contents
TMBOY 44:c1d8923072ba 4
TMBOY 44:c1d8923072ba 5
TMBOY 44:c1d8923072ba 6 * [度秘开放平台-BotApi2.0接口说明](#度秘开放平台-botapi20接口说明)
TMBOY 44:c1d8923072ba 7 * [Table of Contents](#table-of-contents)
TMBOY 44:c1d8923072ba 8 * [交互模式说明](#交互模式说明)
TMBOY 44:c1d8923072ba 9 * [关于confirm的说明](#关于confirm的说明)
TMBOY 44:c1d8923072ba 10 * [请求格式](#请求格式)
TMBOY 44:c1d8923072ba 11 * [未来的响应格式](#未来的响应格式)
TMBOY 44:c1d8923072ba 12 * [bot配置（开放平台的输出）](#bot配置开放平台的输出)
TMBOY 44:c1d8923072ba 13
TMBOY 44:c1d8923072ba 14
TMBOY 44:c1d8923072ba 15 ## 交互模式说明
TMBOY 44:c1d8923072ba 16
TMBOY 44:c1d8923072ba 17 ### 关于confirm的说明
TMBOY 44:c1d8923072ba 18 ![confirm](http://d.hiphotos.baidu.com/xiaodu/pic/item/f9dcd100baa1cd1111c81ea2b012c8fcc3ce2d31.jpg)
TMBOY 44:c1d8923072ba 19
TMBOY 44:c1d8923072ba 20 * 之所以有confirm请求，是因为us会把同一个请求发给多个bot，然后挑选较好的一个。bot返回的结果，有可能不被使用
TMBOY 44:c1d8923072ba 21 * 按bot对请求的处理有无副作用，分为幂等请求和非幂等请求
TMBOY 44:c1d8923072ba 22 * 幂等请求如：
TMBOY 44:c1d8923072ba 23 * 通用信息
TMBOY 44:c1d8923072ba 24 * 天气
TMBOY 44:c1d8923072ba 25 * 非幂等请求如：
TMBOY 44:c1d8923072ba 26 * 提醒（bot会为用户创建提醒）
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 ```javascript
TMBOY 44:c1d8923072ba 33 {
TMBOY 44:c1d8923072ba 34 "version": 2,
TMBOY 44:c1d8923072ba 35 "query":"", //query，可能已经经过了改写
TMBOY 44:c1d8923072ba 36 "raw_query":"", //原始query，可选
TMBOY 44:c1d8923072ba 37 "content_type": "image",//可选，默认是txt
TMBOY 44:c1d8923072ba 38 "user_id":"", //对bot来说，可以唯一标识一个用户的string
TMBOY 44:c1d8923072ba 39
TMBOY 44:c1d8923072ba 40 "cuid":"", //设备id，可选
TMBOY 44:c1d8923072ba 41 "dumi_id":"", //度秘登录用户id，可选
TMBOY 44:c1d8923072ba 42 "baidu_uid":"", //百度登录后的passport id，可选
TMBOY 44:c1d8923072ba 43 "bot_id":"",//把bot_id带下来，其实可以不看
TMBOY 44:c1d8923072ba 44
TMBOY 44:c1d8923072ba 45 "log_id":"5969bdd5126d493387a6b127d8c45ce7",
TMBOY 44:c1d8923072ba 46 "confirm":1,//0或者1，0代表可能不会使用bot的返回结果，1代表肯定会使用bot的返回结果。（参考上面的[关于confirm的说明]）
TMBOY 44:c1d8923072ba 47
TMBOY 44:c1d8923072ba 48 "query_type":"1",//请求类型，标识用户发这个请求的方法，参见文档 http://agroup.baidu.com/dbo/md/article/49113
TMBOY 44:c1d8923072ba 49 "client_info":{
TMBOY 44:c1d8923072ba 50 "device_interface":{
TMBOY 44:c1d8923072ba 51 "Alerts":{},
TMBOY 44:c1d8923072ba 52 "AudioPlayer":{},
TMBOY 44:c1d8923072ba 53 "PlaybackController":{},
TMBOY 44:c1d8923072ba 54 "Speaker":{},
TMBOY 44:c1d8923072ba 55 "Settings":{},
TMBOY 44:c1d8923072ba 56 "System":{}
TMBOY 44:c1d8923072ba 57 }, //设备支持的接口（包含directive、event等整套实现）
TMBOY 44:c1d8923072ba 58
TMBOY 44:c1d8923072ba 59 "device_event":{
TMBOY 44:c1d8923072ba 60 //query_type==30 的时候才会有 device_event
TMBOY 44:c1d8923072ba 61 "header": {
TMBOY 44:c1d8923072ba 62 "namespace": "AudioPlayer",
TMBOY 44:c1d8923072ba 63 "name": "PlaybackStarted",
TMBOY 44:c1d8923072ba 64 "message_id": "message_id-1344"
TMBOY 44:c1d8923072ba 65 },
TMBOY 44:c1d8923072ba 66 "payload": {
TMBOY 44:c1d8923072ba 67 //AudioPlayer里可能出现的payload
TMBOY 44:c1d8923072ba 68 "token": "156",
TMBOY 44:c1d8923072ba 69 "offset_ms": 10000
TMBOY 44:c1d8923072ba 70 //Speaker里可能出现的payload
TMBOY 44:c1d8923072ba 71 "volume": 1,
TMBOY 44:c1d8923072ba 72 //SpeechSynthesizer可能出现的payload
TMBOY 44:c1d8923072ba 73 "token": "156",
TMBOY 44:c1d8923072ba 74 "type": "{{Text/SSML}}",
TMBOY 44:c1d8923072ba 75 "content": ["xxxx1", "xxxx2"],
TMBOY 44:c1d8923072ba 76 "speak_behavior": "REPLACE_ALL",
TMBOY 44:c1d8923072ba 77 "should_get_next_speech": true
TMBOY 44:c1d8923072ba 78 }
TMBOY 44:c1d8923072ba 79 },
TMBOY 44:c1d8923072ba 80
TMBOY 44:c1d8923072ba 81 "device_status":{
TMBOY 44:c1d8923072ba 82 "AudioPlayer":{
TMBOY 44:c1d8923072ba 83 "audio_item_id":"xxx",//正在播放的音频流id
TMBOY 44:c1d8923072ba 84 "offsetInMilliseconds":20000,//播放到多少ms了
TMBOY 44:c1d8923072ba 85 "playerActivity":"IDLE PAUSED PLAYING BUFFER_UNDERRUN FINISHED STOPPED"
TMBOY 44:c1d8923072ba 86 },
TMBOY 44:c1d8923072ba 87 },
TMBOY 44:c1d8923072ba 88 "operation_system":"android",
TMBOY 44:c1d8923072ba 89 "operation_system_version":"5.0",
TMBOY 44:c1d8923072ba 90 "from_client":"sdk",// sdk/na/shoubai
TMBOY 44:c1d8923072ba 91 "appid":"appid",
TMBOY 44:c1d8923072ba 92 "appkey":"appkey",
TMBOY 44:c1d8923072ba 93 "device_brand":"apple", //设备品牌 （目前只有对外sdk有该字段），ios写死"apple"，安卓取android.os.Build.BRAND
TMBOY 44:c1d8923072ba 94 "device_model":"iphone 6s", //设备具体型号 （目前只有对外sdk有该字段）ios取 设备型号字符串
TMBOY 44:c1d8923072ba 95 "ua":"",//可选，浏览器的user agent
TMBOY 44:c1d8923072ba 96 "app_ver":"1.0.0"
TMBOY 44:c1d8923072ba 97 },
TMBOY 44:c1d8923072ba 98
TMBOY 44:c1d8923072ba 99 //完整的地址信息
TMBOY 44:c1d8923072ba 100 "location": {
TMBOY 44:c1d8923072ba 101 "la": 40.0433,
TMBOY 44:c1d8923072ba 102 "lo": 116.269,
TMBOY 44:c1d8923072ba 103 "bd_la": 40.0508,
TMBOY 44:c1d8923072ba 104 "bd_lo": 116.281,
TMBOY 44:c1d8923072ba 105 "mi_la": 4845580,
TMBOY 44:c1d8923072ba 106 "mi_lo": 12944500,
TMBOY 44:c1d8923072ba 107 "address": "北京市海淀区软件园西三路",
TMBOY 44:c1d8923072ba 108 "city": "北京市",
TMBOY 44:c1d8923072ba 109 "city_code": 131,
TMBOY 44:c1d8923072ba 110 "country": "中国",
TMBOY 44:c1d8923072ba 111 "country_code": 0,
TMBOY 44:c1d8923072ba 112 "direction": "",
TMBOY 44:c1d8923072ba 113 "distance": "",
TMBOY 44:c1d8923072ba 114 "district": "海淀区",
TMBOY 44:c1d8923072ba 115 "province": "北京市",
TMBOY 44:c1d8923072ba 116 "street": "软件园西三路",
TMBOY 44:c1d8923072ba 117 "street_number": "",
TMBOY 44:c1d8923072ba 118 "cip": "1.2.2.1",
TMBOY 44:c1d8923072ba 119 "cip_type": "mockbycity",
TMBOY 44:c1d8923072ba 120 "location_type": "real",
TMBOY 44:c1d8923072ba 121 "sematic_description": "百度科技园内"
TMBOY 44:c1d8923072ba 122 },
TMBOY 44:c1d8923072ba 123
TMBOY 44:c1d8923072ba 124 "session": {//是上次user_id + bot_id 请求的返回值里的session，纯kv，内部结构不做限制（串行化保存的值）
TMBOY 44:c1d8923072ba 125 "key":"value",
TMBOY 44:c1d8923072ba 126 "key2":"value2"
TMBOY 44:c1d8923072ba 127 },
TMBOY 44:c1d8923072ba 128 //用户常驻地址，可选，字段和上面location一致
TMBOY 44:c1d8923072ba 129 "freq_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": "百度科技园内" },
TMBOY 44:c1d8923072ba 130 //最近几次访问的地址，可选，一个数组，每个元素里面的结构和location 一致
TMBOY 44:c1d8923072ba 131 "last_location":[
TMBOY 44:c1d8923072ba 132 { "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": "百度科技园内" },
TMBOY 44:c1d8923072ba 133 { "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": "百度科技园内" },
TMBOY 44:c1d8923072ba 134 ],
TMBOY 44:c1d8923072ba 135
TMBOY 44:c1d8923072ba 136 //da解析结果，对一个query可能有多种理解，所以是一个数组
TMBOY 44:c1d8923072ba 137 "nlu_list":[
TMBOY 44:c1d8923072ba 138 {"score":100,"domain":"remind","intent":"remind","slots":{"event_title":"开会","intent":"设置","remind_time":"{\"month\":\"10\",\"day\":\"21\",\"hour\":\"9\",\"apm\":\"am\"}","__intent__":"setup","__id__":"1483430617165_fu6tll","remind_type_message":"否","remind_type_phone":"否","remind_type_dumi":"否","remind_type_clock":"否","remind_time_type":"abstime","remind_time_data":"1508547600","status":"create_confirm"}},
TMBOY 44:c1d8923072ba 139 {"score":100,"domain":"duer_weather","intent":"sys_weather","slots":{"loc_city":"九江市","loc_county":"九江市","loc_province":"江西省","time":"2017-01-03,2017-01-03"}},
TMBOY 44:c1d8923072ba 140 ],
TMBOY 44:c1d8923072ba 141 //其他da解析结果，会放服务的原始返回，比如分词、语法分析之类的结果
TMBOY 44:c1d8923072ba 142 "nlu_extend":{
TMBOY 44:c1d8923072ba 143 "nlu_responce": "{\"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 144 "qu_responce": "{\"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 145 },
TMBOY 44:c1d8923072ba 146 }
TMBOY 44:c1d8923072ba 147 ```
TMBOY 44:c1d8923072ba 148
TMBOY 44:c1d8923072ba 149 ## 未来的响应格式
TMBOY 44:c1d8923072ba 150
TMBOY 44:c1d8923072ba 151 里面的result结构中的views、resource、nlu、speech、directives、hint都和对外输出的格式里的定义一致，详细结构可见([度秘API2.0文档](http://gitlab.baidu.com/wangpeng20/dumi_schema/blob/master/doc/OPENAPI_README.md))
TMBOY 44:c1d8923072ba 152
TMBOY 44:c1d8923072ba 153 ```javascript
TMBOY 44:c1d8923072ba 154 {
TMBOY 44:c1d8923072ba 155 "status" : 0, //0 success，other fail
TMBOY 44:c1d8923072ba 156 "version": 2,
TMBOY 44:c1d8923072ba 157 "msg" : "string", //status 0，msg "success"，status not 0，msg explaining reason
TMBOY 44:c1d8923072ba 158 "need_confirm":1, //可选，默认为0，参考前面的[关于confirm的说明]
TMBOY 44:c1d8923072ba 159 "data" : {
TMBOY 44:c1d8923072ba 160 //如果bot没有召回结果，就不要返回result结构了
TMBOY 44:c1d8923072ba 161 "result":{
TMBOY 44:c1d8923072ba 162 //必选
TMBOY 44:c1d8923072ba 163 "views":[],
TMBOY 44:c1d8923072ba 164 //可选
TMBOY 44:c1d8923072ba 165 "resource":{},
TMBOY 44:c1d8923072ba 166 //应该从请求的nlus里选一条返回,可选
TMBOY 44:c1d8923072ba 167 "nlu":{"domain":"duer_weather","intent":"sys_weather","slots":{"loc_city":"九江市","loc_county":"九江市","loc_province":"江西省","time":"2017-01-03,2017-01-03"}},
TMBOY 44:c1d8923072ba 168 //必选
TMBOY 44:c1d8923072ba 169 "speech":{},
TMBOY 44:c1d8923072ba 170 //可选
TMBOY 44:c1d8923072ba 171 "directives":[],
TMBOY 44:c1d8923072ba 172 //可选
TMBOY 44:c1d8923072ba 173 "hint":[],
TMBOY 44:c1d8923072ba 174 //可选，默认为true，如果为false，客户端应该立即进入收听用户query的状态，不用重新唤醒
TMBOY 44:c1d8923072ba 175 'should_end_session':false,
TMBOY 44:c1d8923072ba 176 },
TMBOY 44:c1d8923072ba 177 //会被串行化后保存起来，下次同一个 (user_id,bot_id) 请求的时候，会带上
TMBOY 44:c1d8923072ba 178 "session":{
TMBOY 44:c1d8923072ba 179 "key":"value",
TMBOY 44:c1d8923072ba 180 "key2":"value2"
TMBOY 44:c1d8923072ba 181 },
TMBOY 44:c1d8923072ba 182 /*
TMBOY 44:c1d8923072ba 183 bot_state的取值
TMBOY 44:c1d8923072ba 184 0，根据da给出的intent，返回结果
TMBOY 44:c1d8923072ba 185 1，bot自己改写了intent（返回到了result.nlu里面），返回结果
TMBOY 44:c1d8923072ba 186 2、da返回的槽位值，bot认为有错，返回中给出了相应的错误提示
TMBOY 44:c1d8923072ba 187 3、bot不能响应intent，出了保底话术
TMBOY 44:c1d8923072ba 188 默认为0
TMBOY 44:c1d8923072ba 189 */
TMBOY 44:c1d8923072ba 190 "bot_state":0,
TMBOY 44:c1d8923072ba 191 //rank使用的字段，建议选填，key可以自定，排序的时候会看相关性高低
TMBOY 44:c1d8923072ba 192 "strategy":{
TMBOY 44:c1d8923072ba 193 "title":"标题",
TMBOY 44:c1d8923072ba 194 "content":"主要内容",
TMBOY 44:c1d8923072ba 195 "url":"http://www.baidu.com",//地址，可能会看来源的权威性
TMBOY 44:c1d8923072ba 196 "resource_type":"views,audio", //views和audio的组合，本条结果适合的场景，中控会根据当前应用场景和客户端类型来排序
TMBOY 44:c1d8923072ba 197 "is_valid_result":true,//默认为true，标识这条返回是保底的，还是真的有内容的
TMBOY 44:c1d8923072ba 198 }
TMBOY 44:c1d8923072ba 199 }
TMBOY 44:c1d8923072ba 200 }
TMBOY 44:c1d8923072ba 201
TMBOY 44:c1d8923072ba 202 ```
TMBOY 44:c1d8923072ba 203
TMBOY 44:c1d8923072ba 204
TMBOY 44:c1d8923072ba 205 ## bot配置（开放平台的输出）
TMBOY 44:c1d8923072ba 206 * 服务的host定义
TMBOY 44:c1d8923072ba 207 * protocol: https / http / nshead+mcpack
TMBOY 44:c1d8923072ba 208 * domain: 可以是ip/域名；如果是bns，需要设置domain_type
TMBOY 44:c1d8923072ba 209 * domain_type :"dns/bns", //可选，默认是dns
TMBOY 44:c1d8923072ba 210 * port: http默认80, https默认443
TMBOY 44:c1d8923072ba 211 * uri: 地址
TMBOY 44:c1d8923072ba 212 * 只有被定义在intents中，这个intent才会被转发给bot
TMBOY 44:c1d8923072ba 213 * event请求，根据schema中的interface字段和event的namespace，决定是否转发
TMBOY 44:c1d8923072ba 214
TMBOY 44:c1d8923072ba 215 ```javascript
TMBOY 44:c1d8923072ba 216 {
TMBOY 44:c1d8923072ba 217 "bot_id":"phone",
TMBOY 44:c1d8923072ba 218 "bot_meta":{ //下游bot元数据
TMBOY 44:c1d8923072ba 219 "description":"返回音乐类结果", // 文字描述
TMBOY 44:c1d8923072ba 220 "version":"1.0.0", //版本
TMBOY 44:c1d8923072ba 221 "type":"音乐" //TODO，bot类型见pm给的分类
TMBOY 44:c1d8923072ba 222 },
TMBOY 44:c1d8923072ba 223 //"url":"http://xiaodu.baidu.com:80/api/phone",
TMBOY 44:c1d8923072ba 224
TMBOY 44:c1d8923072ba 225 "protocol": "https / http / nshead+mcpack",
TMBOY 44:c1d8923072ba 226 "domain":"172.0.0.1", //可以是ip；如果是bns，要加domain_type
TMBOY 44:c1d8923072ba 227 "domain_type":"dns/bns", //可选，默认是dns
TMBOY 44:c1d8923072ba 228 "port":"8080", http默认80, https默认443
TMBOY 44:c1d8923072ba 229 "uri":"/saiya/search",
TMBOY 44:c1d8923072ba 230 //标识bot能接受哪些客户端事件
TMBOY 44:c1d8923072ba 231 "interface":{
TMBOY 44:c1d8923072ba 232 "AudioPlayer":{},
TMBOY 44:c1d8923072ba 233 },
TMBOY 44:c1d8923072ba 234 "intents": [
TMBOY 44:c1d8923072ba 235 {
TMBOY 44:c1d8923072ba 236 "intent": "phone",
TMBOY 44:c1d8923072ba 237 "slots": [
TMBOY 44:c1d8923072ba 238 {
TMBOY 44:c1d8923072ba 239 "name": "action_type",
TMBOY 44:c1d8923072ba 240 "type": "ACTION_TYPE"
TMBOY 44:c1d8923072ba 241 },
TMBOY 44:c1d8923072ba 242 {
TMBOY 44:c1d8923072ba 243 "name": "Date",
TMBOY 44:c1d8923072ba 244 "type": "AMAZON.DATE"
TMBOY 44:c1d8923072ba 245 }
TMBOY 44:c1d8923072ba 246 ]
TMBOY 44:c1d8923072ba 247 },
TMBOY 44:c1d8923072ba 248 {
TMBOY 44:c1d8923072ba 249 "intent": "GetLuckyNumbers"
TMBOY 44:c1d8923072ba 250 }
TMBOY 44:c1d8923072ba 251 ]
TMBOY 44:c1d8923072ba 252 }
TMBOY 44:c1d8923072ba 253 ```