Synology Download Station 官方 API 开发指南

本文介绍 Synology Download Station 官方 API 的完整开发指南，帮助开发者基于 Download Station API 构建应用程序，通过 HTTP 请求与群晖 NAS 的下载服务进行交互。

文档概述

Synology Download Station 是群晖 NAS 中最受欢迎的套件之一，提供强大的下载管理功能。本文档详细介绍 Download Station API 的结构和规范，包括基础 API 和 Download Station 专用 API 的完整说明。

API 工作流程

使用 Download Station API 需要遵循以下四个步骤：

1. 获取 API 信息

首先需要查询目标 DiskStation 上可用的 API 列表，通过 SYNO.API.Info API 的 query.cgi 接口获取。

请求示例：

响应包含：

• API 名称
• CGI 路径
• 支持的版本信息

2. 会话登录

使用 DSM 账号和密码通过 SYNO.API.Auth API 登录会话。

请求示例：

3. 调用 Download API

登录成功后，可以调用所有可用的 Download Station API。

4. 会话注销

完成操作后，通过 SYNO.API.Auth API 的 logout 方法结束会话。

请求构造规范

所有 API 请求需要包含以下基本元素：

请求语法：

响应解析

所有 API 响应均采用 JSON 格式，包含以下字段：

成功响应示例：

{
  "success": true,
  "data": {
    "is_manager": true,
    "version": 2269,
    "version_string": "3.2-2269"
  }
}

失败响应示例：

{
  "success": false,
  "error": 101
}

通用错误代码

基础 API

SYNO.API.Info

提供可用 API 信息查询。

方法： query

参数：

• query: API 名称列表（逗号分隔）或使用 ALL 获取所有支持的 API

响应对象：

• path: API CGI 路径
• minVersion: 最小支持版本
• maxVersion: 最大支持版本

SYNO.API.Auth

执行会话登录和注销。

登录方法： login

参数：

• account: 登录账号
• passwd: 登录密码
• session: 会话名称
• format: 会话 ID 返回格式（cookie 或 sid）
• otp_code: 2步验证代码（DSM 4.2+）

注销方法： logout

参数：

• session: 要注销的会话名称

错误代码：

• 400: 账号不存在或密码错误
• 401: 账号已禁用
• 402: 权限被拒绝
• 403: 需要2步验证码
• 404: 2步验证失败

Download Station API

SYNO.DownloadStation.Info

提供 Download Station 信息和设置管理。

方法：

• getinfo: 获取 Download Station 信息
• getconfig: 获取服务器配置
• setserverconfig: 设置服务器配置

配置参数包括：

• bt_max_download: BT 最大下载速度（KB/s，0 表示无限制）
• bt_max_upload: BT 最大上传速度（KB/s）
• emule_max_download: eMule 最大下载速度
• emule_max_upload: eMule 最大上传速度
• nzb_max_download: NZB 最大下载速度
• http_max_download: HTTP 最大下载速度
• ftp_max_download: FTP 最大下载速度
• emule_enabled: eMule 服务是否启用
• unzip_service_enabled: 自动解压服务是否启用
• default_destination: 默认下载路径
• emule_default_destination: eMule 默认路径

SYNO.DownloadStation.Schedule

提供高级下载计划设置。

方法：

• getconfig: 获取计划配置
• setconfig: 设置计划配置

参数：

• enabled: 下载计划是否启用
• emule_enabled: eMule 下载计划是否启用

SYNO.DownloadStation.Task

提供下载任务管理和操作。

方法：

• list: 获取任务列表
• getinfo: 获取任务详细信息
• create: 创建下载任务
• delete: 删除任务
• pause: 暂停任务
• resume: 恢复任务
• edit: 编辑任务

List 方法参数：

• offset: 起始记录位置（默认 0）
• limit: 请求记录数量（-1 表示所有任务）
• additional: 额外信息选项（逗号分隔）
  • detail: 任务详情
  • transfer: 传输信息
  • file: 文件信息（仅 BT）
  • tracker: Tracker 信息（仅 BT）
  • peer: Peer 信息（仅 BT）

任务对象字段：

• id: 任务 ID
• type: 任务类型（bt/http/ftp/emule/nzb）
• username: 用户名
• title: 任务标题
• size: 文件大小
• status: 任务状态
• status_extra: 额外状态信息

Create 方法参数：

• uri: 下载链接（HTTP/FTP/magnet/ED2K）或文件路径
• file: 上传的文件
• username: 登录用户名
• password: 登录密码
• unzip_password: 解压密码
• destination: 下载目标路径

SYNO.DownloadStation.Statistic

提供总下载/上传统计信息。

方法： getinfo

响应包含：

• 总下载速度
• 总上传速度

SYNO.DownloadStation.RSS.Site

提供 RSS 站点管理。

方法：

• list: 获取 RSS 站点列表
• refresh: 刷新 RSS 站点

SYNO.DownloadStation.RSS.Feed

提供 RSS 订阅源管理。

方法： list

参数：

• offset: 起始位置
• limit: 数量限制

SYNO.DownloadStation.BTSearch

提供 BT 搜索功能。

方法：

• start: 开始搜索
• list: 获取搜索结果

完整工作示例

以下是从登录到获取下载任务列表的完整示例：

步骤 1: 获取 API 信息

步骤 2: 会话登录

响应：

{
  "data": {
    "sid": "ohOCjwhHhwghw"
  },
  "success": true
}

步骤 3: 请求下载任务列表

步骤 4: 会话注销

任务状态说明

注意事项

1. 版本兼容性：所有 Download Station API 需要 DSM 4.0 或更高版本
2. 权限要求：部分配置操作需要管理员权限
3. 速率限制：HTTP 和 FTP 最大下载速率共享同一配置值
4. 会话管理：建议操作完成后及时注销会话
5. 2步验证：DSM 4.2+ 支持 2步验证，需要在登录时提供 otp_code 参数

参考链接

• 群晖官方开发者文档
• Download Station 官方 API PDF 文档