bowen liu
ex
Fork of
mbed-os-example-mbed5-blinky
by 
mbed-os-examples
Diff: dumi_doc-master/doc/BOTAPI2.0_README.md
- Revision:
- 44:c1d8923072ba
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/dumi_doc-master/doc/BOTAPI2.0_README.md Tue Jul 18 16:27:22 2017 +0800
@@ -0,0 +1,253 @@
+# 度秘开放平台-BotApi2.0接口说明
+
+## Table of Contents
+
+
+ * [度秘开放平台-BotApi2.0接口说明](#度秘开放平台-botapi20接口说明)
+ * [Table of Contents](#table-of-contents)
+ * [交互模式说明](#交互模式说明)
+ * [关于confirm的说明](#关于confirm的说明)
+ * [请求格式](#请求格式)
+ * [未来的响应格式](#未来的响应格式)
+ * [bot配置（开放平台的输出）](#bot配置开放平台的输出)
+
+
+## 交互模式说明
+
+### 关于confirm的说明
+
+
+ * 之所以有confirm请求，是因为us会把同一个请求发给多个bot，然后挑选较好的一个。bot返回的结果，有可能不被使用
+ * 按bot对请求的处理有无副作用，分为幂等请求和非幂等请求
+ * 幂等请求如：
+ * 通用信息
+ * 天气
+ * 非幂等请求如：
+ * 提醒（bot会为用户创建提醒）
+ * 打车（bot会帮用户叫车）
+
+
+## 请求格式
+
+```javascript
+{
+ "version": 2,
+ "query":"", //query，可能已经经过了改写
+ "raw_query":"", //原始query，可选
+ "content_type": "image",//可选，默认是txt
+ "user_id":"", //对bot来说，可以唯一标识一个用户的string
+
+ "cuid":"", //设备id，可选
+ "dumi_id":"", //度秘登录用户id，可选
+ "baidu_uid":"", //百度登录后的passport id，可选
+ "bot_id":"",//把bot_id带下来，其实可以不看
+
+ "log_id":"5969bdd5126d493387a6b127d8c45ce7",
+ "confirm":1,//0或者1，0代表可能不会使用bot的返回结果，1代表肯定会使用bot的返回结果。（参考上面的[关于confirm的说明]）
+
+ "query_type":"1",//请求类型，标识用户发这个请求的方法，参见文档 http://agroup.baidu.com/dbo/md/article/49113
+ "client_info":{
+ "device_interface":{
+ "Alerts":{},
+ "AudioPlayer":{},
+ "PlaybackController":{},
+ "Speaker":{},
+ "Settings":{},
+ "System":{}
+ }, //设备支持的接口（包含directive、event等整套实现）
+
+ "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":{
+ "audio_item_id":"xxx",//正在播放的音频流id
+ "offsetInMilliseconds":20000,//播放到多少ms了
+ "playerActivity":"IDLE PAUSED PLAYING BUFFER_UNDERRUN FINISHED STOPPED"
+ },
+ },
+ "operation_system":"android",
+ "operation_system_version":"5.0",
+ "from_client":"sdk",// sdk/na/shoubai
+ "appid":"appid",
+ "appkey":"appkey",
+ "device_brand":"apple", //设备品牌 （目前只有对外sdk有该字段），ios写死"apple"，安卓取android.os.Build.BRAND
+ "device_model":"iphone 6s", //设备具体型号 （目前只有对外sdk有该字段）ios取 设备型号字符串
+ "ua":"",//可选，浏览器的user agent
+ "app_ver":"1.0.0"
+ },
+
+ //完整的地址信息
+ "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": "百度科技园内"
+ },
+
+ "session": {//是上次user_id + bot_id 请求的返回值里的session，纯kv，内部结构不做限制（串行化保存的值）
+ "key":"value",
+ "key2":"value2"
+ },
+ //用户常驻地址，可选，字段和上面location一致
+ "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": "百度科技园内" },
+ //最近几次访问的地址，可选，一个数组，每个元素里面的结构和location 一致
+ "last_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": "百度科技园内" },
+ { "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": "百度科技园内" },
+ ],
+
+ //da解析结果，对一个query可能有多种理解，所以是一个数组
+ "nlu_list":[
+ {"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"}},
+ {"score":100,"domain":"duer_weather","intent":"sys_weather","slots":{"loc_city":"九江市","loc_county":"九江市","loc_province":"江西省","time":"2017-01-03,2017-01-03"}},
+ ],
+ //其他da解析结果，会放服务的原始返回，比如分词、语法分析之类的结果
+ "nlu_extend":{
+ "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"
+ "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}]}"
+ },
+}
+```
+
+## 未来的响应格式
+
+里面的result结构中的views、resource、nlu、speech、directives、hint都和对外输出的格式里的定义一致，详细结构可见([度秘API2.0文档](http://gitlab.baidu.com/wangpeng20/dumi_schema/blob/master/doc/OPENAPI_README.md))
+
+```javascript
+{
+ "status" : 0, //0 success，other fail
+ "version": 2,
+ "msg" : "string", //status 0，msg "success"，status not 0，msg explaining reason
+ "need_confirm":1, //可选，默认为0，参考前面的[关于confirm的说明]
+ "data" : {
+ //如果bot没有召回结果，就不要返回result结构了
+ "result":{
+ //必选
+ "views":[],
+ //可选
+ "resource":{},
+ //应该从请求的nlus里选一条返回,可选
+ "nlu":{"domain":"duer_weather","intent":"sys_weather","slots":{"loc_city":"九江市","loc_county":"九江市","loc_province":"江西省","time":"2017-01-03,2017-01-03"}},
+ //必选
+ "speech":{},
+ //可选
+ "directives":[],
+ //可选
+ "hint":[],
+ //可选，默认为true，如果为false，客户端应该立即进入收听用户query的状态，不用重新唤醒
+ 'should_end_session':false,
+ },
+ //会被串行化后保存起来，下次同一个 (user_id,bot_id) 请求的时候，会带上
+ "session":{
+ "key":"value",
+ "key2":"value2"
+ },
+ /*
+ bot_state的取值
+ 0，根据da给出的intent，返回结果
+ 1，bot自己改写了intent（返回到了result.nlu里面），返回结果
+ 2、da返回的槽位值，bot认为有错，返回中给出了相应的错误提示
+ 3、bot不能响应intent，出了保底话术
+ 默认为0
+ */
+ "bot_state":0,
+ //rank使用的字段，建议选填，key可以自定，排序的时候会看相关性高低
+ "strategy":{
+ "title":"标题",
+ "content":"主要内容",
+ "url":"http://www.baidu.com",//地址，可能会看来源的权威性
+ "resource_type":"views,audio", //views和audio的组合，本条结果适合的场景，中控会根据当前应用场景和客户端类型来排序
+ "is_valid_result":true,//默认为true，标识这条返回是保底的，还是真的有内容的
+ }
+ }
+}
+
+```
+
+
+## bot配置（开放平台的输出）
+ * 服务的host定义
+ * protocol: https / http / nshead+mcpack
+ * domain: 可以是ip/域名；如果是bns，需要设置domain_type
+ * domain_type :"dns/bns", //可选，默认是dns
+ * port: http默认80, https默认443
+ * uri: 地址
+ * 只有被定义在intents中，这个intent才会被转发给bot
+ * event请求，根据schema中的interface字段和event的namespace，决定是否转发
+
+```javascript
+{
+ "bot_id":"phone",
+ "bot_meta":{ //下游bot元数据
+ "description":"返回音乐类结果", // 文字描述
+ "version":"1.0.0", //版本
+ "type":"音乐" //TODO，bot类型见pm给的分类
+ },
+ //"url":"http://xiaodu.baidu.com:80/api/phone",
+
+ "protocol": "https / http / nshead+mcpack",
+ "domain":"172.0.0.1", //可以是ip；如果是bns，要加domain_type
+ "domain_type":"dns/bns", //可选，默认是dns
+ "port":"8080", http默认80, https默认443
+ "uri":"/saiya/search",
+ //标识bot能接受哪些客户端事件
+ "interface":{
+ "AudioPlayer":{},
+ },
+ "intents": [
+ {
+ "intent": "phone",
+ "slots": [
+ {
+ "name": "action_type",
+ "type": "ACTION_TYPE"
+ },
+ {
+ "name": "Date",
+ "type": "AMAZON.DATE"
+ }
+ ]
+ },
+ {
+ "intent": "GetLuckyNumbers"
+ }
+ ]
+}
+```