### 3.5.8 点播控制指令 #### （1） 功能说明 用于音乐点播、儿童听听硬件段的指令服务，包括播放控制、声音控制、收藏控制三部分指令。 1）播放控制指令有：暂停播放，继续播放，随机播放，单曲循环，列表循环，上一首，下一首。 2）声音控制指令有：静音，增大音量，减小音量。 3）收藏控制指令有：打开收藏，收藏单曲，收藏专辑，播放收藏。 #### （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=上一首 返回结果 ``` { "_text": "上一首", "msg_id": "87bae3ab-3335-47b2-a3ea-aa410f6c80f8", "intents": [{ "parameters": { "operation": "prev", "上一首": "上一首", "service": "app_musicOperation" }, "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, "skill_id": "366111de-4d77-41b6-8612-784ad471f9ed", "id": "b7f652c5-fe4b-44d7-b451-c95ac9cb70db", "action": "dialog" }], "meta_process_milliseconds": 71 } ``` **详细参数说明** | 名称 | 类型 | 说明 | | :--- | :--- | :--- | | service | string | 服务名称 | | operation | string | 操作指令，例如"pause" | | attr | string | 智能设备属性，例如"mode" | | attr\_value | string | 设备属性值，例如"mode"中，“单曲循环”代表一直播放某歌曲 | **控制指令列表** | operation | 说明 | | :--- | :--- | | set | 设置 | |launch|打开| |play|播放| | pause | 暂停 | | prev | 上一首 | | next | 下一首 | |mute|静音| |decrease|减少| |increase|增加| |collect|收藏| |attr|说明| | :--- | :--- | |mode|模式| |volume|音量| | mode | 说明 | | :--- | :--- | | 单曲循环 | 单曲循环 | |随机播放|随机播放| |列表循环|列表循环| |object|说明| | :--- | :--- | |collecting|收藏夹| |song|单曲| |album|专辑|