Synology File Station 官方 API 指南总结（中文版）

Synology File Station 官方 API 指南总结（中文版）

本总结基于提供的 Synology File Station Official API Guide PDF 文档（版本：2023 年 Synology Inc.，总页数 112 页）。文档详细说明了如何通过 HTTP/HTTPS 请求与 DSM（DiskStation Manager）中的 File Station 交互，实现文件管理功能。总结聚焦于核心内容，包括 API 结构、基本流程、基础 API 和所有 File Station API 的规格。所有 API 请求需通过 /webapi/ 路径，并使用 JSON 格式响应。

注意：文档强调所有内容为 Synology 专有技术信息，未经许可不得复制或用于商业用途。API 可用性从 DSM 4.0 开始，支持 HTTPS 以确保安全。

总结力求简单详尽：用列表、表格形式解释每个 API 的方法、参数、响应和错误码，避免复杂术语，提供示例。完整 API 列表覆盖所有章节。

第 1 章：引言

• 目的：本指南帮助开发者扩展应用，通过 File Station API 与 DSM 文件交互，支持文件列表、搜索、共享、上传/下载、压缩/解压等操作。
• 版权与免责：Synology 保留所有知识产权。文档“按原样”提供，无任何保证。开发者需自行承担风险。
• 适用范围：仅适用于 Synology 品牌的 NAS 设备。

第 2 章：入门

2.1 API 工作流程

1. 检索 API 信息：请求 SYNO.API.Info 获取可用 API 列表、路径和版本。
2. 登录：使用 SYNO.API.Auth 登录，获取 session ID（sid），默认过期 7 天。
3. 执行 API 请求：使用 sid 调用 File Station API。
4. 登出：使用 SYNO.API.Auth 登出。

2.2 构造请求

• 基本元素：API 名、版本、路径、方法、sid。
• 语法：GET /webapi/<路径>?api=<名称>&version=<版本>&method=<方法>[&参数][&_sid=]。
• 参数处理：URL 转义逗号用斜杠，密码不转义。
• 示例：查询所有 API：http://myds.com:5000/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query&query=all。

2.3 解析响应

• 格式：JSON，包含 success（true/false）、data（数据）、error（错误码 + errors 数组）。
• 示例：成功响应有文件详情；失败响应有错误码。

2.4 常见错误码

• 通用：100（未知）、101（无参数）、102（API 不存在）、105（无权限）、106（超时）、107（重复登录）。
• 文件操作：400（无效参数）、408（无文件/目录）、414（文件存在）、415（配额超限）、418（非法名称）、599（无任务）。

2.5 示例操作

检索信息 → 登录 → 列出共享文件夹 → 获取详情 → 登出。

第 3 章：基础 API

SYNO.API.Info（版本1，DSM 4.0+）

• 方法：query
  • 参数：query（API 名或 “all”）。
  • 响应：API 描述（path、minVersion、maxVersion）。
  • 示例响应：{“SYNO.API.Auth”: {“path”: “auth.cgi”, “minVersion”: 1, “maxVersion”: 3}}。
• 错误码：无特定。

SYNO.API.Auth（版本3，DSM 4.0+）

• 方法：login
  • 参数：account（用户名）、passwd（密码）、session（会话名）、format（cookie/sid）、otp_code（保留）。
  • 响应：sid。
• 方法：logout
  • 参数：session。
  • 响应：空成功。
• 错误码：400（密码错）、401（账户禁用）、402（权限拒）、403（需2FA）、404（2FA失败）。

第 4 章：File Station API

所有 API 需登录 session=FileStation。支持附加信息（additional）：real_path、size、owner（user/group/uid/gid）、time（atime/mtime/ctime/crtime）、perm（posix、acl_enable、is_acl_mode、acl: append/del/exec/read/write）、mount_point_type、volume_status（freespace/totalspace/readonly）。

SYNO.FileStation.Info（版本2，DSM 6.0+）

• 方法：get（无参数）
  • 响应：is_manager（是否管理员）、support_virtual_protocol（cifs,iso等）、support_sharing、hostname。
• 错误码：无特定。

SYNO.FileStation.List（版本2，DSM 6.0+）

• 方法：list_share（列共享文件夹）
  • 参数：offset、limit、sort_by（name/user/group/mtime/atime/ctime/crtime/posix）、sort_direction（asc/desc）、onlywritable、additional。
  • 响应：total、offset、shares[]（path、name、additional）。
• 方法：list（枚举文件夹）
  • 参数：folder_path、offset、limit、sort_by（+size/type）、sort_direction、pattern（glob）、filetype（file/dir/all）、goto_path、additional。
  • 响应：total、offset、files[]（path、name、isdir、children[]、additional）。
• 方法：getinfo（文件信息）
  • 参数：path（数组）、additional。
  • 响应：files[]（同list）。
• 错误码：无特定。

SYNO.FileStation.Search（版本2，DSM 6.0+）

• 非阻塞：start → list/stop → clean。
• 方法：start（开始搜索）
  • 参数：folder_path（数组）、recursive、pattern、extension、filetype、size_from/to、mtime_from/to、crtime_from/to、atime_from/to、owner、group。
  • 响应：taskid。
• 方法：list（列结果）
  • 参数：taskid、offset、limit、sort_by（同List+pack_size）、sort_direction、pattern、filetype、