### 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|查询诗的最后一句