WebOffice 开放平台

主题

回到顶部
本页内容

文档编辑

本接口是您进行文档编辑的前提，未实现的情况下将会以只读模式打开文档。

当用户对文件产生了修改时，需要将用户修改后的文件定期/主动保存到接入方的文件系统中。由于各个接入方对于文档存储所采用的方式各不相同，WebOffice 综合了多个接入方的保存需求后，抽象出两种保存方式：

  • 单阶段提交：单阶段提交在对接协议上比较简单，但是对于一些比较复杂的文件系统难以满足需求。

  • 三阶段保存：三阶段保存在对接协议上较为复杂，但是对于一些较为复杂的系统（如多数据中心，就近接入等），三阶段的实现反而能较为灵活的满足接入方需求。

单阶段提交和三阶段保存，二者实现其一即可。

这里请注意，虽然您的文档修改会自动同步到我们的WebOffice服务器，但是并不会调用此接口，该接口的调用可以理解为一次存盘操作，会生成新的文件和新的版本号保存至接入方的文件系统和数据库。

关于此接口的调用时机：

  1. 当用户主动触发保存，例如通过键盘Ctrl + S、通过 SDK 的save方法，都可以触发一次存盘。
  2. 用户主动关闭文档也会触发一次存盘操作。
  3. WebOffice每5秒触发一次检查，判断的逻辑为最近一次保存时间和最后一次编辑时间，最近一次编辑时间距离现在超过一分钟并且最近一次保存时间距离现在超过一分钟，触发文档存盘。
  4. 当所有用户关闭文档，编辑会话并不会立即退出，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日起停止新的接入

  1. 正在使用单阶段提交的开发者，您仍可继续使用，不受此次升级影响
  2. 正在对接单阶段提交的开发者，请留意对接截止时间，推荐您对接三阶段保存接口
  3. 若关闭单阶段提交接口，则该接口不能被再次开启

接口: 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
  }
}