深色模式
控制台
文档编辑
本接口是您进行文档编辑的前提，未实现的情况下将会以只读模式打开文档。
当用户对文件产生了修改时，需要将用户修改后的文件定期/主动保存到接入方的文件系统中。由于各个接入方对于文档存储所采用的方式各不相同，WebOffice 综合了多个接入方的保存需求后，抽象出两种保存方式：
单阶段提交：单阶段提交在对接协议上比较简单，但是对于一些比较复杂的文件系统难以满足需求。
三阶段保存：三阶段保存在对接协议上较为复杂，但是对于一些较为复杂的系统（如多数据中心，就近接入等），三阶段的实现反而能较为灵活的满足接入方需求。
单阶段提交和三阶段保存，二者实现其一即可。
这里请注意，虽然您的文档修改会自动同步到我们的WebOffice服务器，但是并不会调用此接口，该接口的调用可以理解为一次存盘操作，会生成新的文件和新的版本号保存至接入方的文件系统和数据库。
关于此接口的调用时机：
- 当用户主动触发保存，例如通过键盘
Ctrl + S、通过 SDK 的save方法，都可以触发一次存盘。 - 用户主动关闭文档也会触发一次存盘操作。
- WebOffice每5秒触发一次检查，判断的逻辑为最近一次保存时间和最后一次编辑时间，最近一次编辑时间距离现在超过一分钟并且最近一次保存时间距离现在超过一分钟，触发文档存盘。
- 当所有用户关闭文档，编辑会话并不会立即退出，WebOffice 会在五分钟后将会话销毁。
三阶段保存图示
以下是接入方接入 WebOffice 三阶段保存的流程图示，三个阶段的传参详见下文具体介绍。
三阶段保存
准备上传阶段
说明：三阶段保存的第一步主要用于 WebOffice 与接入方进行参数协商，目前主要协商摘要算法。
接口: GET /v3/3rd/files/:file_id/upload/prepare
参数：
| 字段 | 位置 | 必须 | 类型 | 说明 |
|---|---|---|---|---|
file_id | Path | 是 | string | 文档 ID |
返回值 :
| 字段 | 必须 | 类型 | 说明 |
|---|---|---|---|
digest_types | 否 | string[] | 文档校验和算法 md5 sha1 sha256 |
返回值示例：
json
{
"code": 0,
"data": {
"digest_types": ["sha1"]
},
"message": ""
}获取上传地址
接口: POST /v3/3rd/files/:file_id/upload/address
说明：三阶段保存第二步主要用于获取上传地址，WebOffice 将上传保存后的文档到该地址。此外，回调中也会带上本次保存的一些额外信息，如文档大小，手动/自动保存等。
参数：
| 字段 | 位置 | 必须 | 类型 | 说明 |
|---|---|---|---|---|
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 类型 |
返回值:
| 字段 | 必须 | 类型 | 说明 |
|---|---|---|---|
url | 是 | string | 上传文档的 URL |
method | 是 | string | 上传文档的 HTTP Method，暂只支持 PUT，文件实体将在 Body 传递 |
headers | 否 | map<string, string> | 上传文档时需要携带的额外请求头 |
params | 否 | map<string, string> | 上传文档时需要携带的额外参数，PUT 方式下在 Query 传递 |
send_back_params | 否 | map<string, string> | 上传文档后，请求完成上传接口需要原样带回的额外参数 |
请求示例：
json
{
"file_id": "27",
"name": "样张.xlsx",
"size": 11683,
"digest": {
"sha1": "asdjfiedjisdhihsidihishiahi"
},
"is_manual": true
}返回值示例：
json
{
"code": 0,
"data": {
"method": "POST",
"url": "http://foo.bar.com/files/27"
},
"message": ""
}上传完成后，回调通知上传结果
接口: POST /v3/3rd/files/:file_id/upload/complete
说明：WebOffice 在将新版本文件上传到指定地址后，将会回调通知接入方
提示
遵循「文件ID一致性」原则：接口中文件「请求ID」 和 「返回ID」需保持一致
文件ID不一致有可能影响某些功能的正常使用
参数：
| 字段 | 位置 | 必须 | 类型 | 说明 |
|---|---|---|---|---|
file_id | Path | 是 | string | 文档 ID |
request | Body | 是 | Object | 获取上传地址时相同的请求 |
name | Request | 是 | string | 文档名称 |
size | Request | 是 | integer | 文档大小，单位 byte |
digest | Request | 是 | map<string, string> | 文档校验和，key 为算法，value 为结果值 |
is_manual | Request | 是 | boolean | 是否手动保存，即用户手动 ctrl/cmd + s 或点击保存版本触发的保存，区别于定时触发的自动保存 |
attachment_size | Request | 否 | integer | 文档内包含的附件的大小，单位 byte |
content_type | Request | 否 | string | 文档的 MIME 类型 |
response | Body | 是 | Object | 上传文档完成后，存储服务返回的 HTTP Response |
status_code | Response | 是 | integer | 上传文档时，存储服务返回的 HTTP Response Status |
headers | Response | 否 | map<string, string> | 上传文档时，存储服务返回的 HTTP Response Header |
body | Response | 否 | []byte | 上传文档时，存储服务返回的 HTTP Response Body 的 base64 编码 |
send_back_params | Body | 否 | map<string, string> | 获取上传地址时，要求原样带回的额外参数 |
返回值：
| 字段 | 必须 | 类型 | 说明 |
|---|---|---|---|
id | 是 | string | 文档 ID，必须与传入的file_id一致 |
name | 是 | string | 文档名称 |
version | 是 | integer | 文档版本号，从 1 开始，每次保存后递增 |
size | 是 | integer | 文档大小，单位 byte |
create_time | 是 | integer | 文档创建时间戳，单位纪元秒 |
modify_time | 是 | integer | 文档最后修改时间戳，单位纪元秒 |
creator_id | 是 | string | 文档创建者 Id |
modifier_id | 是 | string | 文档最后修改者 Id |
请求示例：
json
{
"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"
}
}返回值示例：
json
{
"code": 0,
"data": {
"create_time": 1670218748,
"creator_id": "404",
"id": "9",
"modifier_id": "404",
"modify_time": 1670328304,
"name": "统计月报.xlsx",
"size": 18961,
"version": 180
}
}单阶段提交
注意
由于保存接口的升级，单阶段提交将于2024年9月1日起停止新的接入
- 正在使用单阶段提交的开发者，您仍可继续使用，不受此次升级影响
- 正在对接单阶段提交的开发者，请留意对接截止时间，推荐您对接三阶段保存接口
- 若关闭单阶段提交接口，则该接口不能被再次开启
接口: POST /v3/3rd/files/:file_id/upload
说明：当用户按下保存或者 WebOffice 自动保存时，会回调保存接口。
提示
提交方式为表单提交，即 Content-Type 为：
multipart/form控制台-应用管理-回调配置 在线接口调试，针对编辑保存相关接口，并未计算测试文件的sha1值。
遵循「文件ID一致性」原则：接口中文件「请求ID」 和 「返回ID」需保持一致
文件ID不一致有可能影响某些功能的正常使用
参数：
| 字段 | 位置 | 必须 | 类型 | 说明 |
|---|---|---|---|---|
file_id | Path | 是 | string | 文档 ID |
file | Form | 是 | file | 文档实体 |
name | Form | 是 | string | 文档名称 |
size | Form | 是 | integer | 文档大小，单位 byte |
sha1 | Form | 是 | string | 文档校验和，采用 sha1 算法 |
is_manual | Form | 是 | boolean | 是否手动保存，即用户手动 ctrl/cmd + s 或点击保存版本触发的保存，区别于定时触发的自动保存 |
attachment_size | Form | 否 | integer | 文档内包含的附件的大小，单位 byte |
content_type | Form | 否 | string | 文档的 MIME 类型 |
返回值：
| 字段 | 必须 | 类型 | 说明 |
|---|---|---|---|
id | 是 | string | 文档 ID，必须与传入的file_id一致 |
name | 是 | string | 文档名称 |
version | 是 | integer | 文档版本号，从 1 开始，每次保存后递增 |
size | 是 | integer | 文档大小，单位 byte |
create_time | 是 | integer | 文档创建时间戳，单位纪元秒 |
modify_time | 是 | integer | 文档最后修改时间戳，单位纪元秒 |
creator_id | 是 | string | 文档创建者 Id |
modifier_id | 是 | string | 文档最后修改者 Id |
请求示例：
注意
示例并非 multipart/form ，仅参考字段值。
json
{
"file_id": "27",
"name": "样张.xlsx",
"size": 11683,
"sha1": "asdjfiedjisdhihsidihishiahi",
"is_manual": true
}返回值示例：
json
{
"code": 0,
"data": {
"create_time": 1670218748,
"creator_id": "404",
"id": "9",
"modifier_id": "404",
"modify_time": 1670328304,
"name": "统计月报.xlsx",
"size": 18961,
"version": 180
}
}