### 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|專輯|