回调接口列表

获取文件信息

接口：GET_/v3/3rd/files/:file_id

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
id	是	string	文档 `Id`
name	是	string	文档名称
version	是	integer	文档版本号，从 `1` 开始，每次保存后递增
size	是	integer	文档大小，单位 `byte`
create_time	是	integer	文档创建时间戳，单位纪元秒
modify_time	是	integer	文档最后修改时间戳，单位纪元秒
creator_id	是	string	文档创建者 `Id`
modifier_id	是	string	文档创建者 `Id`

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "create_time": 1670218748,
        "creator_id": "404",
        "id": "9",
        "modifier_id": "404",
        "modify_time": 1670328304,
        "name": "统计月报.xlsx",
        "size": 18961,
        "version": 180
    }
}

获取文件下载地址

接口: GET_/v3/3rd/files/:file_id/download

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
url	是	string	文档下载地址
digest	否	string	文档校验和 (checksum)
digest_type	否	string	文档校验和算法 `md5` 或者 `sha1`
headers	否	map<string, string>	请求文档下载地址所需要的额外请求头，例如某些云存储商会要求额外的签名头等

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "url": "https://foo.bar.com/files/9/180"
    }
}

[可选] 获取扩展信息

接口: GET_/v3/3rd/files/:file_id/extra

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
file_max_size	是	integer	最大允许打开的文档大小，单位 `byte`
max_online_users	是	integer	单个文档内同时协作的用户人数上限
max_online_files	是	integer	文档并发数，允许同时在线的最大文件数量
readonly	否	boolean	是否以 `只读` 的方式打开当前文档

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {
      "file_max_size": 123123,
      "max_online_users": 10,
      "max_online_files": 1,
      "readonly": false
    }
}

[可选] 获取文档水印

接口: GET_/v3/3rd/files/:file_id/watermark

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
type	是	integer	水印类型，0-无水印 1-文字水印
value	`type = 1`时必须	string	水印显示的文字内容
fill_style	否	string	水印透明度，示例： `rgba( 192, 192, 192, 0.6 )`
font	否	string	水印字体设置，示例： `bold 20px Serif`
rotate	否	float	水印旋转度，示例： `-0.7853982`
horizontal	否	integer	水印水平间距
vertical	否	integer	水印垂直间距

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "fill_style": "rgba( 192, 192, 192, 0.6 )",
        "font": "bold 20px Serif",
        "horizontal": 50,
        "rotate": -0.7853982,
        "type": 1,
        "value": "谢绝拷贝\n2022-12-07 13:18:11",
        "vertical": 100
    }
}

文档用户权限

接口: GET_/v3/3rd/files/:file_id/permissions

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
user_id	是	string	当前用户 `Id`
read	否	integer	是否具有预览权限，0-无 1-有
update	否	integer	是否具有编辑权限，0-无 1-有
download	否	integer	是否具有下载文档权限，0-无 1-有
rename	否	integer	是否具有重命名文档权限，0-无 1-有
history	否	integer	是否具有查看文档历史记录权限，0-无 1-有
copy	否	integer	是否具有拷贝文档内容权限，0-无 1-有
print	否	integer	是否具有打印文档权限，0-无 1-有
saveas	否	integer	是否具有另存当前文档权限，0-无 1-有
comment	否	integer	是否具有评论文档权限，0-无 1-有

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "comment": 1,
        "copy": 1,
        "download": 1,
        "history": 1,
        "print": 1,
        "read": 1,
        "rename": 1,
        "saveas": 1,
        "update": 1,
        "user_id": "404"
    }
}

用户信息

接口: GET_/v3/3rd/users/:user_id

参数：

字段	位置	必须	类型	说明
user_id	Path	是	string	用户 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
id	是	string	当前用户 `Id`
name	是	string	用户昵称
avatar_url	否	string	用户头像 `URL`
logined	否	boolean	当前用户是否在线

返回值示例：

