本文介绍毕升office v4版本中集成配置的相关说明。
¶ 存储信息(APP空间)
APP空间是针对某一个集成应用的存储空间。集成毕升office编辑、预览或者服务端api处理文件时，毕升office将会将文件的信息记录在一个APP空间中。 具体集成是记录在哪个APP空间，在APP空间的那个路径下可以通过参数指定。文件处理完成之后如果文件需要推送到原有的系统中，也可以在APP空间中 配置相应的回调地址。
¶ APP空间参数
具体集成是记录在哪个APP空间，在APP空间的那个路径下可以通过参数指定。
{
"store": {
"appId": "appId001",
"time": "2022-05-28 00:32:16",
"sign": "timeSignResult",
"folderPath": "/",
"newVersion": false
}
}
以上参数为具体调用毕升office API进行集成时指定APP参数的部分（参数中store对应的内容）。store中内容为APP空间具体参数。
- appId：AppId，指定本次调用使用的APP空间。
- time：调用时的时间信息。可接受的格式请参考时间格式内容。
- sign：用于验证的签名信息。签名的值为使用指定APP空间的AppKey对上方的调用时间进行HMAC-MD5计算所得的值。
- folderPath：指定APP空间中的文件路径。指定文件在APP空间的保存位置，可将文件上传至当前APP空间根目录的对应路径下。例：上传到根路径->folderPath="/"，上传到[/a/b/c]路径->folderPath="/a/b/c"。
- newVersion：是否使用文件地址创建新版本。指定docId的文件存在并指定了fetchUrl时，此项目设置为true时，将使用fetchUrl获取的文件，为指定的文件创建新版本。如果没有指定创建新版本，且该ID的文件在系统是存在的，则会使用原来的文件，而不会使用fetchurl进行下载
如果APP空间关闭安全验证，则time和sign参数可以不传入。
¶ 回存地址
如果调用毕升office API处理文件之后，需要将最新的文件推送到原有的系统中，可以在APP空间中指定回存地址。 当记录在APP空间的文件完成处理之后，以POST方式推送到此地址中。推送的数据格式为：
文件内容修改推送数据
{
"action": "saveVersion",
"callToken":"",
"docId": "文件ID",
"title": "文件名称",
"docUrl": "文件下载地址",
"personInfo": {
"uid":"操作者UserID", //与调用时传递的uid相同
"nickName":"操作者名称",
"pid":"操作者PersonID" //操作者的用户节点ID
}
}
文件重命名推送数据
{
"action": "rename",
"callToken":"",
"docId": "文件ID",
"title": "文件名称",
"personInfo": {
"uid":"操作者UserID", //与调用时传递的uid相同
"nickName":"操作者名称",
"pid":"操作者PersonID" //操作者的用户节点ID
}
}
回调地址返回给office数据格式
{
"status": true
}
其中callToken为用户自定义参数,在打开文档opts中传入callToken参数（非必要参数），文件回存时将该参数值回传
用户在文档编辑器界面，手动点击新版本时，回存数据中的personInfo将为操作者的用户信息；在系统触发的回存中，由于没有实际的操作者，personInfo中的各项目固定为“system”。
¶ 回存服务调用时机：
有如下几种情况将会触发系统回存服务：
- 所有的编辑参与者退出编辑，且在是1分钟内没有任何用户重新进入编辑；
- 有一个用户在客户端出发了新版本的请求；
¶ 创建APP空间
系统管理员root登录到系统后台，点击右侧开发设置->开发设置进入到设置页面，进入应用集成tab，可以点添加APP来创建新的APP空间。 在对话框中设置APP的名称，回存地址，是否开启安全验证等内容（这些内容可以APP列表中进行修改）系统将创建一个APP空间，并随机生成一个APP空间的ID和APP key.
安全验证开关设置为开启状态时将进行签名的检查，默认为关闭状态。
¶ 设置APP空间
在APP空间的列表中展示了系统所有的APP空间，root管理员可以对APP空间进行设置。例如重置APP key,修改名称等
¶ 查看APP空间的内容
APP空间创建成功后将同时创建一个同名的团队空间，并可设置APP空间的管理者信息（与团队空间管理者概念相同）。root管理员可以给APP空间添加管理员，这样被添加的管理员可以在他的团队空间中看到该APP空间的内容
在管理员的团队空间中可以看到该APP空间的内容
¶ 默认APP空间
在集成毕升office API时，如果不指定对应的APP空间（即不传入store参数部分），则会使用默认的APP空间。文件将会被记录在默认APP空间对应的团队空间的根目录下。 默认APP空间的默认情况是关闭了安全验证的。如果开启了安全验证，不传入store参数将会报错。
¶ 自定义参数
自定义参数存在于集成文档参数opts中，可以用于指定用户打开文件的权限和文件的水印。
{
"opts": {
"privilege": [
"FILE_READ"
],
"watermark": {
"width": 300,
"height": 200,
"rotate": -45,
"text": "毕升office",
"text2": "2018-2020",
"fontSize": 16,
"color": "acacac",
"alpha": 0.2,
"offsetX": 50,
"offsetY": -50,
"images": [
{
"image": "",
"imagePosType": "absolute",
"imageScale": 0.25,
"imageLeft": 0,
"imageRight": 10,
"imageTop": 10,
"imageBottom": 0
}
]
}
}
}
¶ 指定文件打开的权限
在默认情况下，集成调用毕升Office时不需要特别指定用户打开这个文件的权限。毕升Office默认用户本次操作拥有毕升Office编辑器支持的全部权限，这些权限包括：
- FILE_READ：可读，用户可以预览该文件。
- FILE_WRITE：可编辑，用户可以编辑该文件。
- FILE_DOWNLOAD：可下载，用户可下载该文件。
- FILE_PRINT：可打印，用户可以打印该文件。
- FILE_CONTENT：文件内容权限设置。
- FILE_SHARE：文件共享设置。
如果默认权限在实际过程中过大，则需要在调用时增加权限参数。如下时包含了权限参数（privilege数组）之后调用毕升Office的json格式数据：
{
"doc": {
"docId": "docId002",
"title": "doc002.docx"
},
"token": "tokenInfo001",
"store": {
"appId": "appId001",
"time": "2022-05-28 00:32:16",
"sign": "timeSignResult",
"folderPath": "/",
"newVersion": false
},
"opts": {
"privilege": [
"FILE_READ",
"FILE_WRITE",
"FILE_DOWNLOAD",
"FILE_PRINT",
"FILE_CONTENT"
]
}
}
在实际使用过程中更加实际使用需要可以减少部分权限：例如预览模式下：如果是在预览模式下，需要隐藏编辑以及下载按钮，可以不传FILE_WRITE和FILED_DOWNLOAD这两个权限值。在编辑模式下，如果禁止文件下载，可以不传入FILE_DOWNLOAD参数。
¶ 指定文件水印
本版本水印的实现为，在编辑可见区中，按照指定长宽，将可见区进行分块，如下图。水印的文字将会在每个水印块中进行绘制。水印绘制的位置为每个水印块的下方。
注意当水印文字的宽度超过它所做的水印块的宽度时，文字并不会被截断，而是将延伸到右侧水印区域。
如果在后台管理/设置页面中也设置了水印信息，设置页面的水印信息会被优先显示。
¶ 水印配置中各参数的含义：
- width：水印块区域的宽度。
- height：水印块区域的高度。
- rotate：水印块的旋转角度（顺时针）。
- text：水印的文字内容。
- text2：水印的文字内容。
- fontSize：水印文字的字号。
- color：水印文字颜色。
- alpha：水印的透明度（0～1之间）。
- offsetX：水印块在旋转后偏移量。
- offsetY：水印块在旋转后偏移量。
- images：水印图片信息。
- image：图片地址。
- imagePosType：值为absolute或center，默认为center居中。
- imageScale：指定图片在页面上的缩放。
- imageLeft：图片距离页面左侧的距离，当imagePosType为absolute有效。
- imageRight：图片距离页面右侧的距离，当imagePosType为absolute有效。
- imageTop：图片距离页面顶部的距离，当imagePosType为absolute有效。
- imageBottom：图片距离页面底部的距离，当imagePosType为absolute有效。
可以添加多个图片到水印中。参数为images中所示数组。对于每个图片，如果不指定定位信息，将默认在页面中间位置。
当需要指定位置时，可以把imagePosType指定为absolute，并且通过imageLeft，imageRight，imageTop，imageBotton来指定图片离页面左右上下的距离。
¶ 时间格式说明
时间字符串格式为 ISO 8601格式（建议使用）。
例如 北京时间2022-05-28 00:32:16，此处作为参数，毕升Office可以兼容如下六种形式作为参数
集成调用时如果需要向网盘系统中传递当前时间参数，可接受的字符串时间格式如下：
- 2022-05-28 00:32:16
- 2022-05-28 00:32:16+08:00
- 2022-05-28 16:32:16Z
- 2022-05-27T16:32:16
- 2022-05-28T00:32:16+08:00
- 2022-05-27T16:32:16Z
需要注意： 调用API的时间参数与毕升office服务器上的当前时间相差不能超过10分钟