库文件操作

更新: 2017-10-24

API域名

Host: yk3-api-ent.gokuai.com

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


文件列表

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 获取模式, 默认空, 返回上传时间 < fetch_dateline的文件, 不包括删除的文件; 当 mode = compare时, 返回操作时间 > fetch_dateline的文件, 包括删除操作
fetch_dateline unix时间戳, 单位毫秒, 默认0
dir 获取文件或文件夹, 不传表示都返回, 1只返回文件夹, 0只返回文件
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

字段 类型 说明
fetch_dateline int 当前返回数据的最大时间戳, 单位毫秒
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/info HTTP/1.1

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath - 文件路径, 需传fullpathhash其中一个参数
hash - 文件唯一标识, 需传fullpathhash其中一个参数
net in表示获取内网下载地址, 默认空返回公网地址
attribute 是否获取额外属性, 包括子文件数量、大小,子文件夹数量
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:
}
字段 类型 说明
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/download_url HTTP/1.1

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

请求参数

名称 必需 说明
org_client_id 库授权client_id
fullpath - 文件路径, 需传fullpathhash其中一个参数
hash - 文件唯一标识, 需传fullpathhash其中一个参数
filehash 文件内容唯一标识, 用于下载历史版本, 不传表示下载当前版本
open 1返回能直接在浏览器中打开的文件地址, 默认0
filename 指定下载文件名,默认使用原名称
net in表示获取内网下载地址, 默认空返回公网地址
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 在水印中显示的文档查看人姓名
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

{
    "url" : 文档预览地址(10分钟有效)
}

文件搜索

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 文件夹的路径

上传文件

50MB以内的文件上传

POST /1/file/create_file HTTP/1.1

multipart/form-data方式

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
op_id - 上传人ID, 个人库默认是库拥有人ID, 如果上传人不是云库用户, 可以用op_name代替
op_name - 上传人名称, 如果指定了op_id, 就不需要op_name
overwrite 是否覆盖同名文件, 1覆盖(默认) 0不覆盖,文件名后增加数字标识
filefield 上传文件的参数名称
[filefield的值],如filefield的值是file,则这个参数的名称就是file 要上传文件的数据,在HTTP body里面使用Multipart/form-data格式上传(此参数不用参加签名计算)
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

字段 类型 说明
hash string 文件唯一标识
fullpath string 文件路径
filehash string 文件内容hash
filesize long 文件大小
state int 是否需要上传文件内容, 0需要,1不需要(已秒传)

WEB直接上传文件

支持50MB以上文件的上传

步骤1:获得上传服务器

POST /1/file/upload_servers HTTP/1.1

请求参数

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

返回结果

{
    "upload":
    [
        上传服务器地址 如:http://upload.domain.com,
        ...
    ]
}

步骤2:上传文件内容

[返回的服务器地址]/2/web_upload

multipart/form-data方式

请求参数

参数 必需 说明
org_client_id 库授权client_id
path 文件上传到哪个目录下
name 文件名
overwrite 是否覆盖同名文件, 1覆盖, 默认0不覆盖, 文件名后增加数字标识
filefield 指定上传的文件数据的请求参数名称
[filefield的值],例如参数filefield的值如果是file,则这个参数的名称就是file 要上传文件的数据,在HTTP body里面使用Multipart/form-data格式上传
redirect 上传完成(失败或成功)后的回调地址,回调结果在参数result中,用于不支持CORS的浏览器的获取上传完成后的返回信息
op_name 上传人名称

返回结果

正常返回 HTTP 200

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

错误

{
    'error_code': 错误代码,
    'error_msg': 错误消息,
    'fullpath': 文件完整路径
}

分块上传

支持大文件分块上传

步骤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:分块上传文件

请参考文档: 分块上传


通过链接上传文件

POST /1/file/create_file_by_url HTTP/1.1

请求参数

参数 必需 说明
org_client_id 库授权client_id
fullpath 文件完整路径
op_id - 创建人ID, 个人库默认是库拥有人ID, 如果创建人不是云库用户, 可以用op_name代替
op_name - 创建人名称, 如果指定了op_id, 就不需要op_name
overwrite 是否覆盖同名文件, 1覆盖, 默认0不覆盖, 文件名后增加数字标识
url 需要服务端获取的文件url
dateline 当前unix时间戳, 单位秒
sign 签名

返回格式

json

返回结果

HTTP 200

调用该接口后, 服务端会将任务添加到队列, 并不会马上执行完成


复制文件(夹)

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": "外链地址"
}

获取开启外链的文件列表

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_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


文件属性的权限字段

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

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