《Synology File Station Official API》第二章-入门

#1f4970

官方英文版链接《Synology File Station Official API》

在使用 File Station API 开发自己的应用程序之前，您需要对 API 概念和 API 程序有基本的了解。 

本章分以下五个部分解释如何执行和完成 API 流程： 

  • API 工作流程：简要介绍如何使用 File Station API
  • 发出请求：详细说明如何构造 API 请求
  • 解析响应：描述如何解析响应数据
  • 常见错误代码：列出所有 File Station API 可能返回的所有常见错误代码
  • 工作示例：提供请求文件操作的示例

 

API 工作流程

以下五个步骤且易于遵循的工作流程展示了如何让您的应用程序与 File Station API 交互。 

步骤 1：检索 API 信息

首先，您的应用程序需要从目标 DiskStation 检索 API 信息，以了解哪些 API 可在目标 DiskStation 上使用。可以通过 /webapi/query.cgi 使用 SYNO.API.Info API 参数响应中提供的信息包含可用的 API 名称、API 方法、API 路径和 API 版本。一旦您掌握了所有信息，您的应用程序就可以向所有可用的 API 发出进一步的请求。 

步骤 2：登录

为了让您的应用程序与 File Station 交互，您的应用程序需要先使用帐户和密码登录。登录过程只是使用 login 方法向 SYNO.API.Auth API 发出请求。如果成功，API 会返回一个授权的会话 ID。您应该保留它并将其传递给其他 API 请求。 

第 3 步：发出 API 请求

成功登录后，您的应用程序可以开始向所有可用的 File Station API 发出请求。在下一节“发出请求”中，将给出如何形成有效的 API 请求以及如何解码响应信息的说明。 

第 4 步：注销

完成上述步骤后，您的应用程序可以通过 注销 方法。

 

发出请求 

有五个基本元素可用于构建对任何 API 的有效请求。

  • API name: API请求的名字
  • version: API请求的版本
  • path: API的路径。可以通过请求 SYNO.API.Info 来检索路径信息
  • method: API请求的方法
  • _sid: 授权会话 ID。每个 API 请求都应该通过它，它是从 /webapi/auth.cgi ，通过带有 _sid 参数的 HTTP/HTTPS GET/POST 方法。否则，如果你在 id HTTP/HTTPS header的cookie值，该参数可以忽略。

请求的语法如下： 

GET /webapi/<CGI_PATH>?api=<API_NAME>&version=<VERSION>&method=<METHOD>[&<PARAMS>][&_sid=<SID>]

这里 <参数> 表示请求方法的参数，是可选的。请注意，所有参数都需要转义。逗号“，”替换为斜杠“\”，斜杠“\”替换为双斜杠“\\”，因为逗号“，”用于分隔参数中的多个元素。密码相关参数不需要转义，包括 passwd 或密码参数。 

请看下面的例子。如果您想在 查询 地址为 http://myds.com:port （HTTP 和 HTTPS 的默认端口分别为 5000 或 5001）对于所有可用 API 方法的列表，对应的参数是：

  • API name: SYNO.API.Info
  • version: 1
  • path: query.cgi
  • method: query
  • _sid: query=all

请求将如下所示： 

http://myds.com:port/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query&query=all 

请注意，可以通过向 SYNO.API.Info 发送请求来获取 API 的路径和支持的版本信息。 SYNO.API.Info 的位置是固定的，因此您始终可以使用 /webapi/query.cgi 请求 SYNO.API.Info 。



解析响应

所有 API 响应都以 JSON 格式编码，JSON 响应包含以下元素： 

键 

值 

描述

success 

true/false 

“true”：请求成功完成； “false”：请求失败并返回错误数据。

data 

<JSON 样式  Object>

数据对象包含每个方法中描述的所有响应信息。

error 

<JSON 样式  Object>

数据对象包含请求失败时的错误信息。下表描述了基本元素。



下面描述错误元素中错误信息的格式。 

键 

值 

描述

code 

错误 

代码。

请求失败时返回错误码错误码有两种：一种是所有 API 共享的通用错误码；另一个是特定的 API 错误代码（在相应的 API 规范中描述）。

errors

<JSON 样式 数组>

该数组包含每个文件的详细错误信息。错误中的每个元素都是一个 JSON 样式的对象，其中包含错误代码和其他信息，例如文件路径或名称。  

注意：当没有详细信息时，此错误元素将不会响应。



示例 1

在没有方法参数的情况下响应无效请求以获取 File Station 的信息。 

请求：

http://myds.com:port/webapi/entryFilStation/info.cgi?api=SYNO.FileStation.Info&version=2&method=get

失败响应：

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

 

示例 2

使用非法路径响应无效请求以创建文件夹。 

请求： 

http://myds.com:port/webapi/FilStation/info.cgi?api=SYNO.FileStation.CreateFolder&method=create&version=1&folder_path=%2Ftest&name=%3A

失败响应：

{
    "success": false,
    "error": {
        "code": 1100,
        "errors": [
            {
                "code": 418,
                "path": "/test/:"
            }
        ]
    }
}

 

示例3

响应从 File Station 获取信息的成功请求。

请求：

