### 3.3.4 调教机器人 #### （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": "b814e7b9-73ed-4b5a-bdb4-bcb2d2b782b6", "intents": [{ "parameters": { "type": "ruyi-customized-agent-info", "upsert": "true", "alias": "小苹果", "service": "2cattribute" }, "action": "sys.action.item/update", "name": "终端助理_设置姓名", "result": { "updated_item": { "_id": "3571127f-976d-4368-991e-868b9e59fab4", "type": "ruyi-customized-agent-info", "alias": "小苹果", "service": "2cattribute", "appId": "6e3a8217-d07d-4cb8-803c-75e952bb521b", "userId": "user0", "updated_time": 1487240842616, "created_time": 1487240842616, "item_status": "VALID" }, "msg": "ok", "text": "我的名字叫&name", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "好呀，那以后主人就叫我\"小苹果\"，是吗" } }, { "type": "dialog", "property": { "text": "好呀，那以后主人就叫我\"小苹果\"，是吗", "emotion": "suspect" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "444bdafd-e21f-4dcd-8ad7-3c83cc667996" }], "meta_process_milliseconds": 81 } } ``` **请求示例** 还原姓名 * 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": "cd5cfea9-1454-4366-acc5-299703b1a076", "intents": [{ "parameters": { "type": "ruyi-customized-agent-info", "unset": "alias", "service": "2cattribute" }, "action": "sys.action.item/update", "name": "终端助理_忘记姓名", "result": { "updated_item": { "_id": "3571127f-976d-4368-991e-868b9e59fab4", "type": "ruyi-customized-agent-info", "service": "2cattribute", "appId": "6e3a8217-d07d-4cb8-803c-75e952bb521b", "userId": "user0", "updated_time": 1487241093479, "created_time": 1487240842616, "item_status": "VALID" }, "msg": "ok", "text": "我是&name", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "唔，好的！" } }, { "type": "dialog", "property": { "text": "遵命", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "d8c14220-1881-45bc-b1b9-21651c882699" }], "meta_process_milliseconds": 371 } } ``` **详细参数说明** | 名称 | 类型 | 说明 | | :--- | :--- | :--- | | service | String | 服务名称 | | type | String | 类型| | upsert | String | 判断助理名是否存在 | | alias | String | 机器人名字 | |updated_time|String|更新时间 |created_time|String|创建时间 | yes | String | 确认 | | no | String | 否定 |