Office文档在线预览/在线编辑解决方案 - 毕升OfficeAPI说明
毕升OfficeAPI说明
毕升OfficeAPI集成。onlyoffice api集成
- 使用毕升Office编辑，预览文件的过程
- Api 具体说明
- HMAC-MD5签名
- callURL返回值
- 如何检查callURL是否正确
- 文档回存
- 回存时间间隔
- demo说明
- Api 具体说明
- 其他API说明
- 删除文件
- 移除协同编辑者
毕升OfficeAPI说明
毕升OfficeAPI主要包括文件的在线预览编辑等功能。可以供其他线上系统（OA，erp,网盘等）调用，在线编辑，预览Office等各类文件。
与本文相关的链接有：
集成版GitHub托管安装脚本 https://github.com/ibisheng/onlyoffice-api-deploy
集成版Gitee 托管安装脚本 https://gitee.com/ibisheng/onlyoffice-api-deploy.git
集成版 API demo：https://gitee.com/ibisheng/onlyoffice-api
使用毕升Office编辑，预览文件的过程
编辑时调用的链接为：http://bisheng_host/apps/editor/openEditor?callURL=XXX&sign=XXX
预览时调用的链接为：http://bisheng_host/apps/editor/openPreview?callURL=XXX&sign=XXX；
这两者调用过程，参数，错误代码都是类似，下面以编辑为例详细介绍编辑/预览过程以及当中的参数含义：
在使用集成版对文档进行编辑时的流程如下图描述
下面是文字对上图过程的解释：
-
当用户线上需要打开一个文档时（例如点击了OA系统的word 文件），需要在浏览器中打开一个链接。该链接的格式为： http://bisheng_host/apps/editor/openEditor?callURL=XXX&sign=XXX；其中bisheng_host的值为你部署的毕升Office的访问地址。参数 callURL为一个base64编码的链接，该链接会被毕升Office调用，来获取打开文档的相关参数，例如：文档的ID，名称，获取文件的地址，谁打开文件等。详细情况会在后面的参数部分有说明。参数sign，是使用毕升Office api key对参数 callURL进行的hmac md5编码,毕升Office在收到请求后会sign进行校验。
-
当毕升Office服务器收到请求之后，首先会对sign进行校验，如果校验不正确则会返回错误
1
{"code": "check callURL sign error"} -
在sign校验成功之后，会对参数callURL进行解码，解码成功会得到一个URL，如果解码失败，会返回错误:
1
{"code": "decode callURL error"}然后根据URL请求调用系统，获取本次编辑的相关信息。这些信息有两部分：1. 文件，文件的ID，名称，文件的地址等，2.发起这次编辑的用户的相关信息：用户的ID，头像，昵称，用户对这个文件的权限等信息。如果获取这些数据失败则会返回错误。错误为：
1
{"code": "request callURL error", "callURL": callURL，"error":错误信息}其中错误信息为请求callURL并解析返回结果是产生错误的原因
-
在第三步参数获取正确之后，会对根据返回的数据检查用户对这个文件是否有编辑权限，如果没有编辑权限，则会返回错误。
1
{"code": "权限不足"} -
完成以上几步之后，毕升Office会根据文件的类型选择相应的应用打开文件。如果根据文件类型找不到相应的应用，则会返回错误302；如果正确则浏览器端会自动转向编辑链接。以上2，3，4，5都是发生毕升Office服务端，用户无感知，这里详细介绍是为了帮助大家理解API执行过程
Api 具体说明
HMAC-MD5签名
在上文的描述中，需要使用HMAC-MD5 对请求参数callURL进行签名，其中key为从控制台得到的 api key（如下图）。下面的代码是以nodejs 使用API签名45ae1f8b5d50ea9322a3d8e3326ca0f9我们对字符串 bishengoffice.com进行签名：
1 2 3 4 5 6 7 |
var crypto = require('crypto');
var hmac = crypto.createHmac('md5', '45ae1f8b5d50ea9322a3d8e3326ca0f9');
data = hmac.update('bishengoffice.com');
gen_hmac= data.digest('hex');
console.log("hmac : " + gen_hmac);
==========================输出为：
hmac : a3bcad4f42b7b41edbf7f737bd4d8254
|
在实际的开发中，需要根据具体开发语言实现相应HMAC-MD5 ，并且可以使用上面例子中的数据来验证实现是否有问题。
需要注意的是：如果改算法不正确，则API调用会失败
callURL返回值
在调用在线编辑和预览的时候，callURL参数是一个URL地址的base64编码后的字符串。毕升Office服务器在解码得到该URL之后会从服务器请求该URL，以获取本次编辑的相关数据。响应该URL的服务器应该按照如下格式返回数据：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
{
doc: {
docId: "",
title: "",
mime_type: "",
fetchUrl: "",
thumbnail:"",
pdf_viewer: false,
fromApi:true,
callback:""
},
user: {
uid: "",
oid: "",
nickName: "",
avatar: "",
privilege: [
'FILE_READ','FILE_WRITE','FILE_DOWNLOAD', 'FILE_PRINT' //如果你需要在在预览模式隐藏编辑以及下载按钮，可以不传递FILE_WRITE以及FILE_DOWNLOAD
],
opts:{}//可为空，在自定义UI是将会使用到该值
},
}
|
返回数据说明：
doc:当前编辑预览的文档的信息。其中各个属性值的含义如下；
docId: 文档的ID，不同的文档通过docId 来区分。
title: 文件的标题，用于编辑时在编辑器上显示当前文件的标题，需包含加上文件扩展名
mime_type：文件的类型。毕升支持的各类文件类型参考链接：毕升Office支持文件类型的mime_type
fetchUrl: 该文件的获取链接。当毕升Office打开该文件时，会通过这个链接去获取文件。该链接不要进行编码
thumbnail: 该文件的缩略图，目前只有视频文件会用该值在视频播放钱进行展示，其他文件可以为空。
fromApi： API模式下必须为true。
pdf_viewer： 该值true时，Office文件将使用pdf模式进行预览。默认为false，将使用Office预览
callback: API模式下可以通过改参数指定文档的回调地址，也可以不传递该参数而通过配置文件统一配置回存地址。
user: 当前编辑预览文档的用户的信息
uid：用户ID，不同的用户通过uid来做区分。
oid: api调用模式下无特别意义，保持和uid一致即可
nickName： 用户昵称。用于多人编辑时标示不同的用户。
avatar：用户头像地址。用于多人编辑时 在右上角显示各个用户。
privilege： 该用户对目前编辑/预览的文件有何种权限。目前API模式下支持4种权限： FILE_READ：可读，用户可以预览该文件，FILE_WRITE:可编辑，用户可以编辑该文件；FILE_DOWNLOAD：可下载，用户可下载该文件；FILE_PRINT：可打印，用户可以打印该文件。在用户进入编辑，预览，下载，打印之前，会进行权限检查。需要注意：如果是在预览模式下，需要隐藏编辑以及下载按钮，可以不传FILEWRITE和FILEDOWNLOAD这两个权限值
如何检查callURL是否正确
大部分用户在集成过程中碰到的问题都是由于callURL参数值导致的。常见的问题是有：
- base64编码不正确
- callRUL参数解码后docker 容器内请求得不到数据。
- callURL请求得到的数据有误
callURL出问题表现的结果是会如下格式的错误
1 |
{"code": "request callURL error", "callURL": callURL}
|
或者
1 |
{"code": "callURL decode error"}
|
如果你在集成过程中碰到了类似的错误可以安装如下部署排除：
-
url本身的问题
在上面的文档中已经介绍过：callURL参数值是一个url进行base64编码，毕升Office服务器在收到请求之后，对callURL值进行解析，然后请求该url得到上面文档中要求的数据。
首先第一步，在浏览器中直接打开这个URL，查看浏览器是否能得到正确的数据。同时需要注意 url的值需要加上 http:// 或者https://
-
确认是否是编码问题。
例如：你的url值为 http://HOST/fileAcl/docid/user/abcd ，首先对这个url进行base64编码得到值：aHR0cDovL0hPU1QvZmlsZUFjbC9kb2NpZC91c2VyL2FiY2Q; 该值就是callURL的参数值。
校验base64编码是否的方法是打开浏览器控制台，使用浏览器原生函数btoa对url进行编码，得到的值和你的程序的值进行对比，检查是否一致。
也可以采用浏览器的atob函数来解码你的程序base64编码url的结果，检查解码是否能够得到和url值一样的结果，并且在浏览器中打开这个url，检查是否能够得到上面文档中要求的数据。
-
在docker内是否能请求到数据。
如果上面第一步和第二步都正确，集成毕升Office打开文件时依然出错，需要进入到docker 容器内部去检查 url 所对应的链接在 docker 容器内是否时通畅的。可以按照如下命令来进行：
首先进入到 docker容器：
1
docker exec -it editor_app bash
然后执行 命令 curl http://HOST/fileAcl/docid/user/abcd // 实际过程中使用你的url值。
执行该命令之后，应该会得到上文中需要的数据，如果得不到需要的数据，则说明url所对应的链接在docker 内是不通的。请详细检查网络情况
文档回存
当所有用户退出编辑之后一段时间后（正式环境是5分钟，test环境为1分钟），毕升Office服务器会将用户编辑的内容重新生成Office（docx,pptx,xlsx）文件，此时会根据毕升Office中API配置来回调，将新的文档送回到原有系统中，原有系统需要实现这个过程。为了使得编辑的内容能过回存到原系统，首先需要修改毕升Office的配置。
毕升Office的配置文件的位置是 /bisheng_data/workspace/config/config.yml**（如果你安装目录不是bisheng_data，请将bisheng_data替换为你的安装目录）**
编辑config.yml，在配置文件中增加API回调
1 2 |
apis: postapiurl: http://192.168.2.66:9090/api/file/saveBack |
修改毕升Office的配置之后，需要重启毕升Office服务
1 |
bash restart.sh |
上面的例子是demo代码中使用的配置。在实际开发中请根据你的实际情况进行修改。
需要注意的是：postapiurl中的地址是一个post请求。在实现请注意
该post请求的body内容如下格式：
1 2 3 4 5 6 7 |
{
"docId":"",
"action":"",
"data":{
}
}
|
其中docId是当前文档的ID，action是当前回调的是什么类型。例如如果是编辑完成，需要把数据存回到原系统，action的值为：saveBack。data值和action的值相关。
当action的值为saveBack时，表示这次回调是编辑完成进行回存，此时的data的格式为：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
{
"docId":"",
"docURL":"",
"docUrlEncode":"",
"modifyBy":[{
"uid":"",
"oid":"",
"avatar":"",
"nickName":""
}],
unchanged: true/false,
"pngUrl":"",
"txtUrl":"",
"txtUrlEncode":"",
"pngUrlEncode":""
}
|
各部分key的意义时：
docId 是当前回存文档的ID，
docURL是修改完最新的文件的下载地址;
docUrlEncode: docURL的base64编码，用于用户对docURL进行校验
unchanged 是标示这个文件有没有被修改；
pngUrl这个文件最新的缩略图；
pngUrlEncode：pngUrl的base64编码，用于用户对pngUrl进行校验
txUrl 这个文件最新提取的文本;
txtUrlEncode： txUrl的base64编码，用于用户对txUrl进行校验
modifyBy：这个文件在这次编辑过程中被哪些人修改过。
回存时间间隔
在默认情况下，所有的编辑参与者退出编辑5分钟之后，毕升Office会触发回存逻辑；或者在所以用户退出编辑之后，如果有用户再打开预览，也会触发回存。在集成调试过中，5分钟会有点长，因此毕升Office提供自定义配置回存时间间隔的功能。配置方法如下：
毕升Office的配置文件的位置是 /bisheng_data/workspace/config/config.yml**（如果你安装目录不是bisheng_data，请将bisheng_data替换为你的安装目录）**
编辑config.yml，在配置文件中增加回存时间项：
1 |
savebacktime: 1 // 值为大于零的数字 |
上面的例子中：配置了回存时间间隔为1分钟（配置的值只需要数字，否则会出错）。时间值根据你实际调试过程中的需要进行调整。在生产环境不建议把该值设置低于3
修改毕升Office的配置之后，需要重启毕升Office服务
1 |
bash restart.sh |
demo说明
在demo中，当用户点击文件列表中的编辑按钮时，会进入到demo服务端代码，由相应的uri进行响应，该响应最后会生成一个调用毕升Office编辑的链接让浏览器打开；其中callURL参数在这个过程会生成。
毕升Office服务器端在收到请求后，进过一系列的处理，最后会根据callURL参数的地址，请求demo服务器，获取本次编辑的数据。demo服务器响应，并按照格式返回数据
同时demo服务器还会处理获取文件请求，把该文件返回给毕升Office服务器。当然在实际过程，这个地址可以各种可以下载文件的地址。例如：ftp,s3,普通http请求等。
文件完成编辑之后，会回调到demo服务器，demo服务器响应了该请求，做出响应的处理。在实际过程中，集成方系统也需要对回存的文件进行处理
其他API说明
免费版还提供一些API，主要用于处理当文件源头发生改变之后，通知毕升Office编辑进行相应的处理。例如：当源头文件被删除了，需要通知毕升Office关闭此文件的编辑。目前开放的API有删除文件API，移除协同编辑者API
删除文件
当你集成了毕升Office之后，如果你的系统中的文件被删除了，你可以通知毕升Office来关闭改文件的编辑。此时你可以调用这个API；
该API的地址为： http://bisheng_host/apps/editor/deleteFile/docId 其中 docId为该文档的id, 该API被调用之后，将会通知正在编辑这个文件的所有参与者，文件被删除了，必须关闭编辑；如果此时没有人在编辑这个文件，则什么也不会发生。
注意：该API为post请求；
该 API返回值为json对象，内容如下：
如果发生错误该则返回如下：
1 2 3 |
{
"status": false,
}
|
否则返回值如下：
1 2 3 |
{
"status": true,
}
|
移除协同编辑者
移除协同编辑者的API主要用于一下场景：在你的系统，你移除了某些人的权限，或者你取消了这个文件的共享。这个时候需要调用这个API来让参与编辑某个人或者所有人都退出编辑。该API有两种形式，且都为post请求：
-
http://bisheng_host/apps/editor/removeParticipant/docId
-
http://bisheng_host/apps/editor/removeAllParticipant/docId
这两种形式的API中的 docId为文档的ID，
第一个将移除某一些协同编辑者；post请求的参数body为一个用户ID的数组，该数组中的用户都是将被移除的协同编辑者。
第二个将移除所有的协同编辑者，让所有参与该文档编辑的用户退出，然后从源文件处打开编辑。
该 API返回值为json对象，内容如下：
如果发生错误该则返回如下：
1 2 3 |
{
"status": false,
}
|
否则返回值如下：
1 2 3 |
{
"status": true,
}
|
- 本文作者：毕升office
- 本文链接： https://bishengoffice.com/apps/blog/posts/onlyoffice-api.html
- 版权声明： 本公司网站所有内容均采用 CC BY-NC-SA 3.0 CN 许可协议。转载请注明出处！
# api