库和文件

更新: 2025-10-10

使用 登录与授权 获得的access token操作用户库和文件

API域名

Host: yk3.gokuai.com

文件库列表

获取用户创建和加入的文件库

GET /m-api/1/account/mount

请求参数

参数 必需 说明
token 是 access token
dateline 是 当前unix时间戳, 单位秒
sign 是 签名

返回格式

json

返回结果

{
 "list": [
    {
      "ent_id": 0,
      "org_id": 1,
      "org_name": "个人文件",
      "mount_id": 1,
      "org_type": 0,
      "member_count": 0,
      "owner_member_id": 2,
      "org_logo_url": "http://dn-avatar.gokuai.com/36/3673e5b2778a8fa94db911c5c2473f8443c138fc.jpg",
      "size_org_total": 21474836480,
      "size_org_use": 806623,
      "storage_point": "",
      "storage_ethernet": 1
    },
        ...
    ]
}
字段 类型 说明
ent_id int 企业ID
org_id int 库ID
org_name string 库名称
mount_id int 库空间ID
org_type int 库类型
member_count int 成员总数
org_logo_url string 库图标地址
size_org_total bigint 库空间总大小, 单位字节
size_org_use bigint 库已使用空间大小, 单位字节
storage_point string 存储点
storage_ethernet int 是否允许外网访问

注意:

ent_id=0的库为不在企业中的个人库, org_type=20的库为企业中的个人文件库

创建文件库

注意: 用户需要有创建库的权限

POST /m-api/1/library/create

请求参数

参数 必需 说明
token 是 access token
name 是 库名称
ent_id 是 企业ID
capacity 否 存储空间限制, 单位字节, -1表示不限制
storage_point 否 存储点, 不传表示默认存储
dateline 是 当前unix时间戳, 单位秒
sign 是 签名

返回格式

json

返回结果

字段 类型 说明
org_id int 库ID
mount_id int 库空间ID
storage_point string 存储点

文件列表

GET /m-api/1/file/ls

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath - 文件夹完整路径, 取公开资料文件夹下的市场文档用公开资料\市场文档, 默认根路径空字符串, fullpath和sort只需传一个即可
sort - 按文件类型列表文件, 1视频, 2音频, 3图片, 5文档, fullpath和sort只需传一个即可
dir 否 1表示只返回文件夹, 默认0都返回
start 否 开始位置, 默认0
size 否 获取数量, 默认100
order 否 默认按最后修改时间倒序排序, filename按文件名排序, filesize按文件大小排序
sign 是 签名

返回格式

json

返回结果

{
  "count": 2,
  "list": [
    {
      "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "mount_id": 1,
      "dir": 1,
      "fullpath": "公开资料",
      "filename": "公开资料",
      "filehash": "",
      "filesize": 0,
      "create_member_id": "1",
      "create_member_name": "我",
      "create_dateline": 1452569732,
      "last_member_id": "1",
      "last_member_name": "我",
      "last_dateline": 1452569732,
      "thumbnail": "",
      "lock": 0
    },
    {
      "hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "mount_id": 1,
      "dir": 0,
      "fullpath": "Word文档.doc",
      "filename": "Word文档.doc",
      "filehash": "ffffffffffffffffffffffffffffffffffffffff",
      "filesize": 204800,
      "create_member_id": "1",
      "create_member_name": "我",
      "create_dateline": 1442563789,
      "last_member_id": "1",
      "last_member_name": "我",
      "last_dateline": 1449505954,
      "thumbnail": "",
      "lock": 0
    },
    ......
  ]
}
字段 类型 说明
hash string 文件唯一ID
mount_id int 库空间ID
dir int 是否文件夹
fullpath string 文件完整路径
filename string 文件名称
filehash string 文件内容checksum, 文件夹为空字符串
filesize bigint 文件大小
create_member_id string 文件创建人ID
create_member_name string 文件创建人
create_dateline int 文件创建时间, unix时间戳, 单位秒
last_member_id string 文件最后修改人ID
last_member_name string 文件最后修改人
last_dateline int 文件最后修改时间, unix时间戳, 单位秒
thumbnail string 文件缩略图URL
lock int 文件是否锁定

文件下载地址

GET /m-api/2/file/open

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath - 文件完整路径, fullpath和hash传一个即可
hash - 文件唯一ID, fullpath和hash传一个即可
sign 是 签名

返回格式

json

返回结果

