库文件操作

更新: 2025-10-30

• 文件列表
• 文件最近更新列表
• 文件更新数量
• 文件下载链接
• 文件预览/批注链接
• 文件协同编辑链接
• 文件（夹）信息
• 文件搜索
• 创建文件夹
• 上传文件
• 网页上传
• 复制文件（夹）
• 高级复制文件（夹）
• 移动文件（夹）
• 删除文件（夹）
• 彻底删除文件（夹）
• 回收站
• 恢复已删除文件
• 获取文件历史
• 获取文件外链
• 关闭文件外链
• 获取开启外链的文件列表
• 文件锁的操作
• 设置文件夹权限继承状态
• 获取文件夹单独设置的权限
• 修改文件夹权限
• 重置或移除文件夹权限
• 获取文件权限
• 添加标签
• 删除标签
• 添加或修改元数据
• 删除元数据
• 统计信息
• 查询队列状态

API域名

Host: yk3.gokuai.com

注意: 库文件操作API使用的secret是 库授权 后获得的 org_client_secret

参数说明

sign

参考 访问控制 中的算法说明, 对接口请求参数进行签名计算, 如果接口返回错误: error_code=401041, 表示签名验证失败, 可能是由于中文编码不一致导致的

所有接口参数的编码必须是UTF-8编码, 并且需要进行URL编码, 具体参考 约定

fullpath

文件或文件夹在文件库中的完整路径

例如:

fullpath=readme.txt 表示存放在文件库根目录下的名为readme.txt的文件

fullpath=documents/project.docx 表示存放在名为documents的文件夹下, 文件名为project.docx的文件

filename

文件或文件夹的名称, 同一个文件夹下不能存在两个相同filename的文件或文件夹

hash

文件或文件夹在文件库中的唯一标识, 改名或移动并不会修改hash的值

filehash

文件内容的checksum值, 是文件内容的唯一标识, 文件名不同, 但文件内容相同, 它们的filehash是相同的

op_id

用于指定操作人ID, 即云库中的用户ID

op_name

用来指定操作人名称, 开发API是以最高权限对文件进行操作, 如果需要在云库用户界面中显示具体操作人名称, 可以用op_name来指定用于显示的姓名

文件列表

POST /m-open/1/file/ls HTTP/1.1

请求参数

返回格式

json

返回结果

{
    count:
    list:
    [
        {
            hash:
            dir:
            fullpath:
            filename:
            filehash:
            filesize:
            create_member_name:
            create_dateline:
            last_member_name:
            last_dateline:
            property:
        },
        ...
    ]
}

• property中的tag, 多个标签使用分号;分隔

文件最近更新列表

POST /m-open/1/file/updates HTTP/1.1

请求参数

注意

• mode为空时, 按操作时间 倒序 获取数据, 获取操作时间早于 fetch_dateline的数据, 如果fetch_dateline不传、为空或为0时, 从当前时间开始获取列表, 返回的列表中不包括已删除的文件

• mode = compare时, 按操作时间 顺序 获取数据, 获取操作时间迟于 fetch_dateline的数据, fetch_dateline=0时, 从最早操作的文件开始获取列表, 返回的列表中包括已删除的文件

• 每次请求最多只会返回100条数据, 如果要获取所有数据, 需要将每次返回的fetch_dateline作为下一次请求的参数

• 锁定, 解锁, 标签变化, 权限变化也会变更操作时间

返回格式

json

返回结果

文件更新数量

POST /m-open/1/file/updates_count HTTP/1.1

请求参数

返回格式

json

返回结果

{
    count: 更新数量
}

文件下载链接

POST /m-open/1/file/download_url HTTP/1.1

文件下载链接一般的有效时间仅为10分钟, 过期后下载链接无法使用, 根据存储类型不同可能会返回多个下载链接

请求参数

返回格式

json

返回结果

{
    "urls": [文件下载链接数组(可能有多个下载链接)]
}

文件预览/批注链接

POST /m-open/1/file/preview_url HTTP/1.1

请求参数

获取预览链接

获取批注链接

需要开通批注功能, 只支持PDF和图片文件

返回格式

json

返回结果

{
    "url": 文档预览链接(10分钟有效),
    "thumbnail": 缩略图链接(图片文件才支持)
}

预览页面事件通知

使用iframe引用预览页面, 并增加message事件监听

<iframe frameborder="0" src="{预览URL}"></iframe>
<script type="text/javascript">
window.addEventListener('message', function (e) {
    try {
        const msg = JSON.parse(e.data);
        if (typeof msg === 'object' && msg.type == 'GK_VIEWER_EVENT') {
            //msg结构见下面的说明
        }
    } catch (err) {
        console.error(err);
    }
});
</script>

