# 概述 在不托管文件系统的情况下，WebOffice 集群提供了通用的文件在线预览/编辑/协同的能力。回调服务内的接口可以理解为文件系统的接口抽象，需要接入方提供文件元信息，文件下载地址，文件权限，文件保存等接口，用于打通在线编辑系统与文件系统。当然，接入方可以通过签发凭证(Token)的方式，自行管理文件系统的权限。 :::tip 提示 Token 的流转： 接入业务方根据自身的鉴权需要自定义 Token。Token 在前端 [初始化](/app-integration-dev/docs-center/online-preview-edit/web/quick-start.html#%E6%AD%A5%E9%AA%A4-3-%E5%88%9D%E5%A7%8B%E5%8C%96) `SDK`时传入, WebOffice 将会在回调接入业务方接口时通过 `Header` 的 `X-Weboffice-Token` 字段回传，业务方可在其所实现的接口上检查当前用户的 Token，用于鉴权。 ::: ## 回调服务的要求 * 拥有已经通过审核的 WebOffice 应用。 * 回调接口需要**接入方自行实现**，所有接口都需实现，若只实现部分接口，可能会导致部分功能异常。 * 接入方实现的**回调接口必须部署在公网**。（需要保证能被 WebOffice 服务器访问到） ## 通讯过程 以下是接入方通过 WebOffice-SDK 接入 WebOffice 在线预览/编辑服务的通讯全过程。回调服务对应于**WebOffice-服务端** 以及 **接入方-服务端** 间的通讯。 ![回调接口通讯](https://cloudcdn.qwps.cn/open/kingsoft_open_docs/solutions_img/e0428185fb.svg "回调接口通讯") ## 回调配置 **回调配置**是我们[WebOffice 控制台](https://solution.wps.cn/console)应用详情中一个重要的配置项，与**在线预览编辑服务**紧密相关，您开发的回调服务必须通过回调配置才能与应用进行绑定。在回调配置界面，可以对您的接口进行在线调试，根据返回的错误信息一步一步完善接口。当调试无误后，便可以通过左侧的开关开启此项接口，WebOffice 服务的对应的功能便会自动开启。 ![](https://open-docs.wpscdn.cn/public/dms/prod-env/resource/1/be/d9/bed99979e4760109ebf526efb4cfd53b8c638a97e879add36c19ceb27b17cd65.png) ## 回调请求签名 WebOffice 服务集群发出的回调请求，全部经过 `WPS-2` 签名算法签名。签名需要用到申请应用时拿到的 `AppId` 和 `AppSecret`。签名实现如下： | 签名相关请求头(HTTP Header) | 说明 | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Date | 请求发生时间。 以 时间格式的当前时间[RFC1123](https://datatracker.ietf.org/doc/html/rfc822#section-5) | | 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)` 十六进制表示方式, 小写 | :::tip 提示 Get请求 `Content-Type` 使用空字符串来计算 相关讨论：[社区-签名算法](https://solution-community.wps.cn/questions/10010000000000621/10020000000000781)::: ## 业务数据请求头 除签名头外，回调请求会携带如下四个业务数据头： | 请求头 | 必须 | 类型 | 说明 | | ----------------- | -- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | X-App-Id | 是 | string | 当前请求所属的 `AppId` 与 URl 上的 `_w_appid` 值相同 | | X-WebOffice-Token | 是 | string | 当前请求的用户凭证，即通过传递的`token`值[初始化参数](/app-integration-dev/docs-center/online-preview-edit/web/quick-start.html#base-config) | | 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`[初始化](/app-integration-dev/docs-center/online-preview-edit/web/quick-start.html#步骤-3-初始化) | :::tip 提示 上述提到的 URL 指的是接入方前端通过 WebOffice SDK 打开文档的 iframe 的链接。 ::: ## 接入方返回值格式 接入方应统一返回 `application/json` 格式的数据，相关字段和说明请参照下表。 | 字段 | 必须 | 类型 | 说明 | | ------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------- | | code | 是 | integer | 错误码，详见后续，请求成功时，`code` 为 `0`[错误码](/app-integration-dev/docs-center/online-preview-edit/callback/error-code.html) | | 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 开始递增，每保存一个版本加一。