diff --git a/src/05.audio-library/01.protocol.md b/src/05.audio-library/01.protocol.md index a567f21..468a057 100644 --- a/src/05.audio-library/01.protocol.md +++ b/src/05.audio-library/01.protocol.md @@ -105,7 +105,9 @@ Access-Control-Allow-Origin: * "protocol_version": "0.2.1", // 音频仓库最近一次数据更新时间 // 用于客户端缓存 `/albums` 请求结果 - "last_update": 1639631487 + "last_update": 1639631487, + // 用于提供元数据的 `Annim` 服务器 URL + "meta_server": "https://annim.example.com" } ``` diff --git a/src/06.anniv/03.playlist.md b/src/06.anniv/03.playlist.md index 7dcfa17..a169d6f 100644 --- a/src/06.anniv/03.playlist.md +++ b/src/06.anniv/03.playlist.md @@ -307,3 +307,23 @@ type PatchedPlaylistInfo = Partial>; | -------- | -------------- | | `103002` | 播放列表不存在 | | `103003` | 非法修改类型 | + +## 搜索播放列表 + +### Endpoint + +`GET /api/playlist/search` + +### 请求 + +#### 请求参数 + +| 参数名 | 详情 | +| --------- | -------------- | +| `keyword` | 搜索关键词 | +| `limit` | 最多返回条目数 | +| `offset` | 跳过条目数 | + +### 响应 + +返回一个 `PlaylistInfo[]` ，按相关程度降序排序。 diff --git a/src/06.anniv/09.search.md b/src/06.anniv/09.search.md deleted file mode 100644 index 32da524..0000000 --- a/src/06.anniv/09.search.md +++ /dev/null @@ -1,28 +0,0 @@ -# 搜索 - -## Endpoint - -`GET /api/search` - -## 请求参数 - -| 参数名 | 类型 | 说明 | -| ------------------ | -------- | ---------------- | -| `search_albums` | `bool` | 是否搜索专辑 | -| `search_tracks` | `bool` | 是否搜索音轨 | -| `search_playlists` | `bool` | 是否搜索播放列表 | -| `keyword` | `string` | 搜索关键字 | - -## 返回 - -返回 `SearchResult` 。 - -### 参数列表 - -```ts -interface SerachResult { - albums?: AlbumDetail[]; - tracks?: TrackInfoWithAlbum[]; - playlists?: PlaylistInfo[]; -} -``` diff --git a/src/08.annim/00.readme.md b/src/08.annim/00.readme.md new file mode 100644 index 0000000..06f6317 --- /dev/null +++ b/src/08.annim/00.readme.md @@ -0,0 +1,7 @@ +# Annim + +> ⚠️️ 目前的 `Annim` 仍处于 `Draft` 状态，尚未完全定稿。欢迎随时提出意见或建议。 + +> ⚠️️ 目前 `Annim` 协议的版本为 `1`。 + +`Annim` 是独立的元数据服务，每一个 `Annil` 都需要指定一个对应的 `Annim` 服务提供元数据。 diff --git a/src/08.annim/01.protocol.md b/src/08.annim/01.protocol.md new file mode 100644 index 0000000..022bd85 --- /dev/null +++ b/src/08.annim/01.protocol.md @@ -0,0 +1,117 @@ +# Annim 元数据协议 + +Annim 元数据协议用于向客户端提供元数据服务。所有接口均使用 [Anni 信息导出格式](../06.anniv/07.export-format.md)。 + +## 元数据 + +### 专辑信息 + +通过 `album_id` 获得专辑元数据的接口。支持同时获取多张专辑的元数据信息。 + +#### Endpoint + +`GET /album/:id` + +#### 请求参数 + +| 参数名 | 说明 | +| ------ | ---------------------------- | +| `id` | 待获取元数据的专辑 `ID` 列表 | + +#### 返回 + +返回以 `album_id` 为键，专辑元数据或空为值的 `Object`。 + +当查询成功时，值为专辑的 `AlbumDetail`，否则为 `null`。 + +### 获取 Tag 列表 + +`GET /tags` + +#### 返回 + +返回包含所有 `Tag` 的数组，类型为 `TagInfo[]` 。 + +### 按 Tag 检索专辑 + +通过 Tag 检索归属于该 Tag 下的专辑列表。 + +该接口属于检索接口，标签使用「向上合并」的语义。即计算专辑标签时，需要取专辑内所有专辑标签、光盘标签和音轨标签的**并集**。具体定义见 [专辑信息 - 标签](../02.metadata-repository/02.album-information.md#标签)。 + +#### Endpoint + +`GET /tags/:tag/albums` + +#### 参数 + +| 参数名 | 类型 | 说明 | +| ----------- | --------- | -------------------------------- | +| `tag` | `string` | 路径中的 `tag` 参数，表示 Tag 名 | +| `recursive` | `boolean` | 是否递归检索子 Tag 所包含专辑 | + +#### 返回 + +`AlbumDetail[]` + +#### 错误列表 + +| 错误代码 | 详情 | +| -------- | ------------ | +| `902000` | `Tag` 不存在 | + +### 获取 Tag 详细 + +#### Endpoint + +`GET /tags/:tag/detail` + +#### 参数 + +| 参数名 | 类型 | 说明 | +| ------ | -------- | -------------------------------- | +| `tag` | `string` | 路径中的 `tag` 参数，表示 Tag 名 | + +#### 返回 + +`TagDetail` + +### 获取 Tag 关系 + +#### Endpoint + +`GET /tag-graph` + +#### 返回 + +返回 `tag` 依赖关系的邻接表，类型表示为 `Record` 。 + +`Key-Value` 对应的是标签与其所包含的子标签。字符串格式为 `:`，标签类型不可省略。 + +## 搜索 + +### Endpoint + +`GET /search` + +### 请求参数 + +| 参数名 | 类型 | 说明 | +| --------- | -------- | ------------------------------------------- | +| `type` | `string` | `album` 或 `track` ，分别代表搜索专辑或单曲 | +| `keyword` | `string` | 搜索关键字 | +| `limit` | `number` | 最多返回条目数 | +| `offset` | `number` | 跳过多少条记录，缺省为 0 | + +### 返回 + +返回 `ScoredEntry[]` ，结果按 `score` 降序排序，`T` 为 `AlbumDetail` 或 `TrackInfoWithAlbum` 。 + +#### 参数列表 + +```ts +interface ScoredEntry { + content: T; + // 归一化的 score ，必须为属于 [0, 100] 的浮点数 + score: number; +} +``` diff --git a/src/08.annim/02.backend.md b/src/08.annim/02.backend.md new file mode 100644 index 0000000..eb611df --- /dev/null +++ b/src/08.annim/02.backend.md @@ -0,0 +1,7 @@ +# Annim 元数据后端 + +Annim 不仅需要与客户端约定提供元数据的协议，也需要关于元数据来源的约定，这就是 Annim 元数据后端。 + +## Git repo 后端 + +使用 git 仓库作为元数据来源，仓库结构应符合[Anni 元数据仓库](../02.metadata-repository/00.readme.md)标准。 diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d1a1ed0..d0f8b8d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -52,7 +52,6 @@ - [Annil Token 管理](./06.anniv/04.credential.md) - [信息导出格式](./06.anniv/07.export-format.md) - [专辑元数据](./06.anniv/08.meta.md) - - [搜索](./06.anniv/09.search.md) - [分享管理](./06.anniv/05.share.md) - [播放统计](./06.anniv/06.statistics.md) - [喜欢](./06.anniv/10.favorite.md) @@ -62,6 +61,9 @@ - [两步验证（2fa）](./06.anniv/features/02.2fa.md) - [禁止注册（close）](./06.anniv/features/03.close.md) - [预构建数据源（metadata-db）](./06.anniv/features/04.metadata-db.md) +- [Annim 元数据服务](./08.annim/00.readme.md) + - [协议](./08.annim/01.protocol.md) + - [元数据后端](./08.annim/02.backend.md) - [Annisonic](./07.annisonic/00.readme.md) - [实现的 API](./07.annisonic/01.apis.md) - [已测试的客户端](./07.annisonic/02.clients.md)