msg 结构

• 文档, 加载成功和换页时触发

{
  "type": "GK_VIEWER_EVENT",
  "page": {
    "current": 1,
    "total": 23
  },
  "time": 1612839014841
}

• 视频和音频, 开始播放和结束时触发, 播放中每5秒触发一次

{
  "type": "GK_VIEWER_EVENT",
  "progress": {
    "current": 18.208222,
    "total": 1260.34
  },
  "time": 1612839014841
}

current和total单位: 秒

文件协同编辑链接

需要开通协同编辑功能, 只支持Office文档

POST /m-open/1/file/cedit_url HTTP/1.1

注意: 协同编辑不支持匿名编辑, 必须指定编辑人, 参数op_id、out_id、account必须传其中一个

返回格式

json

返回结果

{
    "url": 协同编辑链接
}

文件（夹）信息

注意: 当前接口返回的数据较多, 会消耗大量服务器资源, 请慎重调用

POST /m-open/1/file/info HTTP/1.1

请求参数

返回格式

json

返回结果

默认返回:

{
    hash:
    dir:
    fullpath:
    filename:
    filesize:
    create_member_name:
    create_dateline:
    last_member_name:
    last_dateline:
    uri:
    preview:
    thumbnail:
    tag:
    file_count:
    folder_count:
    files_size:
    property:
}

当attribute=10时, 返回:

{
    hash:
    dir:
    fullpath:
    filename:
    filehash:
    filesize:
}

• property中的tag, 多个标签使用分号;分隔

文件搜索

POST /m-open/1/file/search HTTP/1.1

请求参数

返回格式

同文件列表

创建文件夹

POST /m-open/1/file/create_folder HTTP/1.1

请求参数

返回格式

{
    "hash": "文件唯一标识",
    "fullpath": "文件夹完整路径"
}

上传文件

分块方式上传文件

步骤1: 请求上传

POST /m-open/1/file/create_file HTTP/1.1

请求参数

返回格式

步骤2: 分块上传文件

请参考文档: 分块上传

网页上传

通过网页表单方式直接上传文件

步骤1: 获取上传服务器

注意: 请使用后端代码调用该接口, 防止org_client_secret外泄

POST /m-open/1/file/upload_servers HTTP/1.1

请求参数

返回格式

{
    "m-upload": [
        "http://upload_server",
        ...
    ],
    "key": "上传密钥"
}

步骤2: 上传文件

使用multipart/form-data表单方式上传文件

POST /2/web_upload HTTP/1.1
Host: {upload_server}
Content-Type: multipart/form-data; boundary=xxxxx

请求参数

返回格式

{
    "fullpath": "文件完整路径",
    "filesize": 文件大小,
    "hash": "文件唯一标识"
}

复制文件（夹）

POST /m-open/1/file/copy HTTP/1.1

请求参数

返回格式

json

返回结果

{
  "hash": "文件唯一标识",
  "fullpath": "文件完整路径",
  "queue_id": "队列ID"
}

注意: 如果返回了 queue_id 表示进入异步处理队列, 请求返回并不代表已完成操作, 调用 查询队列状态 查询执行结果

高级复制文件（夹）

POST /m-open/1/file/mcopy HTTP/1.1

请求参数

返回格式

json

返回结果

[
  {
    "hash": "文件文件唯一标识",
    "fullpath": "文件完整路径",
    "queue_id": "队列ID"
  },
  ...
]

字段说明见 复制文件（夹）

移动文件（夹）

POST /m-open/1/file/move HTTP/1.1

请求参数

返回格式

json

返回结果

HTTP 200

删除文件（夹）

POST /m-open/1/file/del HTTP/1.1

请求参数

返回格式

json

返回结果

HTTP 200

彻底删除文件（夹）

POST /m-open/1/file/del_completely HTTP/1.1

请求参数

返回格式

json

返回结果

HTTP 200

回收站

POST /m-open/1/file/recycle HTTP/1.1

请求参数

返回格式

json

返回结果

{
    count:
    list:
    [
        {
            hash:
            dir:
            fullpath:
            filename:
            filehash:
            filesize:
            create_member_name:
            create_dateline:
            last_member_name:
            last_dateline:
        },
        ...
    ]
}

恢复已删除文件

POST /m-open/1/file/recover HTTP/1.1

请求参数

返回格式

json

返回结果

HTTP 200

获取文件历史

POST /m-open/1/file/history HTTP/1.1

请求参数

返回格式

json

返回结果

