mirror of
https://github.com/bolucat/Archive.git
synced 2025-12-24 13:28:37 +08:00
145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# JSON API文档
|
||
|
||
## API
|
||
|
||
如果以服务器模式启动BBDown，BBDown会在本地启动一个http server，该服务器有以下API：
|
||
|
||
### 获取任务列表
|
||
**Endpoint:** `/get-tasks/`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 获取所有任务的列表，包括正在运行的任务和已完成的任务。
|
||
|
||
**Response:** JSON格式的`DownloadTaskCollection`。
|
||
|
||
### 获取正在运行的任务列表
|
||
**Endpoint:** `/get-tasks/running`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 获取所有正在运行的任务的列表。
|
||
|
||
**Response:** JSON格式的`List<DownloadTask>`, 正在运行的任务列表。
|
||
|
||
### 获取已完成的任务列表
|
||
**Endpoint:** `/get-tasks/finished`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 获取所有已完成的任务的列表。
|
||
|
||
**Response:** JSON格式的`List<DownloadTask>`, 已完成的任务列表。
|
||
|
||
### 获取特定任务
|
||
**Endpoint:** `/get-tasks/{id}`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 获取特定任务的详细信息，根据视频的AID。
|
||
|
||
**Parameters:**
|
||
- `{id}` (路径参数): 视频的AID
|
||
|
||
**Response:** 如果找到匹配的任务，将返回JSON格式的`DownloadTask`。如果未找到匹配的任务，将返回404 Not Found。
|
||
|
||
### 添加任务
|
||
**Endpoint:** `/add-task`
|
||
|
||
**Method:** POST
|
||
|
||
**Description:** 向任务列表中添加新任务。
|
||
|
||
**Request Body:** JSON格式的任务信息，需要符合`MyOption`数据结构。并不要求带有MyOption中的每一个字段，只需要有`Url`字段就够了。
|
||
|
||
**Response:**
|
||
- 如果请求有效并成功添加任务，将返回200 OK。
|
||
- 如果请求无效，将返回400 Bad Request，并附带错误消息`"输入有误"`。
|
||
|
||
### 移除已完成的任务
|
||
**Endpoint:** `/remove-finished`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 移除所有已完成的任务
|
||
|
||
**Response:**
|
||
- 返回200 OK。
|
||
|
||
### 移除已完成的任务
|
||
**Endpoint:** `/remove-finished/failed`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 移除所有已完成但是失败(`IsSuccessful == false`)的任务
|
||
|
||
**Response:**
|
||
- 返回200 OK。
|
||
|
||
### 移除特定已完成的任务
|
||
**Endpoint:** `/remove-finished/{id}`
|
||
|
||
**Method:** GET
|
||
|
||
**Description:** 移除特定已完成的任务，根据视频的AID。
|
||
|
||
**Parameters:**
|
||
- `{id}` (路径参数): 视频的AID
|
||
|
||
**Response:**
|
||
- 无论是否能找到对应ID的任务，均返回200 OK。
|
||
|
||
## 数据结构
|
||
|
||
### `DownloadTask` 数据结构
|
||
`DownloadTask` 数据结构表示一个下载任务的信息。
|
||
|
||
**属性：**
|
||
- `Aid` `<string>`: 视频解析出的Aid，用作正在下载中的任务的唯一标识符，已完成任务中允许重复存在
|
||
- `Url` `<string>`: 下载任务请求时的URL，不一定需要完整的URL，命令行支持的`av|bv|BV|ep|ss`都可以在这里使用。
|
||
- `TaskCreateTime` `<long>`: 任务创建时间，Unix时间戳，精确到秒，本机时区。
|
||
- `Title` `<string?>`: 视频的标题。
|
||
- `Pic` `<string?>`: 视频的封面图片链接。
|
||
- `VideoPubTime` `<long?>`: 视频发布时间，Unix时间戳，精确到秒。
|
||
- `TaskFinishTime` `<long?>`: 任务完成时间，Unix时间戳，精确到秒，本机时区。
|
||
- `Progress` `<double>`: 任务的下载进度，为0-1区间范围的小数。
|
||
- `DownloadSpeed` `<double>`: 下载速度, 单位为Byte/s。下载中时为最后一次更新的实时速度，下载完成后为平均速度。
|
||
- `TotalDownloadedBytes` `<double>`: 总下载字节(Byte)数，完成后的数字比实际文件偏小。
|
||
- `IsSuccessful` `<bool>`: 标识任务是否成功完成。
|
||
|
||
### `DownloadTaskCollection` 数据结构
|
||
`DownloadTaskCollection` 数据结构包含两个列表，分别表示正在运行的任务和已完成的任务。
|
||
|
||
**属性：**
|
||
- `Running` `<List<DownloadTask>>`: 包含正在运行的任务的列表，每个元素都是 `DownloadTask` 数据结构。
|
||
- `Finished` `<List<DownloadTask>>`: 包含已完成的任务的列表，每个元素都是 `DownloadTask` 数据结构。
|
||
|
||
### `MyOption` 数据结构
|
||
|
||
参考[BBDown/MyOption.cs](./BBDown/MyOption.cs)。属性和命令行参数几乎是一一对应的，相应的值填写使用命令行会使用的值即可。这个结构会随着版本变化，请参考对应版本时候的文件。
|
||
|
||
### 注意事项
|
||
- 由于BBDown的下载进度回报频率所限，`TotalDownloadedBytes`会比实际下载的文件略低，大概会少等效于1秒下载速度的文件体积，如果文件本身就非常小那这个数字偏差会较大。
|
||
- BBDown目前内部机制没有太好的方法取消单个下载任务，因此目前任务提交以后只能等任务失败或者完成。
|
||
- 目前服务器没有对同时执行的下载任务数量做任何限制，如果短时间频繁添加任务就会同时执行相当数量的下载任务，需要小心注意不要耗尽资源。未来考虑添加下载队列。
|
||
|
||
### 使用例
|
||
|
||
#### 用BV号添加任务
|
||
|
||
```shell
|
||
curl -X POST -H 'Content-Type: application/json' -d '{ "Url": "BV1qt4y1X7TW" }' http://localhost:58682/add-task
|
||
```
|
||
|
||
#### 下载到指定目录
|
||
|
||
Windows:
|
||
```shell
|
||
curl -X POST -H 'Content-Type: application/json' -d '{ "Url": "BV1qt4y1X7TW", "FilePattern": "C:\\Downloads\\<videoTitle>[<dfn>]" }' http://localhost:58682/add-task
|
||
```
|
||
|
||
Unix-Like:
|
||
```shell
|
||
curl -X POST -H 'Content-Type: application/json' -d '{ "Url": "BV1qt4y1X7TW", "FilePattern": "/Downloads/<videoTitle>[<dfn>]" }' http://localhost:58682/add-task
|
||
```
|