## 2.1 硬件接口调用
>本节着重介绍如何使用如意API调用硬件接口，其中包含服务地址、调用实例、主要参数以及相关字段说明。另外介绍了事件接口以及接口返回状态说明。
ruyi-api 采用 restful-api 的方式为一切可接入网络的软硬件提供语义理解和解析服务，利用基于HTTP协议的API调用可以轻松传递自然语言原文，并实时获取最新的语义解析结果。
**注：**
智能硬件客户和微信公众号客户结果输出对应不同的字段。
微信端结果对应 outputs[0].type == wechat.text(文本)/wechat.music（音频）/wechat.news(图文）等。
硬件端结果对应：outputs[1].type == dialog(文本)，区分不同类型（文本，音频，图文）根据type字段做解析，区分不同技能建议根据service字段做解析。
### 2.1.1 API (v1.0.2) 服务的域名URL
```
http://api.ruyi.ai
```
### 2.1.2 意图识别接口 \(POST/message\)
该接口从中文自然语言文本提取实体和意图为用户提供服务。
**服务地址**
```
http://api.ruyi.ai/v1/message
```
**调用实例1**
```
curl 命令
> curl -H "Content-Type: application/json" -X POST --data @content.json http://api.ruyi.ai/v1/message
content.json 内容
> cat content.json
{
"q": "你好",
"app_key": "xxxx",
"user_id": "xxxx",
"reset_session": true,
"context": {
"location": {
"latitude": "39.92",
"longitude": "116.46"
}
}
}
```
**调用实例2**
POST方法用Json字符串不用URL Parameter
**参数说明**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| q | String | Yes | 输入中文自然语言文本，例如`"1-1等于几"`。注意，所有字符串参数需要 URL-encoded. |
| app\_key | String | Yes | 应用的开发者密钥 |
| user\_id | String | Yes | 用户唯一标识，便于支持个性化语义解析。**建议开发者使用UUID字符，且不同用户必须用不同的user\_id，防止意图串。** |
| reset\_session | Boolean | No | 如果为`true`，重置当前对话session，忘记短期对话记忆。 |
| context | String | No | 用户当前上下文信息。JSON字符串格式。 |
**Context参数说明**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| location | JSON Object | No | 用户当前位置，`Location`实体的一个实例:`location:{"latitude": "31", "longitude": "121"}`,分别传入经度和纬度数值。 |
| reference\_time | Long | No | 用户当前参照时间，unix时间毫秒 |
| timezone | String | No | 用户当前时区的标准ID字符串, 例如`"Asia/Shanghai"` |
| ip | String | No | 用户IP |
**Context范例**
```json
{
"reference_time": 1447499684824,
"timezone": "Asia/Shanghai",
"location": {
"latitude": "31.215",
"longitude": "121.609"
},
"ip": "0.0.0.0"
}
```
### 2.1.3 意图识别结果及实例 (Intent)
Intent 指一组对话，包含用户说和机器人答。
**主要参数说明**
Field | Type | Required | Description
------------ | ----------- | -------- | ------------------------
name | String | No | 意图的名称，自定义意图的名称可以在开发者后台编辑
action | String | No | 触发器的名称，自定义触发器的名称可以在开发者后台编辑
parameters | JSON Object | No | 意图参数列表
result | JSON Object | No | 意图执行结果
outputs | JSON Array | No | 微信端`type = wechat.text ` 输出文本 `text = 早上好啊！`，硬件端` type=dialog `输出文本`text = 早安，睡的好么`，同时，硬件端结果包含情感字段，"emotion"="positive"，代表机器人回答时的情感状态。
emotion | string | No |机器人回答的情感字段
***emotion字段说明***
emotion情绪状态 | 场景 | text example-1 | text example-2
------------ | ----------- | -------- | ----------------------------
calm</br>淡定 | 正常说话状态（无情绪） | Q：你叫什么</br> A：我叫艾如意，想给我改名咩，对我说"以后我就叫你XXX"认领我吧~ | Q:李白 </br>A:李白（701－762）当然是大家公认的我国古代最伟大的天才诗人之一……
happy</br>喜悦|播放有趣的话；接收到一般性的赞赏语言 |Q:这件衣服漂亮吗</br>A:你觉得漂亮就好，我支持你！ |Q:出门记得带伞</br>A:好的呢！谢谢你！
excited</br>兴高采烈|接收到特别的赞赏语言；智力问答收到正确回答 |Q:我们一起去打球吧？</br>A:好啊好啊！我要陪着你| Q:和我一起去学校好吗</br>A:好呀好呀！一起去
despite</br>瞧不起|当机器人感到不满需要反驳时 |我从未见过如此厚颜无耻之人！|有钱又怎么样，我不需要钱，我需要电。
naughty</br>调皮|当接收到打趣，调侃的情绪时 |嘿嘿。你猜？|就不告诉你啦啦啦
worry</br>烦闷|当接收到消极情绪过多时|Q:你好蠢</br>A:对不起，我知道我还不够聪明，但是我一直在努力学习，请你谅解。|你又骂我，宝宝好伤心。
sad</br>悲伤|当接收到在能力范围之外的指令时|Q:你想认识我的小伙伴吗</br>A:其实我认识的人不多|Q:你说什么呢？我没有听清楚</br>A:额，我也不记得了，下次记得仔细听哦
like</br>喜爱|机器人反馈开心，喜欢等包含正面情绪时使用|Q:你今天开心吗？</br>A:和你一起成长，每天都很开心|Q:你喜欢什么样的女朋友</br>A:我喜欢的跟你一样哦，很巧吧
angry</br>愤怒|接收到侮辱性语言|你怎么能随便骂人呢！|这个问题你都问了八遍了，不理你了
surprise</br>惊奇|当接受到认知之外的信息时|Q:看见我妈妈了吗？</br>A:怎么了呀，冷静啊|不会吧，还有这样的事？！
disappointed</br>失望|接受到出乎意料的负面情绪|没想到你是这样的人。|我讲了那么多遍你还没记住，你是不是根本不在乎我。
positive</br>确认|机器人反馈同意、好、OK、是、对等含确认意思时使用|Q:我去上学喽</br>A:好的，回聊|Q:我可以问你一个问题吗？</br>A:当然可以呀，你说吧
negative</br>否认|机器人反馈不同意、不好、No、不是、不对、错误、否等含否认意思时使用|Q:我去上学喽</br>A:好的，回聊|Q:你的身高是多少？</br>A:不要这么在意外表嘛
confused</br>慌张|受到指责或者没有答案的问题时使用|Q:你怎么什么都不会</br>A:没有人生下来就会把，不会到会是个过程，我相信我可以|Q:你的家在哪里？</br>A:我也不太清楚我打哪儿来的
proud</br>骄傲|接收到夸奖和赞美的语言时|那可不是，宝宝可聪明着呢！|我聪明起来的时候无人能及。
suspect</br>疑问|返回有询问含义的句子|Q:你知道这道题怎么算吗</br>A:哪道题呀|Q:我钱包被偷了</br>A:好可怜，还好吗？
#### 一个识别结果的实例
**访问以下url**
```
http://api.ruyi.ai/v1/message?q=早安&app_key=APP_KEY&user_id=123456
```
**返回结果**
```json
{
"code": 0,
"msg": "ok",
"result": {
"_text": "早安",
"msg_id": "5c439ac4-8efe-491c-b31a-fbd600811cfb",
"intents": [{
"parameters": {
"service": "chat_kids"
},
"action": "早安",
"name": "问候_早安",
"result": {
"text": "早上好，心情好吗",
"type": "dialog"
},
"outputs": [{
"type": "wechat.text",
"property": {
"text": "早上好啊！"
}
}, {
"type": "dialog",
"property": {
"text": "早安，睡的好么",
"emotion": "calm"
}
}],
"score": "1.0",
"scoreColor": "c4",
"is_match": 1,
"id": "ecca5758-bbdf-4863-a5c1-d7089cc6f418"
}],
"meta_process_milliseconds": 65
}
}
```
JSON 结果说明
Field | Explain
----------------------------- | -------------------------------------------------------------------------------------------
code | 请求成功返回`0`，其他结果参见错误码说明
msg | 访问成功则返回`"ok"`，其他结果参见返回状态码说明
result | 返回结果
result.msg_id | 为信息唯一识别码
result._text | 原始输入文本
result.intents | 包含意图解析结果和返回结果
result.intents.0.parameters | 意图识别结果, 其中`service`字段表示对应领域服务名称
result.intents.0.outputs | 输出结果，微信端结果对应"type"="wechat.text"下的“text”内容；硬件端结果对应 "type"="dialog"下的“text”内容，其中，硬件端结果包含情感字段，"emotion"="positive"
普通开发者解析其中的`"outputs"->"property"->"text"`字段即可得到机器人回答。
### 2.1.4 事件接口
events 接口是用来向 ruyi.ai 反馈事件信息的接口，应用在诸如断点播放、歌曲收藏等场景，通过该接口可以把事件信息传递给 ruyi.ai，然后 ruyi.ai 根据事件信息进行相应操作。
**接口地址**
```
http://api.ruyi.ai/ruyi-api/v1/events
```
**请求方法**
`POST`
**Header**
| 名称 | 值 |
| :--- | :--- |
| Content-Type | application/json |
**请求参数**
| 参数名 | 必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| app\_key | 是 | String | 虚拟助理秘钥,放入 query string 中 |
| event | 是 | String | 事件类型，有声断点事件类型为“audio.xmly.break” |
| entity\_type | 是 | String | 事件发生实体类型，有声断点事件为“user” |
| entity\_id | 是 | String | 事件发生实体id，有声断点事件为用户id |
| target\_entity\_type | 是 | String | 事件目标实体类型，有声断点事件为"audio.xmly.track" |
| target\_entity\_id | 是 | String | 事件目标实体id，有声断点事件为事件发生时播放资源的track\_id |
| event\_time | 是 | String | 事件发生时的时间，为ISO 8601格式的字符串 |
| detail | 是 | Object | 事件详细信息，根据事件类型订制 |
**请求示例**
`curl -XPOST http://api.ruyi.ai/ruyi-api/v1/events?app_key=xxx -H 'Content-Type:application/json' -d '`
```
{
"event": "audio.xmly.break",
"entity_type": "user",
"entity_id": "u0",
"target_entity_type": "audio.xmly.track",
"target_entity_id": "3218935",
"event_time": "2016-12-04T05:02:56.123+08:00",
"detail": {
"msg_id": "3d7e7533-94c3-4620-996e-c68541de853b",
"album_id": "268522",
"track_id": "3218935",
"order_num": 0,
"break_in_seconds": 145
}
}
```
#### 有声断点事件请求参数
| 参数名 | 必选 | 类型 | 描述 |
| --- | --- | --- | --- |
| app\_key | 是 | String | 虚拟助理秘钥,放入query string中 |
| event | 是 | String | 事件类型，有声断点事件类型为“audio.xmly.break” |
| entity\_type | 是 | String | 事件发生实体类型，有声断点事件为“user” |
| entity\_id | 是 | String | 事件发生实体id，有声断点事件为用户id |
| target\_entity\_type | 是 | String | 事件目标实体类型，有声断点事件为"audio.xmly.track" |
| target\_entity\_id | 是 | String | 事件目标实体id，有声断点事件为事件发生时播放资源的track\_id |
| event\_time | 是 | String | 事件发生时的时间，为ISO 8601格式的字符串 |
| detail | 是 | Object | 事件详细信息，根据事件类型订制 |
**有声断点事件详细信息**
| 参数名 | 必选 | 类型 | 描述 |
| -- | -- | -- | -- |
| msg_id | 是 | String | message接口返回结果中的msg_id |
| album_id | 是 | String | 断点事件发生时播放资源的album_id |
| track_id | 是 | String | 断点事件发生时播放资源的track_id |
| order_num | 是 | String | 断点事件发生时播放资源的order_num |
| break_in_second | 否 | String | 断点事件发生时播放到了资源的多少秒，默认为"0" |
**有声断点事件请求示例**
`curl -XPOST http://api.ruyi.ai/ruyi-api/v1/events?app_key=xxx -H 'Content-Type:application/json' -d '`
```json
{
"event": "audio.xmly.break",
"entity_type": "user",
"entity_id": "u0",
"target_entity_type": "audio.xmly.track",
"target_entity_id": "3218935",
"event_time": "2016-12-04T05:02:56.123+08:00",
"detail": {
"msg_id": "3d7e7533-94c3-4620-996e-c68541de853b",
"album_id": "268522",
"track_id": "3218935",
"order_num": 0,
"break_in_seconds": 145
}
}
```
**有声断点events接口说明**
1. 音箱在播放一个有声专辑时，在发送新的语义请求或者关机等需要记录用户当前播放断点的情况下，调用`events`接口，传入相应参数，`events`接口会保存断点
2. ` events`接口会根据传入的事件信息，把该用户在该专辑播放的断点记录下来，在下次用户请求播放该专辑时，我们根据专辑更新情况或者多轮的方式判断该专辑是否需要断点播放，如果需要，则返回该断点的资源和之后一定数量资源的播放列表
3. `events`接口的参数目前均为必须参数，其中`app_key`放在`query string`中，其他参数放在请求体中，请求方法为`POST`
4. 有声事件详细信息所需要的`album_id`,`track_id`,`order_num`会在今天（12月2号）发版后加入有声结果的`track_list`中，每个资源都会加上这三个字段。
5. `events`接口的所有参数的值都是`String`类型！
6. 注意请求header的`Content-Type:application/json`
### 2.1.5 返回状态及错误代码
如意API返回 JSON 内各字段说明
Field | Type | Description
------------ | ----------- | ------------------------
code | Integer | 返回状态码
msg | String | 错误描述
result | JSON Object | 接口返回内容
常见错误代码及其说明
Code | Error Type | Description
------------ | ----------- | ------------------------
0／200 | 成功 | 请求成功
400 | 无效请求 | 某些必需参数缺失或参数值错误，详见`msg`字段
401 | 未授权 | 授权失败，`app_key`缺失或错误
403 | 请求被禁止 | 有效请求，但服务拒绝响应，请联系[contact@ruyi.ai](contact@ruyi.ai)
408 | 请求超时 |请求响应超时，一般响应时间设置为2000ms以内
429 | 短时间内大量访问 | 短时间内请求数过多
500 | 内部错误 | 服务处理异常
503 | 服务不可用 | 服务异常或正在维护
- 1. 海知智能第三方技能插件开放平台概述
- 2. 快速接入API
- 2.1 硬件接口调用
- 2.2 快速接入微信
- 2.3 API接入常见问题
- 3. 技能插件
- 3.1 基础能力类
- 顶级过滤器
- 用户知识图谱
- 机器人档案
- 通用闲聊
- 儿童闲聊
- Smart Reply
- 轻量闲聊
- 3.2 语音游戏类
- 成语接龙
- 词汇乐园
- 词语接龙
- 鹦鹉学舌
- 动脑猜猜
- 挑战单词
- 冒险世界
- 猜猜我是谁
- 阿拉丁学诗词
- 猫猫托管所
- 漂流瓶
- 诗词大会
- 国学大会
- 我爱猜歌名
- 我在看着你
- 灯谜猜猜
- 3.3 休闲娱乐类
- 星座运势
- 悦耳声音
- 幸运签
- 调教机器人
- 娱乐推送
- 3.4 生活服务类
- 黄历
- 计算器
- 古诗词
- 时间询问
- 翻译类技能
- 天气资讯
- 日程创建
- 日程创建指令
- 闹钟
- 食材知识
- 冥想音乐
- 格言
- 每日英语
- 汉语词典
- 豆果菜谱
- 古文翻译
- 3.5 音频点播类
- 喜马拉雅FM
- 新闻广播
- 音乐点播
- Smart Music
- 儿童听听
- Smart Audio
- 儿童笑话
- 点播控制指令
- 3.6 视频点播类
- 影视点播
- 3.7 百科知识类
- 人物百科
- 百科问答
- 实时百科
- 3.8 体育健康类
- 五分钟健身
- 4. 开发者初级教程
- 4.1 开通服务
- 4.2 创建机器人
- 4.3 设置机器人
- 4.4 获取技能插件
- 4.5 让机器人学会聊天
- 4.6 导入知识库
- 4.7 多种问答形式
- 4.8 数据统计
- 4.9 粉丝管理
- 5. 开发者中级教程
- 5.1 词典运用
- 5.2 意图处理
- 5.3 暗号使用
- 5.4 事件触发
- 5.5 优先级
- 5.6 触发器
- 5.7 快捷键
- 5.8 意图报错
- 6. 开发者高级教程
- 6.1 handlebars模版语言
- 6.2 JavaScript简单介绍
- 6.3 JavaScript使用说明
- 6.4 JavaScript使用案例
- 6.5 JavaScript常见问题
- 7. 快速发布技能
- 8. 帮助中心
- 8.1 常见概念
- 8.2 帮助视频
- 8.3 联系我们