{
  "count":
  "list":[
      {
        "hid":
        "act":
        "act_name":
        "dir":
        "hash":
        "fullpath":
        "filehash":
        "filesize":
        "member_id":
        "member_name":
        "dateline":
        "property":
      },
      ...
    ]
}

获取文件外链

POST /m-open/1/file/link HTTP/1.1

请求参数

返回格式

json

返回结果

{
  "link": "文件外链",
  "code": "外链码"
}

关闭文件外链

POST /m-open/1/file/link_close HTTP/1.1

请求参数

注意: code和fullpath只需传其中一个参数

返回结果

HTTP 200

获取开启外链的文件列表

POST /m-open/1/file/links HTTP/1.1

请求参数

返回结果

[
    {
        "filename": 文件名或文件夹名,
        "filesize": 文件大小,
        "link": 文件外链,
        "deadline": 到期时间戳 -1表示永久有效,
        "password": 是否加密, 1加密, 0无
    },
    ...
]

文件锁的操作

POST /m-open/1/file/lock HTTP/1.1

请求参数

返回结果

HTTP 200

设置文件夹权限继承状态

POST /m-open/1/file/set_permission_inherit

请求参数

返回结果

HTTP 200

获取文件夹单独设置的权限

注意: 仅返回单独设置的权限, 不包括从上级或部门继承的权限

POST /m-open/1/file/get_all_permission HTTP/1.1

请求参数

返回结果

见 权限返回结果

修改文件夹权限

POST /m-open/1/file/file_permission HTTP/1.1

请求参数

返回结果

HTTP 200

重置或移除文件夹权限

POST /m-open/1/file/reset_permission HTTP/1.1

注意:

• 当文件夹为继承状态时, 该操作将重置指定成员或部门的权限, 使之与上级文件夹权限保持一致; 如果成员通过部门加入, 则重置后权限与部门权限保持一致
• 当文件夹为非继承状态时, 该操作将移除指定成员或部门, 如果成员通过部门加入, 由于无法移除这些成员, 配合 clear 参数:
  1. 不传或传 0 重置成员权限, 使之与所在部门的权限保持一致
  2. 传 1 清空成员权限

返回结果

HTTP 200

获取文件权限

POST /m-open/1/file/get_permission HTTP/1.1

请求参数

返回结果

如果指定了用户:

[
  "file_read",
  "file_preview",
  "file_write",
  "file_delete"
]

未指定用户时, 返回结果见 权限返回结果 , 注意结果中仅返回members

添加标签

POST /m-open/1/file/add_tag HTTP/1.1

请求参数

返回结果

HTTP 200

删除标签

POST /m-open/1/file/del_tag HTTP/1.1

请求参数

返回结果

HTTP 200

添加或修改元数据

需要先在企业管理后台按需配置元数据模版和属性, 并在文件库上关联元数据模版

POST /m-open/1/file/set_metadata HTTP/1.1

请求参数

注意

• 参数metadata的类型为JSON Object字符串, 内容为需要添加或修改的元数据属性, JSON Object的键为元数据属性的key

例如, 设置归档状态和归档时间, 归档状态的key为4736_620f629b9d63f 字符串型, 归档时间的key为4736_62b93d22140fc 时间型

{
    "4736_620f629b9d63f": "已归档",
    "4736_62b93d22140fc": "2022-03-01 12:00:00",
    ...
}

各类型属性的值举例:

• 参数display用于指定哪些属性需要在文件列表上展示, 如果不指定则不展示在文件列表

返回结果

HTTP 200

删除元数据

POST /m-open/1/file/del_metadata HTTP/1.1

请求参数

返回结果

HTTP 200

统计信息

POST /m-open/1/file/stat HTTP/1.1

请求参数

返回结果

{
    "org_id": ,
    "org_name": ,
    "mount_id": ,
    "capacity": ,
    "size": ,
    "size_recycle": ,
    "count_file": ,
    "storage_point": 
}

查询队列状态

POST /m-open/1/file/queue_status HTTP/1.1

请求参数

返回格式

json

返回结果

{
  "status": 状态,
  "fullpath": "完整路径",
  "add_dateline": 加入时间戳,
  "start_dateline": 开始时间戳,
  "finish_dateline": 结束时间戳
}

权限返回结果

{
  "members":
  {
    用户ID:
    [
      "file_preview",
      "file_read",
      "file_upload",
      "file_write",
      "file_delete",
      "file_link"
    ],
    ...
  },
  "groups":
  {
    部门ID:
    [
      "file_preview",
      "file_read",
      "file_upload",
      "file_write",
      "file_delete",
      "file_link"
    ],
    ...
  }
}