播放历史
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
DELETE | /play-history | 清空播放上下文的播放历史 |
GET | /play-history | 查询播放上下文的播放历史 |
DELETE | /play-history/entry | 删除单条播放历史 |
DELETE /play-history
清空播放上下文的播放历史
删除指定播放上下文内的全部播放记录，返回实际删除条数。上下文不存在或本就没有记录时返回 deleted=0，不视为错误。
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
context_type | string | 是 | 播放上下文类型 可选值: playlist, tag, artist, album, genre, year, decade, language, style |
context_key | string | 是 | 播放上下文标识：playlist 传歌单 ID，分面维度传该维度取值 |
响应
200 - 成功返回 {deleted: 删除条数}
类型： map[string]integer
400 - context_type 不支持或缺少 context_key
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应：
application/json
GET /play-history
查询播放上下文的播放历史
返回指定播放上下文内最近播放过的歌曲，按最后播放时间倒序，含完整歌曲详情。 「播放上下文」由 context_type + context_key 二元组标识：歌单为 (playlist, 歌单 ID)，自定义标签为 (tag, 标签 ID)，分面维度为 (artist, 歌手名) / (album, 专辑名) 等。 同一上下文内按歌曲去重（重复播放只刷新时间并累加 play_count），最多保留最近 50 条，因此本端点不分页。 记录由 POST /songs/{id}/played 在 type=play 时写入。歌曲从库中删除时其历史自动级联清理；歌曲仅被移出歌单时历史仍保留，客户端起播时自行判定失效。
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
context_type | string | 是 | 播放上下文类型 可选值: playlist, tag, artist, album, genre, year, decade, language, style |
context_key | string | 是 | 播放上下文标识：playlist 传歌单 ID，分面维度传该维度取值 |
limit | integer | 否 | 返回条数，缺省 50，上限 50 |
响应
200 - 成功返回播放历史列表
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
items | PlayHistoryEntry[] | 否 | 播放记录，按最后播放时间倒序 |
total | integer | 否 | 本次返回的条数（上限 50，故与 items 长度一致） 示例: 12 |
400 - context_type 不支持或缺少 context_key
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应：
application/json
DELETE /play-history/entry
删除单条播放历史
从指定播放上下文中删除某首歌的播放记录。典型用途：清理已被移出歌单、在历史面板里显示为失效的条目。
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
context_type | string | 是 | 播放上下文类型 可选值: playlist, tag, artist, album, genre, year, decade, language, style |
context_key | string | 是 | 播放上下文标识：playlist 传歌单 ID，分面维度传该维度取值 |
song_id | integer | 是 | 要删除的歌曲 ID |
响应
204 - 删除成功，无内容
400 - context_type 不支持、缺少 context_key 或无效的 song_id
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 该上下文中不存在此歌曲的播放记录
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应：
application/json