库文件操作

更新: 2018-11-8

API域名

Host: yk3-api-ent.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_name

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


文件列表

POST /1/file/ls HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath 文件夹路径, 空字符串表示根目录
tag 返回fullpath下所有层级中带指定标签的文件及文件夹
start 开始位置, 默认0
size 返回条数, 默认100
hashs 获取指定hash的文件, 半角逗号,分隔
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

{
    count:
    list:
    [
        {
            hash:
            dir:
            fullpath:
            filename:
            filehash:
            filesize:
            create_member_name:
            create_dateline:
            last_member_name:
            last_dateline:
            property:
        },
        ...
    ]
}
字段 类型 说明
count int 文件总数
list array 格式见下
字段 类型 说明
hash string 文件唯一标识
dir int 是否文件夹, 1是, 0否
fullpath string 文件路径
filename string 文件名称
filehash string 文件内容hash, 如果是文件夹, 则为空
filesize long 文件大小, 如果是文件夹, 则为0
create_member_name string 文件创建人名称
create_dateline int 文件创建时间戳
last_member_name string 文件最后修改人名称
last_dateline int 文件最后修改时间戳
property json {"tag": "标签", "op_name": "操作人名称", "permisson": 文件权限}

文件最近更新列表

POST /1/file/updates HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
mode 获取模式, 空或compare, 详情见下面的注意项
fetch_dateline unix时间戳, 单位毫秒, 默认0
dir 获取文件或文件夹, 不传表示都返回, 1只返回文件夹, 0只返回文件
dateline 当前unix时间戳, 单位秒
sign 签名

注意

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

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

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

返回格式

json

返回结果

字段 类型 说明
fetch_dateline int 单位毫秒; 当mode为空时, 返回list中最小的操作时间; 当modecompare时, 返回list中最大的操作时间
list array 格式见下
字段 类型 说明
cmd int 当mode=compare 时才会返回cmd字段, 0表示删除, 1表示未删除
hash string 文件唯一标识
dir int 是否文件夹, 1是, 0否
fullpath string 文件路径
filename string 文件名称
filehash string 文件内容hash, 如果是文件夹, 则为空
filesize long 文件大小, 如果是文件夹, 则为0
create_member_name string 文件创建人名称
create_dateline int 文件创建时间戳, 单位秒
last_member_name string 文件最后修改人名称
last_dateline int 文件最后修改时间戳, 单位秒

文件更新数量

POST /1/file/updates_count HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
begin_dateline unix时间戳, 单位毫秒, 开始时间
end_dateline unix时间戳, 单位毫秒, 结束时间
showdel 1同时返回删除的文件, 默认0不返回
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

{
    count: 更新数量
}

文件下载地址

POST /1/file/download_url HTTP/1.1

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

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath - 文件路径, 需传fullpathhash其中一个参数
hash - 文件唯一标识, 需传fullpathhash其中一个参数
filehash 文件内容唯一标识, 用于下载历史版本, 不传表示下载当前版本
open 1返回能直接在浏览器中打开的文件地址, 默认0
filename 指定下载文件名,默认使用原名称
net in表示获取内网下载地址, 默认空返回公网地址
op_id - 操作人ID, 如果操作人不是云库用户, 可以用op_name代替
op_name - 操作人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

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

文件预览地址

POST /1/file/preview_url HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath - 文件路径, 需传fullpathhash其中一个参数
hash - 文件唯一标识, 需传fullpathhash其中一个参数
watermark 1显示水印, 默认0不显示
member_name 在水印中显示的文档查看人姓名
thumbnail 1返回图片缩略图地址, 默认0不返回
op_id - 操作人ID, 如果操作人不是云库用户, 可以用op_name代替
op_name - 操作人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

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

文件(夹)信息

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

