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 | |
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 开始递增，每保存一个版本加一。