{
  "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "filehash": "ffffffffffffffffffffffffffffffffffffffff",
  "filesize": 204800,
  "lock": 0,
  "uris": [
    "http://xxxxxx"
  ]
}
字段 类型 说明
hash string 文件唯一ID
filehash string 文件checksum
filesize string 文件大小
lock int 文件是否锁定
uris array 下载地址数组, 默认情况只有一项, 下载地址有效期10分钟

文件预览地址

GET /m-api/2/file/preview_url

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath - 文件完整路径, fullpath和hash传一个即可
hash - 文件唯一ID, fullpath和hash传一个即可
watermark 否 是否显示水印, 1显示, 默认不显示
sign 是 签名

返回格式

json

返回结果

{
  "url": "预览地址"
}

文件(夹)信息

GET /m-api/2/file/info

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath - 文件完整路径, fullpath和hash传一个即可
hash - 文件唯一ID, fullpath和hash传一个即可
sign 是 签名

返回格式

JSON

返回结果

{
  "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "mount_id": 1,
  "dir": 0,
  "fullpath": "Word文档.doc",
  "filename": "Word文档.doc",
  "filehash": "ffffffffffffffffffffffffffffffffffffffff",
  "filesize": 204800,
  "create_member_id": 1,
  "create_member_name": "我",
  "create_dateline": 1442563789,
  "last_member_id": 1,
  "last_member_name": "我",
  "last_dateline": 1449505954,
  "lock": 0,
  "preview": "",
  "thumbnail": ""
}
字段 类型 说明
hash string 文件唯一ID
mount_id int 库空间ID
dir int 是否文件夹
fullpath string 文件完整路径
filename string 文件名称
filehash string 文件checksum, 文件夹返回空字符串
filesize int 文件大小
create_member_id string 文件创建人ID
create_member_name string 文件创建人
create_dateline int 文件创建时间, unix时间戳, 单位秒
last_member_id string 文件最后修改人ID
last_member_name string 文件最后修改人
last_dateline int 文件最后修改时间, unix时间戳, 单位秒
preview string 预览URI地址, 在浏览器打开需要在URI前增加域名http://yk3.gokuai.com, 文件夹不返回
thumbnail string 缩略图地址, 文件夹不返回

文件夹内文件数量

获取文件夹内的文件和子文件夹数量, 统计的数量包括下级所有文件和文件夹

GET /m-api/2/file/attribute

请求参数

参数 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath - 文件完整路径, fullpath和hash传一个即可
hash - 文件唯一ID, fullpath和hash传一个即可
dateline 是 当前unix时间戳, 单位秒
sign 是 签名

返回格式

json

返回结果

{
    "file_count": 文件数量,
    "folder_count": 子文件夹数量
}

新建文件夹

POST /m-api/2/file/create_folder

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath 否 文件夹完整路径
overwrite 否 默认1覆盖, 传0时, 如果文件夹已经存在, 则自动改名当前文件夹为xxx(2)
dateline 是 当前unix时间戳, 单位秒
sign 是 签名

上传文件

分块方式上传文件

步骤1: 请求上传

POST /m-api/2/file/create_file HTTP/1.1

请求参数

参数 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath 是 文件完整路径
filehash 是 文件内容sha1值, 40字节, 英文字母小写, 不参与签名计算
filesize 是 文件大小, 不参与签名计算
overwrite 否 是否覆盖同名文件, 1覆盖, 默认0不覆盖, 文件名后增加数字标识
sign 是 签名

返回格式

{
    "state": 1表示文件已秒传成功, 0表示需要调分块上传接口,
    "hash": 文件唯一标识,
    "fullpath": 文件完整路径,
    "server": 上传服务器地址
}

步骤2: 分块上传文件

完成步骤1后返回的state为0时,

请参考文档: 分块上传

网页上传

步骤1: 获得上传服务器

GET /m-api/1/file/upload_server

请求参数

参数 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath 是 待上传的文件完整路径
sign 是 签名

返回结果

{
    "server": 上传服务器地址
}

步骤2: 上传文件内容

使用返回的上传服务器地址, 组合成上传URL

{upload server}/2/web_upload

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

请求参数

参数 必需 说明
token 是 access token
mount_id 是 库空间ID
path 是 文件上传的目标路径, 例如上传到doc文件夹下则传doc, 上传到根目录则传空字符串
name 是 文件的名称
overwrite 否 是否覆盖同名文件, 1覆盖, 默认0不覆盖, 文件名后增加数字标识
filefield 是 固定值file
file 是 要上传文件的数据

返回结果

正常返回 HTTP 200

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

错误

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

复制文件

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

请求参数

