### 3.2.2 词汇乐园 #### (1) 功能说明 专门为低龄儿童开发的一款词汇小游戏,通过唤醒语“词汇乐园”进入游戏,开始时可以从水果、形状、颜色、动物、蔬菜五个类别下选择其中一种,进行词汇练习,当用户给出的词语匹配到词库中的词语,机器人会给出相应的解释,同时给出一个新的词语。依次进行直到游戏结束或用户主动退出。 #### (2) 接口说明 **请求方法** * POST **请求地址** * http://api.ruyi.ai/v1/message **请求参数说明** |参数名 |参数类型 | 是否必须 |参数说明 | :-----| :---| :---:|:----- |q |String| 是| 自然语言表达,例如“词汇乐园" |app_key| String|是 |应用开发者秘钥,注册开发者后台账号,建立虚拟助理后获得 |user_id |String| 是 |用户唯一标识,便于支持个性化语义解析。建议开发者使用 UUID 字符,且不同用户必须用不同的 user_id,防止意图串。 #### (3)返回说明 **返回参数说明** |名称 |类型| 说明 |:---|:---|:--- |code |Integer | 返回代码 |msg | String |返回代码描述 |parameters|JSON Object |解析到的实体以及服务说明 |action|String|服务的接口名称 |name| String|匹配的意图名称 |result | JSON Object| 接口返回内容 |outputs| Array| 服务输出结果,微信端使用 type 类型为 wechat 开头的内容;硬件端收到所有内容,依据需求解析使用 **返回代码说明** |返回代码 |错误类型|说明 |:---|:---|:--- |0/200 |成功 |请求成功 |400 |无效请求 |某些必需参数缺失或参数值错误,详见msg字段 |401 |未授权 |授权失败,app_key缺失或错误 |403 |请求被禁止|有效请求,但服务拒绝响应,请联系contact@ruyi.ai |408 |请求超时 |请求响应超时,一般响应时间设置为2000ms以内 |429 |短时间内大量访问 |短时间内请求数过多 |500 |内部错误 |服务处理异常 |503 |服务不可用|服务异常或正在维护 #### (4)请求示例 **请求范例** _词汇乐园;水果_ _苹果_ _果果(不正确词语)_ _重复_ _退出_ **请求示例正确** (说出正确的词语) * http://api.ruyi.ai/ruyi-api/v1/message?app_key=APP_KEY&user_id=user0&q=苹果 返回结果 ```json { "code": 0, "msg": "ok", "result": { "_text": "苹果", "msg_id": "0cfe2767-60f3-41c5-b17f-45bb9d625c31", "intents": [{ "parameters": { "tag1": "水果", "text": "苹果", "score": "0", "numChanceLeft": "1", "game-status": "playing", "service": "cihuileyuan" }, "action": "sys.action.game/cihuileyuan/play", "name": "词汇-游戏开始", "result": { "lastQuestion": "桔子", "lastAnswer": "桔子", "lastExplanation": "桔子红桔子黄,桔子好象金铃铛。", "explanationUserSay": "小苹果红彤彤,咬一口满嘴甜。", "score": 1, "totalNumUserSay": 1, "numChanceLeft": 1, "prevQuestion": "桔子", "prevAnswer": "桔子", "prevResult": "1", "isRightAnswer": true, "totalNumQuestion": 2, "text": "我知道苹果,小苹果红彤彤,咬一口满嘴甜。我想到个词:桔子,该你了。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "我知道苹果,小苹果红彤彤,咬一口满嘴甜。我想到个词:桔子,该你了。" } }, { "type": "dialog", "property": { "text": "我知道苹果,小苹果红彤彤,咬一口满嘴甜。我想到个词:桔子,该你了。", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "d6230319-411c-4a02-93ec-021df41df254" }], "meta_process_milliseconds": 66 } ``` **请求示例错误** (不是词语或不是该类别下的词语) * http://api.ruyi.ai/ruyi-api/v1/message?app_key=APP_KEY&user_id=user0&q=果果 返回结果 ```json { "code": 0, "msg": "ok", "result": { "_text": "果果", "msg_id": "1561bcaa-e96e-4aef-a77f-2856e078791a", "intents": [{ "parameters": { "tag1": "水果", "text": "果果", "score": "2", "numChanceLeft": "1", "game-status": "playing", "service": "cihuileyuan" }, "action": "sys.action.game/cihuileyuan/play", "name": "词汇-玩游戏1", "result": { "lastQuestion": "油桃", "lastAnswer": "油桃", "lastExplanation": "小油桃没有毛,粉红皮甜甜肉。", "explanationUserSay": "", "score": 2, "totalNumUserSay": 1, "numChanceLeft": 1, "prevQuestion": "油桃", "prevAnswer": "油桃", "prevResult": "0", "isRightAnswer": false, "totalNumQuestion": 2, "text": "没听过这个词呢,或许我还没学到,请换一种水果吧!", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "没听过这个词呢,或许我还没学到,请换一种水果吧!" } }, { "type": "dialog", "property": { "text": "没听过这个词呢,或许我还没学到,请换一种水果吧!", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "329b76d5-f132-4b12-a052-eeac9794d6f7" }], "meta_process_milliseconds": 106 } } ``` **请求示例重复** (机器人重复刚才的回答) * http://api.ruyi.ai/ruyi-api/v1/message?app_key=APP_KEY&user_id=user0&q=重复 返回结果 ```json { "code": 0, "msg": "ok", "result": { "_text": "重复", "msg_id": "72e4d2ee-ff0d-4150-bd04-0a2272f4e55e", "intents": [{ "parameters": { "tag1": "水果", "score": "1", "game-status": "playing", "explanationUserSay": "小苹果红彤彤,咬一口满嘴甜。", "lastQuestion": "蓝莓", "text": "苹果", "service": "cihuileyuan" }, "action": "sys.action.game/cihuileyuan/repeat", "name": "词汇-游戏开始-重复", "result": { "explanationUserSay": "小苹果红彤彤,咬一口满嘴甜。", "lastQuestion": "蓝莓", "score": 1, "text": "我知道苹果 ,小苹果红彤彤,咬一口满嘴甜。我想到个词:蓝莓,该你了。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "我知道苹果 ,小苹果红彤彤,咬一口满嘴甜。我想到个词:蓝莓,该你了。" } }, { "type": "dialog", "property": { "text": "我知道苹果 ,小苹果红彤彤,咬一口满嘴甜。我想到个词:蓝莓,该你了。", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "7bc4c27f-1299-41e3-ba50-26dab7208beb" }], "meta_process_milliseconds": 37 } } ``` **请求示例退出** (退出游戏并返回分数) * http://api.ruyi.ai/ruyi-api/v1/message?app_key=APP_KEY&user_id=user0&q=退出 返回结果 ```json { "code": 0, "msg": "ok", "result": { "_text": "退出 ", "msg_id": "50f17009-0d10-4404-be36-550c9fc11c89", "intents": [{ "parameters": { "tag1": "水果", "score": "1", "game-status": "over", "totalNumQuestion": "2", "service": "cihuileyuan" }, "action": "0", "name": "词汇-退出", "result": { "text": "你在水果乐园中说对了1个水果,不错哦!欢迎下次再玩词汇乐园。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "你在水果乐园中说对了1个水果,不错哦!欢迎下次再玩词汇乐园。" } }, { "type": "dialog", "property": { "text": "你在水果乐园中说对了1个水果,不错哦!欢迎下次再玩词汇乐园。", "emotion": "happy" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "4ac54f40-dd04-48cf-8a13-39cf41a604fa" }], "meta_process_milliseconds": 39 } } ``` **详细参数说明** |名称 |类型| 说明 |:---|:---|:--- |service|String|服务名称 |tag|String |所选类别名称 |score|String|分数 |numChanceLeft|Integer|剩余回答次数 |game-status|String|游戏状态 |lastQuestion|String|上一个词语 |lastAnswer|String|上一个词语,同 lastQuestion |lastExplanation|String|上一个词语解释 |explanationUserSay|String|用户所说词汇的解释 |totalNumUserSay|Integer|用户进行几轮对话 |prevQuestion|String|上一个词语,同 lastQuestion |prevAnswer|String|上一个词语,同 lastQuestion |prevResult|String|上次回答结果,1则为正确 |isRightAnswer|Boolean|上次回答结果,true 则为正确 |totalNumQuestion|Integer|问题总数 **指令清单** | 指令名称 | 范例 | | :--- | :--- | | 唤醒| 词汇乐园| | 选择类型| 水果| | 说词语| 苹果| | 重复| 重复| | 退出| 退出|