{
    "code": 0,
    "data": {
        "id": "404",
        "name": "Joe Doe"
    },
    "msg": ""
}

批量用户信息

接口: GET_/v3/3rd/users?user_id=:user_id_1&user_id=:user_id_2&user_id=:user_id_3

参数：

字段	位置	必须	类型	说明
user_id	Query	是	string	用户 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
id	是	string	当前用户 `Id`
name	否	string	用户昵称
avatar_url	否	string	用户头像 `URL`
logined	否	boolean	当前用户是否在线

返回值示例：

{
    "code": 0,
    "data": [
        {
            "id": "404",
            "name": "Joe Doe"
        }
    ],
    "msg": ""
}

[可选] 文档重命名

接口：PUT_/v3/3rd/files/:file_id/name

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`
name	Body	是	string	新文档名称

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分)：

无

请求参数示例：

{
    "name": "新文件名.xlxs"
}

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {}
}

[可选] 获取文档指定历史版本

接口：GET_/v3/3rd/files/:file_id/versions/:version

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`
version	Path	是	integer	版本

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
id	是	string	文档 `Id`
name	是	string	文档名称
version	是	integer	文档版本号
size	是	integer	文档大小，单位 `byte`
create_time	是	integer	文档创建时间，单位纪元秒
modify_time	是	integer	文档最近修改时间，单位纪元秒
creator_id	是	string	文档创建者 `Id`
modifier_id	是	string	文档创建者 `Id`

返回值示例：

{
  "code": 0,
  "msg": "",
  "data": {
    "create_time": 1670218748,
    "creator_id": "404",
    "id": "9",
    "modifier_id": "404",
    "modify_time": 1670328304,
    "name": "统计月报.xlsx",
    "size": 18961,
    "version": 180
  }
}

[可选] 文档历史版本列表

接口：GET_/v3/3rd/files/:file_id/versions?offset=:offset&limit=:limit

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`
offset	Query	否	integer	列表偏移量
limit	Query	否	integer	单页最大长度

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

需返回文件版本列表，按照版本号倒序排列。

字段	必须	类型	说明
id	是	string	文档 `Id`
name	是	string	文档名称
version	是	integer	文档版本号，从 `1` 开始，每次保存后递增
size	是	integer	文档大小，单位 `byte`
create_time	是	integer	文档创建时间，单位纪元秒
modify_time	是	integer	文档最近修改时间，单位纪元秒
creator_id	是	string	文档创建者 `Id`
modifier_id	是	string	文档创建者 `Id`

返回值示例：

{
    "code": 0,
    "data": [
        {
            "create_time": 1670218748,
            "creator_id": "404",
            "id": "27",
            "modifier_id": "404",
            "modify_time": 1670314818,
            "name": "样张.xlsx",
            "size": 14820,
            "version": 2
        },
        {
            "create_time": 1670218748,
            "creator_id": "404",
            "id": "27",
            "modifier_id": "404",
            "modify_time": 1670218748,
            "name": "样张.xlsx",
            "size": 11683,
            "version": 1
        }
    ],
    "msg": ""
}

[可选] 获取历史版本下载信息

接口 GET_/v3/3rd/files/:file_id/versions/:version/download

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
url	是	string	文档下载地址
digest	否	string	文档校验和 (checksum)
digest_type	否	string	文档校验和算法 `md5` 或者 `sha1`
headers	否	map<string, string>	请求文档下载地址所需要的额外请求头，例如某些云存储商会要求额外的签名头等

返回值示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "url": "https://foo.bar.com/files/9/180"
    }
}

保存文档，三阶段上传协议

[可选] 准备上传阶段，主要是获取 checksum 算法

接口: GET_/v3/3rd/files/:file_id/upload/prepare

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
digest_types	否	string[]	文档校验和算法 `md5` `sha1` `sha256`

返回值示例：

{
    "code": 0,
    "data": {
        "digest_types": [
            "sha1"
        ]
    },
    "msg": ""
}

获取上传地址接口: POST_/v3/3rd/files/:file_id/upload/address

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`
name	Body	是	string	文档名称
size	Body	是	integer	文档大小，单位 `byte`
digest	Body	是	map<string, string>	文档校验和，`key` 为算法，`value` 为结果值
is_manual	Body	是	boolean	是否手动保存，即用户手动 `ctrl/cmd + s` 或点击保存版本触发的保存，区别于定时触发的自动保存
attachment_size	Body	否	integer	文档内包含的附件的大小，单位 `byte`
content_type	Body	否	string	文档的 MIME 类型

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