POST /1/file/info HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath - 文件路径, 需传fullpathhash其中一个参数
hash - 文件唯一标识, 需传fullpathhash其中一个参数
net in表示获取内网下载地址, 默认空返回公网地址
attribute 1表示获取额外属性, 包括子文件数量、大小,子文件夹数量, 10只返回最基础的信息, 默认0
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

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:
}
字段 类型 说明
hash string 文件唯一标识
dir int 是否文件夹
fullpath string 文件路径
filename string 文件名称
filehash string 文件内容hash
filesize long 文件大小
create_member_name string 文件创建人
create_dateline int 文件创建时间戳(10位精确到秒)
last_member_name string 文件最后修改人
last_dateline int 文件最后修改时间戳(10位精确到秒)
uri string 文件下载地址
preview string 文件预览地址
thumbnail string 文件缩略图地址
tag string 文件标签
file_count int 子文件数量
folder_count int 子文件夹数量
files_size int 子文件大小
property json {"tag": "标签", "op_name": "操作人名称", "permisson": 文件权限}

文件搜索

POST /1/file/search HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
keywords 搜索关键字
path 需要搜索的文件夹, 默认空搜索整个库
scope json字符串,默认["filename","tag"], filename按文件名、tag按标签、content按全文检索
start 开始位置, 默认0
size 返回条数, 默认100
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

文件列表


创建文件夹

POST /1/file/create_folder HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件夹路径
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

字段 类型 说明
hash string 文件唯一标识
fullpath string 文件夹的路径

上传文件

分块方式上传文件

步骤1: 请求上传

POST /1/file/create_file HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
filehash 文件内容sha1值, 40字节, 英文字母小写, 不参与签名计算
filesize 文件大小, 不参与签名计算
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
overwrite 是否覆盖同名文件, 1覆盖, 默认0不覆盖, 文件名后增加数字标识
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

字段 类型 说明
hash string 文件唯一标识
fullpath string 文件完整路径
state int 是否需要调用分块上传, 0需要,1不需要(已秒传)
server string 上传服务器

步骤2: 分块上传文件

请参考文档: 分块上传


网页上传

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

步骤1: 获取上传服务器

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

POST /1/file/upload_servers HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
timeout 返回的上传临时密钥有效时间, 单位秒, 如300, 表示5分钟后失效
rand 随机字符串, 长度任意
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

{
    "m-upload": [
        "http://upload_server",
        ...
    ],
    "key": "上传密钥"
}
名称 说明
m-upload 上传服务器, 内容为数组, 可随机选择一个, 上传服务器包含协议和端口
key 上传的临时密钥, 在实际上传文件时使用, 密钥经过timeout秒后将失效

步骤2: 上传文件

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

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

请求参数

参数 必需 说明
org_client_id 库授权client_id
key 上传的临时密钥
path 上传的目标文件夹, 根目录传空字符串
name 文件名
overwrite 是否覆盖同名文件, 1覆盖, 默认0不覆盖, 文件名后增加数字标识
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
filefield 固定值file
file 上传的文件内容

返回格式

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

复制文件(夹)

POST /1/file/copy HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
from_fullpath 源文件路径
fullpath 目标文件完整路径(含文件名)
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200


高级复制文件(夹)

POST /1/file/mcopy HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
from_fullpaths 源文件路径 , 如果多个使用竖号 | 分隔
paths 目标文件夹(不包含文件名), 如果复制多份使用竖号 | 分隔
copy_all 1复制文件的所有属性, 包括操作人, 默认0不复制
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
sp 特殊参数, 预留
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200


删除文件(夹)

POST /1/file/del HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath - 文件完整路径, fullpathtag只需传其中一个
tag - 通过标签删除, 多个使用分号;分隔, fullpathtag只需传其中一个
path - 路径, 当使用tag方式删除时, 可以指定路径进行删除, 默认空, 不指定
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
destroy 1彻底删除文件, 不进回收站, 默认0删除文件进入回收站
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200


回收站

POST /1/file/recycle HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
start 开始位置, 默认0
size 返回条数, 默认100
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

{
    count:
    list:
    [
        {
            hash:
            dir:
            fullpath:
            filename:
            filehash:
            filesize:
            create_member_name:
            create_dateline:
            last_member_name:
            last_dateline:
        },
        ...
    ]
}
字段 类型 说明
count int 文件总数
list array 格式见下
字段 类型 说明
hash string 文件唯一标识
dir int 是否文件夹, 1是, 0否
fullpath string 文件路径
filename string 文件名称
filehash string 文件内容hash, 如果是文件夹, 则为空
filesize long 文件大小, 如果是文件夹, 则为0
create_member_name string 文件创建人名称
create_dateline int 文件创建时间戳, 单位秒
last_member_name string 文件最后修改人名称
last_dateline int 文件最后修改时间戳, 单位秒

