WPS WebOffice 开放平台WPS WebOffice 开放平台 | 开发文档

深色模式

概述 ​

在不托管文件系统的情况下，WebOffice 集群提供了通用的文件在线预览/编辑/协同的能力。回调服务内的接口可以理解为文件系统的接口抽象，需要接入方提供文件元信息，文件下载地址，文件权限，文件保存等接口，用于打通在线编辑系统与文件系统。当然，接入方可以通过签发凭证(Token)的方式，自行管理文件系统的权限。

提示

Token 的流转：

接入业务方根据自身的鉴权需要自定义 Token。Token 在前端 初始化 SDK时传入, WebOffice 将会在回调接入业务方接口时通过 Header 的 X-Weboffice-Token 字段回传，业务方可在其所实现的接口上检查当前用户的 Token，用于鉴权。

回调服务的要求 ​

  • 拥有已经通过审核的 WebOffice 应用。
  • 回调接口需要接入方自行实现，所有接口都需实现，若只实现部分接口，可能会导致部分功能异常。
  • 接入方实现的回调接口必须部署在公网。（需要保证能被 WebOffice 服务器访问到）

通讯过程 ​

以下是接入方通过 WebOffice-SDK 接入 WebOffice 在线预览/编辑服务的通讯全过程。回调服务对应于WebOffice-服务端 以及 接入方-服务端 间的通讯。

回调接口通讯

回调配置 ​

回调配置是我们WebOffice 控制台应用详情中一个重要的配置项，与在线预览编辑服务紧密相关，您开发的回调服务必须通过回调配置才能与应用进行绑定。在回调配置界面，可以对您的接口进行在线调试，根据返回的错误信息一步一步完善接口。当调试无误后，便可以通过左侧的开关开启此项接口，WebOffice 服务的对应的功能便会自动开启。

回调配置

回调请求签名 ​

WebOffice 服务集群发出的回调请求，全部经过 WPS-2 签名算法签名。签名需要用到申请应用时拿到的 AppId 和 AppSecret。签名实现如下：

签名相关请求头(HTTP Header)说明
Date
请求发生时间。 以 RFC1123 时间格式的当前时间
Content-Type
请求中 Body 内容的 mime 类型
Content-Md5
请求中 Body 内容的 md5 值十六进制表示方式, 小写。如果 Body 为空，改用 URI 计算, 例如: 原始请求为 GET https://foo.bar.com/baz/v3/3rd/files/123 则取 /baz/v3/3rd/files/123 计算
Authorization
格式为：WPS-2:AppId:SHA1值 其中 SHA1值 的计算方式为 SHA1( AppSecret + Content-Md5 + Content-Type + Date) 十六进制表示方式, 小写

提示

Get请求 Content-Type 使用空字符串来计算 相关讨论：社区-签名算法

业务数据请求头 ​

除签名头外，回调请求会携带如下四个业务数据头：

请求头必须类型说明
X-App-Id
是
string
当前请求所属的 AppId 与 URl 上的 _w_appid 值相同
X-WebOffice-Token
是
string
当前请求的用户凭证，即通过初始化参数传递的token值
X-Request-Id
否
string
本次请求 ID，方便定位问题
X-User-Query
否
string
URL 中的 query 部分，包含一些基础参数和 WebOffice SDK 初始化时通过customArgs传递的参数，例如customArgs的值为{"firstname":"jack","lastname":"green"}，那么该请求头的内容为_w_appid=xxx&_w_tokentype=xxx&file_id=xxx&firstname=jack&lastname=green

提示

上述提到的 URL 指的是接入方前端通过 WebOffice SDK 打开文档的 iframe 的链接。

接入方返回值格式 ​

接入方应统一返回 application/json 格式的数据，相关字段和说明请参照下表。

字段必须类型说明
code
是
integer
错误码，详见后续错误码，请求成功时，code 为 0
message
否
string
错误说明，请求成功时，该字段可以不返回
data
否
object
具体数据，请求失败时，该字段可以不返回

请求成功示例 ​

json
{
  "code": 0,
  "message": "",
  "data": {
    //这里的具体数据，根据回调接口不同，返回不同的scheme
    "id": "404",
    "name": "Joe Doe"
  }
}

请求失败示例 ​

json
{
  "code": 40004,
  "message": "file not exists"
}

返回字段规范 ​

文件 ID ​

文件 ID 可由数字、字母和下划线组成，但不能以下划线开头。文件 ID 在接入方系统中不能具有二义性（保持唯一）。文件 ID 长度要求不超过 47 位字符串，超出规定长度的将无法校验通过。

用户 ID ​

用户 ID 可由数字、字母和下划线组成，但不能以下划线开头。用户 ID 在接入方系统中不能具有二义性（保持唯一）。用户 ID 长度要求不超过 48 位字符串，超出规定长度的将无法校验通过。

历史版本号 ​

历史版本号只能为正数，且逐步递增，最大不超过 2147483647。建议从 1 开始递增，每保存一个版本加一。