毕升OfficeAPI说明

毕升OfficeAPI集成。onlyoffice 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进行签名：

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的服务器应该按照如下格式返回数据：

{
    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内容如下格式：

{
  "docId":"",
  "action":"",
  "data":{
       
  }
}

其中docId是当前文档的ID，action是当前回调的是什么类型。例如如果是编辑完成，需要把数据存回到原系统，action的值为：saveBack。data值和action的值相关。

当action的值为saveBack时，表示这次回调是编辑完成进行回存，此时的data的格式为：

{
  "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

秒客网

Office文档在线预览/在线编辑解决方案 - 毕升OfficeAPI说明