恢复已删除文件

POST /1/file/recover HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpaths 文件路径,多个使用竖号 | 分隔
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200


彻底删除文件(夹)

POST /1/file/del_completely HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpaths - 文件路径,多个使用竖号 | 分隔
tag - 通过标签删除, 多个使用分号;分隔, fullpathstag只需传其中一个
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200


移动文件(夹)

POST /1/file/move HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 要移动文件的路径
dest_fullpath 移动后的路径
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200


获取文件历史

POST /1/file/history HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
start 开始位置, 默认0
size 返回条数, 默认20
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

{
  count:
  list:[
      {
              hid:
            act:
            act_name:
            dir:
            hash:
            fullpath:
            filehash:
            filesize:
            member_id:
            member_name:
            dateline:
            property:
      }
      ...
    ]
}
字段 类型 说明
count int 历史总数
list array 格式见下
字段 类型 说明
hid string 历史版本ID
act int 具体文件操作类型
act_name string 具体文件操作类型描述
dir int 是否文件夹, 1是, 0否
hash string 文件唯一标识
fullpath string 文件路径
filename string 文件名称
filehash string 文件内容hash, 如果是文件夹, 则为空
filesize long 文件大小, 如果是文件夹, 则为0
member_id int 文件操作人
member_name string 文件操作人名称
dateline int 文件操作时间戳, 单位秒
property string 扩展属性, macheine, ip等

获取文件外链

POST /1/file/link HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
deadline 到期时间时间戳,默认48小时后
auth preview文件预览, download文件预览和下载, upload预览、下载、文件夹上传,默认preview
password 访问密码
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

{
  "link": "外链地址",
  "code": "外链码"
}

关闭文件外链

POST /1/file/link_close HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
code - 外链码, 关闭该码对应的外链
fullpath - 文件完整路径, 关闭该文件的所有外链
dateline 当前unix时间戳, 单位秒
sign 签名

注意: codefullpath只需传其中一个参数

返回结果

HTTP 200


获取开启外链的文件列表

POST /1/file/links HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
file 是否只返回文件, 1只返回文件, 0全部返回, 默认0
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

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

获取文件夹所有权限

POST /1/file/get_all_permission HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath 文件夹完整路径
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

文件属性的权限字段

权限说明

权限 说明
file_preview 预览
file_read 下载
file_upload 上传新文件或新建文件夹
file_write 上传或修改
file_delete 删除
file_link 外链

修改文件夹权限

POST /1/file/file_permission HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath 文件夹完整路径
permissions 权限, 如 {用户ID: ["file_preview", "file_read"], ...}{部门ID: ["file_preview", "file_read"], ...}
is_group 1设置部门权限, 默认0设置用户权限
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

HTTP 200


获取用户在文件夹的权限

POST /1/file/get_permission HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath 文件夹完整路径
member_id - 用户ID, member_idout_id必需指定其中一个参数
out_id - 用户外部系统唯一ID, member_idout_id必需指定其中一个参数
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

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

添加标签

POST /1/file/add_tag HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
tag 标签, 多个使用分号;分隔
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

HTTP 200


删除标签

POST /1/file/del_tag HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
tag 标签, 多个使用分号;分隔
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

HTTP 200


统计信息

POST /1/file/stat HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
dateline 当前unix时间戳, 单位秒
sign 签名

返回结果

{
    "org_id": ,
    "org_name": ,
    "mount_id": ,
    "capacity": ,
    "size": ,
    "size_recycle": ,
    "count_file": ,
    "storage_point": 
}
字段 类型 说明
org_id int 库ID
org_name string 库名称
mount_id int 库空间ID
capacity int 空间配额, 单位字节
size int 已使用空间, 单位字节
size_recycle int 已使用空间中回收站的占用, 单位字节
count_file int 文件数量, 不包括文件夹
storage_point string 存储点

文件属性的权限字段

文件属性property中的permission字段值为:

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