### 3.4.3 古詩詞 #### （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": "4248d294-13bb-4b52-8f41-b1ebb9dfb6a9", "intents": [{ "parameters": { "q": "舉頭望明月", "service": "poem" }, "action": "sys.action.poem/search", "name": "知道一個詩句，返回作者、標題、全詩", "result": { "title": "靜夜思", "cat_chaodai": "唐", "poem": "床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。", "author": "李白", "author_detail": "李白（701－762）當然是大家公認的我國古代最偉大的天才詩人之一，大多數人認為他同時也是一位偉大的詞人。他祖籍隴西（今甘肅），一說生于中亞，但少年時即生活在蜀地，壯年漫游天下，學道學劍，好酒任俠，笑傲王侯，一度入供奉，但不久便離開了，后竟被流放到夜郎（今貴州）。他的詩，想象力“欲上青天攬明月”，氣勢如“黃河之水天上來”，的確無人能及。北宋初年，人們發現《菩薩蠻》“平林漠漠煙如織”和《憶秦娥》“秦娥夢斷秦樓月”兩詞，又尊他為詞的始祖。有人懷疑那是后人所托，至今聚訟紛紜。其實，李白的樂府詩，當時已被之管弦，就是詞的濫觴了。至于歷來被稱為“百代詞曲之祖”的這兩首詞，格調高絕，氣象闊大，如果不屬于李白，又算作誰的作品為好呢？", "score": 2, "isRandom": false, "prevSentence": "疑是地上霜", "nextSentence": "低頭思故鄉", "firstSentence": "床前明月光", "lastSentence": "低頭思故鄉", "text": "李白的《靜夜思》：床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "李白的《靜夜思》：床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。" } }, { "type": "dialog", "property": { "text": "李白的《靜夜思》：床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。", "emotion": "worry" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "c7d7d3e2-9f3c-4966-abc2-7948f8ceb666" }], "meta_process_milliseconds": 87 } } ``` **請求示例** (通過詩人和詩名查詢） * 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": "e8fdd83b-b001-48fb-ad19-6430b246b3e5", "intents": [{ "parameters": { "author": "李白", "title": "靜夜思", "service": "poem" }, "action": "sys.action.poem/search/authortitle", "name": "知道作者以及標題，返回作者、標題、全詩", "result": { "title": "靜夜思", "cat_chaodai": "唐", "poem": "床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。", "author": "李白", "author_detail": "李白（701－762）當然是大家公認的我國古代最偉大的天才詩人之一，大多數人認為他同時也是一位偉大的詞人。他祖籍隴西（今甘肅），一說生于中亞，但少年時即生活在蜀地，壯年漫游天下，學道學劍，好酒任俠，笑傲王侯，一度入供奉，但不久便離開了，后竟被流放到夜郎（今貴州）。他的詩，想象力“欲上青天攬明月”，氣勢如“黃河之水天上來”，的確無人能及。北宋初年，人們發現《菩薩蠻》“平林漠漠煙如織”和《憶秦娥》“秦娥夢斷秦樓月”兩詞，又尊他為詞的始祖。有人懷疑那是后人所托，至今聚訟紛紜。其實，李白的樂府詩，當時已被之管弦，就是詞的濫觴了。至于歷來被稱為“百代詞曲之祖”的這兩首詞，格調高絕，氣象闊大，如果不屬于李白，又算作誰的作品為好呢？", "isRandom": false, "text": " 李白的《靜夜思》：床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": " 李白的《靜夜思》：床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。" } }, { "type": "dialog", "property": { "text": " 李白的《靜夜思》：床前明月光，疑是地上霜。舉頭望明月，低頭思故鄉。", "emotion": "worry" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "844078bd-7498-4503-aec7-290ddadca52b" }], "meta_process_milliseconds": 164 } } ``` **請求示例** （隨機返回某首詩） * 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": "6d6e69ae-5f31-4c27-a437-da7fe78ffd4f", "intents": [{ "parameters": { "背": "背首", "詩": "詩", "service": "poem" }, "action": "0", "name": "給我背首詩（偽隨機）", "result": { "text": "李商隱的《登樂游原》：向晚意不適，驅車登古原。夕陽無限好，只是近黃昏。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "沒問題！杜牧的《山行》：遠上寒山石徑斜，白云生處有人家。停車坐愛楓林晚，霜葉紅于二月花。" } }, { "type": "dialog", "property": { "text": "沒問題！王維的《紅豆》：紅豆生南國，春來發幾枝。愿君多采擷，此物最相思。", "emotion": "positive" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "e5e807af-e378-4353-8ae7-b96ba71346e8" }], "meta_process_milliseconds": 100 } } ``` **詳細參數說明** |名稱 |類型| 說明 |:---|:---|:--- |service| String |服務名稱 |q|String|識別的詩句 |title |String |詩名 |cat_chaodai|String |詩人的朝代 |poem|String|整首詩 |author_detail|String|詩人信息 |isRandom|Boolean|返回是否隨機，true 則為隨機 |prevSentence|String|查詢詩句的上一句 |nextSentence|String|查詢詩句的下一句 |firstSentence|String|查詢詩的第一句 |lastSentence|String|查詢詩的最后一句