Skip to content

Latest commit

 

History

History
144 lines (93 loc) · 5.21 KB

json-api-doc.md

File metadata and controls

144 lines (93 loc) · 5.21 KB
Raw

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的下载进度回报频率所限，TotalDownloadedBytes会比实际下载的文件略低，大概会少等效于1秒下载速度的文件体积，如果文件本身就非常小那这个数字偏差会较大。
  • BBDown目前内部机制没有太好的方法取消单个下载任务，因此目前任务提交以后只能等任务失败或者完成。
  • 目前服务器没有对同时执行的下载任务数量做任何限制，如果短时间频繁添加任务就会同时执行相当数量的下载任务，需要小心注意不要耗尽资源。未来考虑添加下载队列。

使用例

用BV号添加任务

curl -X POST -H 'Content-Type: application/json' -d '{ "Url": "BV1qt4y1X7TW" }' http://localhost:58682/add-task

下载到指定目录

Windows:

curl -X POST -H 'Content-Type: application/json' -d { "Url": "BV1qt4y1X7TW", "FilePattern": "C:\\Downloads\\<videoTitle>[<dfn>]" }' http://localhost:58682/add-task

Unix-Like:

curl -X POST -H 'Content-Type: application/json' -d { "Url": "BV1qt4y1X7TW", "FilePattern": "/Downloads/<videoTitle>[<dfn>]" }' http://localhost:58682/add-task