### 3.4.4 时间询问 #### (1) 功能说明 时间询问功能支持报时、询问时间、日期、星期、农历、生肖;时间差计算、时间单位的换算;判断平闰年等;可识别日期、星期、农历、节日、今/明天等;给用户返回相应的时间结果。 #### (2) 接口说明 **请求方法** * POST **请求地址** * [http://api.ruyi.ai/v1/message](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=现在几点了](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": "d54ff04b-564e-4259-b54e-5528ec5893f1", "intents": [{ "parameters": { "time": "1481794490000", "city_from": "北京", "时刻": "几点", "city_from_raw": "北京", "service": "time" }, "action": "sys.action.time/equation", "name": "时间询问——没有城市默认北京时间", "result": { "delta_hour": 0, "day_week": "星期四", "date2": "12月15号", "hour2": "17点34分", "month": 12, "day": 15, "lunar_date": "猴年冬月十七", "lunar_year": "猴", "lunar_month": "冬", "lunar_day": "十七", "text": "北京时间:17点34分 ", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "北京时间:17点34分 " } }, { "type": "dialog", "property": { "text": "北京时间17点34分 ", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "55b1c7c2-8a3a-45f7-b67d-a79e3f4df851" }], "meta_process_milliseconds": 127 } } ``` **请求示例** (返回两个时刻的时间差,第一个时间缺省默认为当下时间) * [http://api.ruyi.ai/ruyi-api/v1/message?app\_key=APP\_KEY&user\_id=user0&q=到元旦还有几天](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": "9fe90626-3f41-4668-b151-f64d618a53f3", "intents": [{ "parameters": { "time2": "1483200000000", "service": "time" }, "action": "sys.action.time/diff", "name": "计算时间——单位日/天", "result": { "time2_day_week": "星期日", "lunar_date": "猴年腊月初四", "lunar_year": "猴", "lunar_month": "腊", "lunar_day": "初四", "time1": 1481794896468, "time2": 1483200000000, "timedelta": 1405103532, "timedeltaInSeconds": 1405103, "timedeltaInMinutes": 23418, "timedeltaInHours": 390, "timedeltaInDays": 16, "timedeltaInMonths": 1, "timedeltaInYears": 1, "text": " 16 天", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": " 16 天" } }, { "type": "dialog", "property": { "text": " 16 天", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "4ee1fcec-5b98-47a2-acbc-7a150fe531f6" }], "meta_process_milliseconds": 192 } } ``` **请求示例** (两个时间单位的换算) * [http://api.ruyi.ai/ruyi-api/v1/message?app\_key=APP\_KEY&user\_id=user0&q=一天是多少小时](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": "4a3eb94c-6939-4585-911c-5f5521477961", "intents": [{ "parameters": { "timedelta": "86400000", "service": "time" }, "action": "sys.action.time/diff", "name": "换算为——小时", "result": { "time2_day_week": "星期五", "lunar_date": "猴年冬月十八", "lunar_year": "猴", "lunar_month": "冬", "lunar_day": "十八", "time1": 1481795169975, "time2": 1481881569975, "timedelta": 86400000, "timedeltaInSeconds": 86400, "timedeltaInMinutes": 1440, "timedeltaInHours": 24, "timedeltaInDays": 1, "timedeltaInMonths": 0, "timedeltaInYears": 0, "text": " 24 小时", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": " 24 小时" } }, { "type": "dialog", "property": { "text": " 24 小时", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "1589baed-4831-47d4-89d7-3a5520f1f36b" }], "meta_process_milliseconds": 188 } } ``` **请求示例** (判断和闰年相关) * [http://api.ruyi.ai/ruyi-api/v1/message?app\_key=APP\_KEY&user\_id=user0&q=今年2月有多少天](http://api.ruyi.ai/ruyi-api/v1/message?app_key=APP_KEY&user_id=user0&q=今年2月有多少天) 返回结果 ```json { "code": 0, "msg": "ok", "result": { "_text": "今年2月有多少天", "msg_id": "97b5b66d-bf48-427b-80eb-2f2bd30fe941", "intents": [{ "parameters": { "year": "2016", "service": "time" }, "action": "sys.action.time/leapyear", "name": "判断二月有多少天", "result": { "year": "2016", "leapyear": "yes", "pre_leapyear": 2012, "next_leapyear": 2020, "text": "2016年 是闰年,二月有29天。", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "2016年 是闰年,二月有29天。" } }, { "type": "dialog", "property": { "text": "2016年 是闰年,二月有29天。", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "75bab6f7-0300-4d8d-a8c5-4acbb34a96e9" }], "meta_process_milliseconds": 156 } } ``` **详细参数说明** | 名称 | 类型 | 说明 | | :--- | :--- | :--- | | service | String | 服务名称 | | time | String | 识别的时间戳,Unix 格式 | | city\_from | String | 第一个城市 | | city\_t | String | 第二个城市 | | delta\_hour | String | 时差 | | day\_week | String | 星期几 | | date2 | String | 返回日期 | | hour2 | String | 返回时刻 | | month | String | 月份 | | day | String | 几号 | | lunar\_date | String | 农历日期 | | lunar\_year | String | 生肖 | | lunar\_month | String | 农历月份 | | lunar\_day | String | 农历几号 | | timedelta | Integer | 时间差,单位毫秒 | | timedeltaInSeconds | Integer | 时间差,单位秒 | | timedeltaInMinutes | Integer | 时间差,单位分钟 | | timedeltaInHours | Integer | 时间差,单位小时 | | timedeltaInDays | Integer | 时间差,单位天 | | timedeltaInMonths | Integer | 时间差,单位月 | | timedeltaInMonths | Integer | 时间差,单位年 |