库文件操作

更新: 2017-6-6

API域名

Host: yk3-api-ent.gokuai.com

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


文件列表

POST /1/file/ls HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件的路径
start int 开始位置,默认0
size int 返回条数,默认100
hashs string 获取指定hash的文件, 半角逗号,分隔
sign string 签名

返回格式

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/updates HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
mode string 获取模式, 默认空, 返回上传时间 < fetch_dateline的文件, 不包括删除的文件; 当 mode = compare时, 返回操作时间 > fetch_dateline的文件, 包括删除操作
fetch_dateline int 13 位时间戳, 默认0
dir int 获取文件或文件夹, 不传表示都返回, 1只返回文件夹, 0只返回文件
sign string 签名

返回格式

json

返回结果

字段 类型 说明
fetch_dateline int 当前返回数据的最大时间戳(13位精确到毫秒)
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 string 库授权client_id
dateline int 10位当前时间戳
begin_dateline string 13位时间戳, 开始时间
end_dateline string 13位时间戳, 结束时间
showdel string 0/1 是否返回删除文件, 默认0不返回删除文件
sign string 签名

返回格式

json

返回结果

{
    count: 更新数量
}

文件(夹)信息

POST /1/file/info HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件路径(需传fullpath或hash)
hash string 文件唯一标识(需传fullpath或hash)
net string in表示获取内网下载地址, 默认空返回公网地址
attribute int 是否获取额外属性(子文件数量、大小,子文件夹数量)
sign string 签名

返回格式

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:
}
字段 类型 说明
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 子文件大小

文件下载地址

POST /1/file/download_url HTTP/1.1

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

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件路径(需传fullpathhash)
hash string 文件唯一标识(需传fullpathhash)
filehash string 文件内容唯一标识, 用于下载历史版本, 不传表示下载当前版本
open int 是否返回能直接在浏览器中打开的文件地址, 默认0
filename string 指定下载文件名,默认使用原名称
net int in表示获取内网下载地址, 默认空返回公网地址
sign string 签名

返回格式

json

返回结果

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

文件预览地址

POST /1/file/preview_url HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件路径(需传fullpathhash)
hash string 文件唯一标识(需传fullpathhash)
watermark int 是否显示水印, 默认0不显示
member_name string 在水印中显示的文档查看人姓名
sign string 签名

返回格式

json

返回结果

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

文件搜索

POST /1/file/search HTTP/1.1

请求参数

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

返回格式

文件列表


创建文件夹

POST /1/file/create_folder HTTP/1.1

请求参数

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

返回格式

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

上传文件

50MB以内的文件上传

POST /1/file/create_file HTTP/1.1

multipart/form-data方式

请求参数

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

返回格式

字段 类型 说明
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 string 库授权client_id
dateline int 10位当前时间戳
sign string 签名

返回结果

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

步骤2:上传文件内容

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

multipart/form-data方式

请求参数

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

返回结果

正常返回 HTTP 200

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

错误

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

分块上传

支持大文件分块上传

步骤1:请求上传

POST /1/file/create_file HTTP/1.1

请求参数

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

返回格式

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

步骤2:分块上传文件

请参考文档: 分块上传


通过链接上传文件

/file/create_file_by_url

请求参数

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

返回格式

json

返回结果

HTTP 200

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


复制文件(夹)

POST /1/file/copy HTTP/1.1

请求参数

参数 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
from_fullpath string 源文件路径
fullpath string 目标文件路径(含文件名称)
op_id int 创建人id, 个人库默认是库拥有人id
op_name string 创建人名称, 如果指定了op_id, 就不需要op_name
sign string 签名

返回格式

json

返回结果

HTTP 200


删除文件(夹)

POST /1/file/del HTTP/1.1

请求参数

参数 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件路径
op_id int 创建人id, 个人库默认是库拥有人id
op_name string 创建人名称, 如果指定了op_id, 就不需要op_name
sign string 签名

返回格式

json

返回结果

HTTP 200


回收站

POST /1/file/recycle HTTP/1.1

请求参数

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

返回格式

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 string 库授权client_id
dateline int 10位当前时间戳
fullpaths string 要恢复文件的路径,'\ '隔开
op_id int 操作人id, 个人库默认是库拥有人id
op_name string 操作人名称, 如果指定了op_id, 就不需要op_name
sign string 签名

返回格式

json

返回结果

HTTP 200


彻底删除文件(夹)

POST /1/file/del_completely HTTP/1.1

请求参数

参数 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpaths string 要彻底删除文件的路径,'\ '隔开
op_id int 操作人id, 个人库默认是库拥有人id
op_name string 操作人名称, 如果指定了op_id, 就不需要op_name
sign string 签名

返回格式

json

返回结果

HTTP 200


移动文件(夹)

POST /1/file/move HTTP/1.1

请求参数

参数 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 要移动文件的路径
dest_fullpath string 移动后的路径
op_id int 创建人id, 个人库默认是库拥有人id
op_name string 创建人名称, 如果指定了op_id, 就不需要op_name
sign string 签名

返回格式

json

返回结果

HTTP 200


获取文件历史

POST /1/file/history HTTP/1.1

请求参数

参数 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件路径
start int 开始位置,默认0
size int 返回条数,默认20
sign string 签名

返回格式

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 string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件路径
deadline int 到期时间时间戳,默认48小时后
auth string preview:文件预览;download:文件预览和下载;upload:预览、下载、文件夹上传;默认preview
password string 访问密码
sign string 签名

返回格式

json

返回结果

字段 类型 说明
link string 文件外链地址

获取开启外链的文件列表

POST /1/file/links HTTP/1.1

请求参数

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

返回结果

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

获取文件夹权限

POST /1/file/get_permission HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件的路径
member_id int 用户ID
out_id string 外部系统用户ID, member_idout_id必须指定其中一个参数
sign string 签名

返回结果

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

修改文件夹权限

POST /1/file/file_permission HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件的路径
permissions json 权限,如 {member_id:["file_read","file_preview","file_write","file_delete"],...}
sign string 签名

返回结果

HTTP 200


添加标签

POST /1/file/add_tag HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件的路径
tag string 标签,多个标签;隔开
sign string 签名

返回结果

HTTP 200


删除标签

POST /1/file/del_tag HTTP/1.1

请求参数

名称 必需 类型 说明
org_client_id string 库授权client_id
dateline int 10位当前时间戳
fullpath string 文件的路径
tag string 标签,多个标签;隔开
sign string 签名

返回结果

HTTP 200