毕升OfficeAPI说明

毕升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;

这两者调用过程,参数,错误代码都是类似,下面以编辑为例详细介绍编辑/预览过程以及当中的参数含义:

在使用集成版对文档进行编辑时的流程如下图描述

集成流程图

下面是文字对上图过程的解释:

  1. 当用户线上需要打开一个文档时(例如点击了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进行校验。

  2. 当毕升Office服务器收到请求之后,首先会对sign进行校验,如果校验不正确则会返回错误

    1
    {"code": "check callURL sign error"}
  3. 在sign校验成功之后,会对参数callURL进行解码,解码成功会得到一个URL,如果解码失败,会返回错误:

    1
    {"code": "decode callURL  error"}

    然后根据URL请求调用系统,获取本次编辑的相关信息。这些信息有两部分:1. 文件,文件的ID,名称,文件的地址等,2.发起这次编辑的用户的相关信息:用户的ID,头像,昵称,用户对这个文件的权限等信息。如果获取这些数据失败则会返回错误。错误为:

    1
    {"code": "request callURL error", "callURL": callURL,"error":错误信息}

    其中错误信息为请求callURL并解析返回结果是产生错误的原因

  4. 在第三步参数获取正确之后,会对根据返回的数据检查用户对这个文件是否有编辑权限,如果没有编辑权限,则会返回错误。

    1
    {"code": "权限不足"}
  5. 完成以上几步之后,毕升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调用会失败

image-20190325153100624

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参数值导致的。常见的问题是有:

  1. base64编码不正确
  2. callRUL参数解码后docker 容器内请求得不到数据。
  3. callURL请求得到的数据有误

callURL出问题表现的结果是会如下格式的错误

1
{"code": "request callURL error", "callURL": callURL}

或者

1
{"code": "callURL decode error"}

如果你在集成过程中碰到了类似的错误可以安装如下部署排除:

  1. url本身的问题

    在上面的文档中已经介绍过:callURL参数值是一个url进行base64编码,毕升Office服务器在收到请求之后,对callURL值进行解析,然后请求该url得到上面文档中要求的数据。

    首先第一步,在浏览器中直接打开这个URL,查看浏览器是否能得到正确的数据。同时需要注意 url的值需要加上 http:// 或者https://

  2. 确认是否是编码问题。

    例如:你的url值为 http://HOST/fileAcl/docid/user/abcd ,首先对这个url进行base64编码得到值:aHR0cDovL0hPU1QvZmlsZUFjbC9kb2NpZC91c2VyL2FiY2Q; 该值就是callURL的参数值。

    校验base64编码是否的方法是打开浏览器控制台,使用浏览器原生函数btoa对url进行编码,得到的值和你的程序的值进行对比,检查是否一致。

    image-20190429160856870

    也可以采用浏览器的atob函数来解码你的程序base64编码url的结果,检查解码是否能够得到和url值一样的结果,并且在浏览器中打开这个url,检查是否能够得到上面文档中要求的数据。

    image-20190429162059360

  3. 在docker内是否能请求到数据。

    如果上面第一步和第二步都正确,集成毕升Office打开文件时依然出错,需要进入到docker 容器内部去检查 url 所对应的链接在 docker 容器内是否时通畅的。可以按照如下命令来进行:

    首先进入到 docker容器:

    1
    docker exec -it editor_app bash

    image-20190429163737075

    然后执行 命令 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替换为你的安装目录)**

image-20190325220009021

编辑config.yml,在配置文件中增加API回调

1
2
apis:
postapiurl: http://192.168.2.66:9090/api/file/saveBack

image-20190325223245235

修改毕升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替换为你的安装目录)**

image-20190325220009021

编辑config.yml,在配置文件中增加回存时间项:

1
savebacktime: 1 // 值为大于零的数字

image-20190418103147945

上面的例子中:配置了回存时间间隔为1分钟(配置的值只需要数字,否则会出错)。时间值根据你实际调试过程中的需要进行调整。在生产环境不建议把该值设置低于3

修改毕升Office的配置之后,需要重启毕升Office服务

1
bash restart.sh

demo说明

demo中,当用户点击文件列表中的编辑按钮时,会进入到demo服务端代码,由相应的uri进行响应,该响应最后会生成一个调用毕升Office编辑的链接让浏览器打开;其中callURL参数在这个过程会生成。

image-20190326173525577

毕升Office服务器端在收到请求后,进过一系列的处理,最后会根据callURL参数的地址,请求demo服务器,获取本次编辑的数据。demo服务器响应,并按照格式返回数据

image-20190326173823838

同时demo服务器还会处理获取文件请求,把该文件返回给毕升Office服务器。当然在实际过程,这个地址可以各种可以下载文件的地址。例如:ftp,s3,普通http请求等。

image-20190326174103980

文件完成编辑之后,会回调到demo服务器,demo服务器响应了该请求,做出响应的处理。在实际过程中,集成方系统也需要对回存的文件进行处理

image-20190326174526465

其他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请求

  1. http://bisheng_host/apps/editor/removeParticipant/docId

  2. 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,
}

欢迎登陆毕升文档了解更多详细信息