相关文章推荐
兴奋的鞭炮  ·  Python 分组处理_ITPUB博客·  1 年前    · 
月球上的乌冬面  ·  记一次白屏兼容性问题的解决 - 掘金·  1 年前    · 
彷徨的香菇  ·  Vue中实现清空数组和清空el-table_ ...·  1 年前    · 
干练的西红柿  ·  入坑MATLAB必会的吐血总结 - ...·  1 年前    · 
Code  ›  《Synology File Station Official API》第二章-入门 - sherlock-merlin
软件 api webapi synology
https://www.cnblogs.com/sherlock-merlin/articles/15981309.html
深沉的单杠
1 年前

#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 响应包含以下元素： 
    

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

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

    失败响应：
    
    "success": false,
    "error": {
        "code": 101

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

    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/:"

    响应从 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 的参数错误或登录失败的常见错误代码。 
    

    以下演示了从 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
     
    推荐文章
    兴奋的鞭炮  ·  Python 分组处理_ITPUB博客
    1 年前
    月球上的乌冬面  ·  记一次白屏兼容性问题的解决 - 掘金
    1 年前
    彷徨的香菇  ·  Vue中实现清空数组和清空el-table_vue2清空数组_霸道流氓气质的博客-CSDN博客
    1 年前
    干练的西红柿  ·  入坑MATLAB必会的吐血总结 - cruelty_angel - 博客园
    1 年前
    今天看啥   ·   Py中国   ·   codingpro   ·   藏经阁   ·   小百科   ·   link之家   ·   卧龙AI搜索
    删除内容请联系邮箱 2879853325@qq.com
    Code - 代码工具平台
    © 2024 ~ 沪ICP备11025650号