名称 必需 说明
token 是 access token
mount_id 是 待复制的文件库空间ID
fullpath - 待复制的文件完整路径, fullpath和fullpaths传一个即可
fullpaths - 复制多个文件, 用竖号 | 分隔, fullpath和fullpaths传一个即可
target_mount_id 否 复制的目标库空间ID, 不传表示库内复制
target_fullpath 是 复制目标的上级完整路径
overwrite 否 1表示覆盖同名文件, 对文件夹无效
delete_from 否 1表示复制后删除原文件, 主要用于跨库移动文件
sign 是 签名

返回结果

正常返回 HTTP 200

移动文件

注意: 只允许在库内移动文件

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

请求参数

名称 必需 说明
token 是 access token
mount_id 是 文件库空间ID
fullpath - 待移动的文件完整路径, fullpath和fullpaths传一个即可
fullpaths - 移动多个文件, 用竖号 | 分隔, fullpath和fullpaths传一个即可
target_fullpath 是 移动目标的上级完整路径
sign 是 签名

返回结果

正常返回 HTTP 200

重命名文件

POST /m-api/1/file/rename HTTP/1.1

请求参数

名称 必需 说明
token 是 access token
mount_id 是 文件库空间ID
fullpath 是 文件完整路径
newname 是 新文件名
sign 是 签名

返回结果

正常返回 HTTP 200

删除文件

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

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath 是 文件完整路径
sign 是 签名

返回结果

正常返回 HTTP 200

添加文件到收藏夹

POST /m-api/1/favorites/add_file HTTP/1.1

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath 是 文件完整路径
fav_id 是 收藏夹ID, 固定值-1表示默认收藏夹
sign 是 签名

返回结果

正常返回 HTTP 200

取消收藏

POST /m-api/1/favorites/del_file HTTP/1.1

请求参数

名称 必需 说明
token 是 access token
mount_id 是 库空间ID
fullpath 是 文件完整路径
fav_id 是 收藏夹ID, 固定值-1表示默认收藏夹
sign 是 签名

返回结果

正常返回 HTTP 200

收藏夹文件列表

GET /m-api/1/favorites/get_files

请求参数

名称 必需 说明
token 是 access token
fav_id 是 收藏夹ID, 固定值-1表示默认收藏夹
start 否 开始位置, 默认0
size 否 获取数量, 默认100
sign 是 签名

返回格式

json

返回结果

{
  "list": [
    {
      "mount_id": 1,
      "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "dir": 1,
      "fullpath": "公开资料",
      "filename": "公开资料",
      "filehash": "",
      "filesize": 0,
      "create_member_id": "1",
      "create_member_name": "我",
      "create_dateline": 1452569732,
      "last_member_id": "1",
      "last_member_name": "我",
      "last_dateline": 1452569732
    },
    {
      "hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "mount_id": 1,
      "dir": 0,
      "fullpath": "Word文档.doc",
      "filename": "Word文档.doc",
      "filehash": "ffffffffffffffffffffffffffffffffffffffff",
      "filesize": 204800,
      "create_member_id": "1",
      "create_member_name": "我",
      "create_dateline": 1442563789,
      "last_member_id": "1",
      "last_member_name": "我",
      "last_dateline": 1449505954
    },
    ......
  ]
}
字段 类型 说明
hash string 文件唯一ID
mount_id int 库空间ID
dir int 是否文件夹
fullpath string 文件完整路径
filename string 文件名称
filehash string 文件内容checksum, 文件夹为空字符串
filesize bigint 文件大小
create_member_id string 文件创建人ID
create_member_name string 文件创建人
create_dateline int 文件创建时间, unix时间戳, 单位秒
last_member_id string 文件最后修改人ID
last_member_name string 文件最后修改人
last_dateline int 文件最后修改时间, unix时间戳, 单位秒

文件搜索

GET /m-api/2/file/search

请求参数

名称 必需 说明
token 是 access token
keyword 是 搜索关键字
mount_id 是 库空间ID, 0表示全局搜索
fullpath 否 搜索指定文件夹下的文件, 包括所有下层文件
scope 否 搜索范围, 内容为JSON, 传参时需转为字符串, ["filename","tag","content"], 其中filename表示搜索文件名, tag搜索标签, content搜索文档内容, 可进行组合, 如["tag","content"]表示搜索标签和文档内容, 默认值为["filename","tag"]
ext 否 搜索指定类型的文件/文件夹, 内容为JSON, 传参时需转为字符串, ["dir", "file", "docx", "jpg", ...], dir表示只搜索文件夹, file表示只搜索文件, 其他扩展名表示指定搜索文件的扩展名
start 否 开始位置, 默认0
size 否 获取数量, 默认100
sign 是 签名

返回结果

同 文件列表