mirror of
https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced.git
synced 2026-06-13 18:55:07 +00:00
39e0e0718d
- Add new interface /api/relay/play/state/submit - Support sessionId tracking for play sessions - Support playMode parameter (list_loop, single_loop, random, single) - Add parameter validation - Include integration documentation
160 lines
3.6 KiB
Markdown
160 lines
3.6 KiB
Markdown
# relay_play_state_submit 集成说明
|
||
|
||
## 修改内容
|
||
|
||
### 1. 新增 API 接口模块
|
||
|
||
**文件**: `module/relay_play_state_submit.js`
|
||
|
||
**功能**: 提交歌曲播放状态，支持会话追踪和播放模式记录
|
||
|
||
**接口地址**: `/api/relay/play/state/submit`
|
||
|
||
**参数说明**:
|
||
- `id` (必填): 歌曲 ID
|
||
- `sessionId` (必填): 播放会话 ID（12 位大写字母和数字）
|
||
- `progress` (可选): 播放进度（秒），默认 0
|
||
- `playMode` (可选): 播放模式，默认 `list_loop`
|
||
- `type` (可选): 资源类型，默认 `song`
|
||
|
||
**参数校验**:
|
||
```javascript
|
||
if (!id || !sessionId) {
|
||
return Promise.reject({
|
||
status: 400,
|
||
body: {
|
||
code: 400,
|
||
msg: '缺少必要参数：id, sessionId',
|
||
},
|
||
})
|
||
}
|
||
```
|
||
|
||
### 2. 更新 API 文档
|
||
|
||
**文件**: `public/docs/home.md`
|
||
|
||
在文档末尾添加了接口说明，包括：
|
||
- 接口功能说明
|
||
- 参数列表
|
||
- 调用示例
|
||
|
||
### 3. 集成到自动任务脚本
|
||
|
||
**文件**: `auto_tasks_enhanced.js`
|
||
|
||
**修改内容**:
|
||
|
||
1. **导入接口** (Line 32):
|
||
```javascript
|
||
const {
|
||
// ... 其他接口
|
||
relay_play_state_submit,
|
||
// ... 其他接口
|
||
} = require('@neteasecloudmusicapienhanced/api')
|
||
```
|
||
|
||
2. **组合使用两个接口** (Lines 447-483):
|
||
```javascript
|
||
// 2. 上传听歌记录（组合使用两个接口）
|
||
console.log(' [2] 上传播放状态...')
|
||
try {
|
||
// 生成 sessionId（12 位大写字母和数字）
|
||
const sessionId = Math.random().toString(36).substring(2, 8).toUpperCase() +
|
||
Math.random().toString(36).substring(2, 8).toUpperCase()
|
||
|
||
// 2.1 提交播放开始状态（relay_play_state_submit）
|
||
const relayResult = await relay_play_state_submit({
|
||
cookie,
|
||
id: song.id,
|
||
sessionId: sessionId,
|
||
progress: 0,
|
||
playMode: 'list_loop'
|
||
})
|
||
if (relayResult.body.code === 200) {
|
||
console.log(' ✓ 播放状态已提交')
|
||
}
|
||
|
||
await sleep(1000)
|
||
|
||
// 2.2 上传完整听歌记录（scrobble）
|
||
const playTime = Math.floor(song.dt / 1000)
|
||
const scrobbleResult = await scrobble({
|
||
cookie,
|
||
id: song.id,
|
||
sourceid: playlistId,
|
||
time: playTime
|
||
})
|
||
if (scrobbleResult.body.code === 200) {
|
||
const timeStr = (playTime / 60).toFixed(2)
|
||
console.log(` ✓ 听歌记录已上传 (${timeStr}分钟)`)
|
||
successCount++
|
||
}
|
||
} catch (e) {
|
||
console.log(` 上传失败：${e.message}`)
|
||
}
|
||
```
|
||
|
||
## 工作流程
|
||
|
||
完整的 VIP 音乐任务播放流程：
|
||
|
||
```
|
||
1. 收藏歌曲 (song_like)
|
||
↓
|
||
2. 提交播放状态 (relay_play_state_submit)
|
||
↓ (延迟 1 秒)
|
||
3. 上传听歌记录 (scrobble)
|
||
↓ (延迟 1 秒)
|
||
4. 等待 30-60 秒
|
||
↓
|
||
5. 取消收藏 (song_like)
|
||
```
|
||
|
||
## 优势
|
||
|
||
### 组合使用两个接口的好处：
|
||
|
||
1. **relay_play_state_submit**:
|
||
- 实时播放状态同步
|
||
- 会话追踪（sessionId）
|
||
- 播放模式记录
|
||
- 更符合现代播放器行为
|
||
|
||
2. **scrobble**:
|
||
- 完整的听歌记录
|
||
- 播放时长统计
|
||
- 来源歌单记录
|
||
- 用于任务完成判定
|
||
|
||
3. **组合效果**:
|
||
- 更真实的播放行为模拟
|
||
- 完整的数据记录
|
||
- 提高任务完成可靠性
|
||
|
||
## Pull Request
|
||
|
||
**PR #181**: https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced/pull/181
|
||
|
||
**提交内容**:
|
||
- ✅ 新增 `module/relay_play_state_submit.js`
|
||
- ✅ 更新 `public/docs/home.md`
|
||
- ✅ 参数校验修复
|
||
- ✅ 使用示例更新
|
||
|
||
## 测试验证
|
||
|
||
接口已通过测试：
|
||
```
|
||
✓ relay_play_state_submit 成功
|
||
✓ scrobble 成功
|
||
✓ 组合使用正常
|
||
```
|
||
|
||
## 兼容性
|
||
|
||
- ✅ 保持原有 `scrobble` 接口不变
|
||
- ✅ 新增 `relay_play_state_submit` 可选使用
|
||
- ✅ 向后兼容
|
||
- ✅ 不影响现有功能
|