http://myds.com:port/webapi/FilStation/info.cgi?api=SYNO.FileStation.Info&version=2&method=get

成功响应：

{
    "success": true,
    "data": {
        "is_manager": true,
        "hostname": "DS",
        "support_sharing": true,
        "support_virtual": "cifs,iso"
    }
}
 

请注意，为了清楚地演示示例，以下部分中给出的响应示例中仅包含数据对象。

 

 

常见错误代码

以下代码是所有 WebAPI 的参数错误或登录失败的常见错误代码。 

代码

说明

100 

未知错误

101 

API、方法或版本没有参数

102 

请求的 API 不存在

103 

请求的方法不存在

104 

请求的版本不支持该功能

105 

登录的会话没有权限

106 

会话超时

107 

会话因重复登录而中断

119 

SID 未找到

 

下面列出的代码是所有 File Station API 的文件操作的常见错误代码。

代码

说明

400 

文件操作参数无效

401 

未知错误

402 

系统太忙

403 

无效用户执行此文件操作

404 

无效组执行此文件操作

405 

无效用户和组执行此文件操作

406 

无法 从帐户服务器获取用户/组信息

407 

不允许操作

408 

没有这样的文件或目录

409 

不支持的文件系统

410 

无法连接基于 Internet 的文件系统（例如，CIFS）

411 

只读文件系统

412 

文件名太长在非加密文件系统中

413 

在加密文件系统中文件名太长

414 

文件已存在

415 

磁盘配额超出

416 

设备上没有剩余空间

417 

输入/输出错误

418 

非法名称或路径

419 

非法文件名

420 

FAT 上的非法文件名文件系统

421 

设备或资源繁忙

599 

文件操作没有此类任务

 

 

工作示例

以下演示了从 DiskStation 请求文件操作的工作示例。要实施此示例，只需将示例中使用的 DiskStation 地址 (myds.com:port) 替换为您的 DiskStation 地址并将 URL 粘贴到浏览器。然后 JSON 响应将显示在响应页面中。 

 

第 1 步：获取 API 信息

为了发出 API 请求，您应该首先 /webapi/query.cgi 以获取用于登录的 SYNO.API.Auth API 信息和用于文件操作的 FileStation API 信息. 

请求：

http://myds.com:port/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query&

query=SYNO.API.Auth,SYNO.FileStation 

响应：

{
    "data": {
        "SYNO.API.Auth": {
            "path": "auth.cgi",
            "minVersion": 1,
            "maxVersion": 3
        },
        "SYNO.FileStation.List": {
            "path": "FileStation/file_share.cgi",
            "minVersion": 1,
            "maxVersion": 1
        }
    },
    "success": true
}

 

第 2 步：登录

在返回 SYNO.API.Auth 路径和支持的版本信息后，您可以通过请求位于 /webapi/auth.cgi 的 SYNO.API.Auth API 版本 3 来登录 FileStation 会话 。 

请求：

http://myds.com:port/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=admin&

passwd=12345&session=FileStation&format=cookie 

响应：

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

 

第 3 步：请求 File Station API

会话登录后，您可以继续调用 SYNO.FileStation.List 中列出共享文件夹的方法。在Step 1的响应中提供了cgi路径和版本，可以通过排除 offset 和 limit 参数来请求所有任务的列表。 

请求：

http://myds.com:port/webapi/FileStation/file_share.cgi?api=SYNO.FileStation.List&version=1&method=list_share

响应：

{
    "data": {
        "offset": 0,
        "shares": [
            {
                "isdir": true,
                "name": "video",
                "path": "/video"
            },
            {
                "isdir": true,
                "name": "photo",
                "path": "/photo"
            }
        ],
        "total": 2
    },
    "success": true
}

列表中可以看出 File Station 中有两个共享文件夹。假设您对共享文件夹“照片”感兴趣并想了解有关它的更多详细信息，您可以向 getinfo 方法。在此请求中，您需要添加参数 additional=real_path,owner,time 用于请求详细对象并在响应中传输它们的方法。 

请求：

http://myds.com:5000/webapi/FileStation/file_share.cgi?api=SYNO.FileStation.List&version=1&
method=getinfo&path=%2Fphoto&additional=real_path,owner,time,perm

响应：

{
    "data": {
        "files": [
            {
                "additional": {
                    "owner": {
                        "gid": 100,
                        "group": "users",
                        "uid": 1024,
                        "user": "admin"
                    },
                    "real_path": "/volume1/photo",
                    "time": {
                        "atime": 1371630215,
                        "crtime": 1352168821,
                        "ctime": 1368769689,
                        "mtime": 1368769689
                    }
                },
                "isdir": true,
                "name": "photo",
                "path": "/photo"
            }
        ]
    },
    "success": true
}

 

第 4 步：注销

完成该过程后，您应该注销当前会话。会话将通过调用 注销 SYNO.API.Auth 中的方法。如果要注销特定会话，可以通过设置 _sid 参数。 

示例：

http://myds.com:5000/webapi/auth.cgi?api=SYNO.API.Auth&version=1&method=logout&session=FileStation

 

posted @ 2022-03-08 19:24  sherlock-merlin  阅读(1955)  评论(0)  编辑  收藏  举报