WebOffice 开放平台

主题

回到顶部
本页内容

扩展能力

以下接口是一些功能相关的接口，缺失该部分接口可能会导致相关的功能不可用。

文档重命名

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

说明：该接口用于在 WebOffice 侧重命名文档。

参数：

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

返回值：无

请求参数示例：

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

返回值示例：

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

历史版本相关接口

以下接口是历史版本相关的接口，实现这一组接口可以接入历史版本相关的需求，如历史版本预览，回滚等。

文档历史版本列表

接口：GET /v3/3rd/files/:file_id/versions

说明：WebOffice 侧支持查看历史版本列表，该功能需要实现该接口。

参数：

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

返回值:

提示

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

📌 遵循「文件 ID 一致性」原则：接口中文件「请求 ID」 和 「返回 ID」需保持一致

📢 文件 ID 不一致有可能影响某些功能的正常使用

字段必须类型说明
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
{
  "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
    }
  ],
  "message": ""
}

获取文档指定历史版本

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

说明：历史版本预览，回滚等相关功能需要获取回滚的版本信息。

提示

🔔 遵循「文件 ID 一致性」原则：接口中文件「请求 ID」 和 「返回 ID」需保持一致

📝 文件 ID 不一致有可能影响某些功能的正常使用

参数：

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

返回值:

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

返回值示例：

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

获取历史版本下载信息

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

说明：历史版本预览，回滚等相关功能需要获取回滚版本的下载地址。

参数：

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

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

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

返回值示例：

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

文档水印

接口: 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
type = 1 时必须
integer
水印水平间距
vertical
type = 1 时必须
integer
水印垂直间距

返回值示例：

json
{
  "code": 0,
  "message": "",
  "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
  }
}

事件通知

接口: POST /v3/3rd/notify

说明：当需要对文档的打开关闭等操作进行事件监听时，可以实现本接口。WebOffice 当前支持四种事件类型：

session_open

  • 文件首次在 WebOffice 服务中打开时，会发送该通知
  • 后续加入的协作用户，不会创建新会话，因此也不会触发 session_open 通知

参数:

字段位置必须类型说明
file_id
body
是
string
文件 ID
type
body
是
string
事件类型
+
content
body
是
SessionOpenContent {}
事件内容

session_quit

WebOffice 服务关闭文档时发送该通知，与 session_open 相对应。

参数:

字段位置必须类型说明
file_id
body
是
string
文件 ID
type
body
是
string
事件类型
+
content
body
是
SessionQuitContent {}
事件内容

user_join

用户加入会话通知。

参数:

字段位置必须类型说明
file_id
body
是
string
文件 ID
type
body
是
string
事件类型
+
content
body
是
UserJoinContent {}
事件内容

user_quit

用户退出会话通知，与 user_join 相对应。

参数:

字段位置必须类型说明
file_id
body
是
string
文件 ID
type
body
是
string
事件类型
+
content
body
是
UserQuitContent {}
事件内容

operate_record_export

导出、打印操作通知。

参数:

字段位置必须类型说明
file_id
body
是
string
文件 ID
type
body
是
string
事件类型
+
content
body
是
OperateRecordExportContent {}
事件内容

附件对象相关接口

以下接口是附件对象相关的接口，实现这一组接口可以在 智能文档/多维表格 完成插入、预览、拷贝图片等附件对象的能力。

上传附件

接口：PUT /v3/3rd/object/:key

说明：智能文档/多维表格 插入图片需要实现该接口。

提示

🔔 提交方式不为表单提交，请求体为文件流, 即 Content-Type 为： application/octet-stream

参数：

字段位置必须类型说明
key
Path
是
string
附件对象 ID
name
Query
是
string
附件名
-
Body
是
files
附件实体

返回值：无

请求示例：

注意

💡 示例对部分数据进行脱敏处理, 仅提供参考

PUT /v3/3rd/object/xxx?name=xxx HTTP/1.1
Host: domain
Content-Length: 43474
Access-Id: AK
Authorization: WPS-2:AK:e4c92b94756cb6a1dabdaa1dcdd4768801a1c2ea
Content-Md5: 92e7364479196928262b2f3275cecc1a
Content-Type: application/octet-stream
Date: Tue, 09 May 2023 11:14:28 CST
X-App-Id: AK
X-User-Query:
X-Weboffice-Token:

[43474 bytes of object data]

返回值示例：

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

获取附件对象下载地址

接口：GET /v3/3rd/object/:key/url

说明：智能文档/多维表格 预览图片需要实现该接口。

参数：

字段位置必须类型说明
key
Path
是
string
附件对象 ID
scale_max_fit_width
Query
否
int
缩略图最大拟合宽度
scale_max_fit_height
Query
否
int
缩略图最大拟合高度
scale_long_edge
Query
否
int
缩略图限定长边长度

返回值:

字段必须类型说明
url
是
string
附件对象下载地址

返回值示例：

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

拷贝附件对象

接口：POST /v3/3rd/object/copy

说明：智能文档/多维表格 拷贝图片需要实现该接口。

参数：

字段位置必须类型说明
key_dict
Body
是
map<string, string>
附件对象 ID 键值对, 如<源附件对象 ID:目标附件对象 ID>

返回值：无

请求示例：

json
{
  "key_dict": {
    "7e0649753ad6474d995f1f525babcb94": "42265cf9fd2b4816a7df9a41ab4d0726"
  }
}

返回值示例：

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