字段	必须	类型	说明
url	是	string	上传文档的 `URL`
method	是	string	上传文档的 `HTTP Method`，取值：`PUT` 或 `POST`
headers	否	map<string, string>	上传文档时需要携带的额外请求头
params	否	map<string, string>	上传文档时需要携带的额外参数
send_back_params	否	map<string, string>	上传文档后，请求完成上传接口需要原样带回的额外参数

请求示例：

{
    "file_id": "27",
    "name": "样张.xlsx",
    "size": 11683,
    "digest": { "sha1": "asdjfiedjisdhihsidihishiahi" },
    "is_manual": true
}

返回值示例：

{
    "code": 0,
    "data": {
        "method": "POST",
        "url": "http://foo.bar.com/files/27"
    },
    "msg": ""
}

上传完成后回调通知接口: POST_/v3/3rd/files/:file_id/upload/complete 上传结果

参数：

字段	位置	必须	类型	说明
file_id	Path	是	string	文档 `Id`
+ request	Body	是	request	获取上传地址时相同的请求
name	Body	是	string	文档名称
size	Body	是	integer	文档大小，单位 `byte`
digest	Body	是	map<string, string>	文档校验和，`key` 为算法，`value` 为结果值
is_manual	Body	是	boolean	是否手动保存，即用户手动 `ctrl/cmd + s` 或点击保存版本触发的保存，区别于定时触发的自动保存
attachment_size	Body	否	integer	文档内包含的附件的大小，单位 `byte`
content_type	Body	否	string	文档的 MIME 类型
+ response	Body	是	response	上传文档完成后，存储服务返回的 `HTTP Response`
status_code	Body	是	integer	上传文档时，存储服务返回的 `HTTP Response Status`
headers	Body	否	map<string, string>	上传文档时，存储服务返回的 `HTTP Response Header`
body	Body	否	[]byte	上传文档时，存储服务返回的 `HTTP Response Body` 的 `base64` 编码
send_back_params	否	map<string, string>	获取上传地址时，要求原样带回的额外参数

返回值 (仅定义 data 段返回值，完整返回数据请参考示例部分):

无

请求示例：

{
    "request": {
        "file_id": "27",
        "name": "样张.xlsx",
        "size": 11683,
        "digest": { "sha1": "foo" },
        "is_manual": true
    },
    "response": {
        "status_code": 200,
        "headers": { "etag": "bar"}
    },
    "send_back_params": {
        "foo": "bar"
    }
}

返回值示例：

{
    "code": 0,
    "data": {},
    "msg": ""
}

回调接口列表 #

获取文件信息 #

获取文件下载地址 #

[可选] 获取扩展信息 #

[可选] 获取文档水印 #

文档用户权限 #

用户信息 #

批量用户信息 #

[可选] 文档重命名 #

[可选] 获取文档指定历史版本 #

[可选] 文档历史版本列表 #

[可选] 获取历史版本下载信息 #

保存文档，三阶段上传协议 #

回调接口列表

获取文件信息

获取文件下载地址

[可选] 获取扩展信息

[可选] 获取文档水印

文档用户权限

用户信息

批量用户信息

[可选] 文档重命名

[可选] 获取文档指定历史版本

[可选] 文档历史版本列表

[可选] 获取历史版本下载信息

保存文档，三阶段上传协议