詞匯樂園 · ruyi.ai開發者文檔

### 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|問題總數 **指令清單** | 指令名稱 | 范例 | | :--- | :--- | | 喚醒| 詞匯樂園| | 選擇類型| 水果| | 說詞語| 蘋果| | 重復| 重復| | 退出| 退出|