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
Office文档在线预览/在线编辑解决方案 - 毕升OfficeAPI说明相关推荐
- 基于MVC4+EasyUI的Web开发框架经验总结(8)--实现Office文档的预览
在博客园很多文章里面,曾经有一些介绍Office文档预览查看操作的,有些通过转为PDF进行查看,有些通过把它转换为Flash进行查看,但是过程都是曲线救国,真正能够简洁方便的实现Office文档的预览 ...
- [转载]基于MVC4+EasyUI的Web开发框架经验总结(8)--实现Office文档的预览
在博客园很多文章里面,曾经有一些介绍Office文档预览查看操作的,有些通过转为PDF进行查看,有些通过把它转换为Flash进行查看,但是过程都是曲线救国,真正能够简洁方便的实现Office文档的预览 ...
- (转)基于MVC4+EasyUI的Web开发框架经验总结(8)--实现Office文档的预览
http://www.cnblogs.com/wuhuacong/p/3871991.html 基于MVC4+EasyUI的Web开发框架经验总结(8)--实现Office文档的预览 在博客园很多文章 ...
- WEB前端实现在线预览、编辑Office文档
这篇文章介绍如何在web前端引入JS插件实现在线预览.编辑Office文档. 使用插件:Spire.Cloud在线Office文档编辑器(官网:冰蓝科技在线编辑) 重点:该方案仅需浏览器支持HTML5 ...
- 文件在线预览(免费)--毕升office系统
文件在线预览(免费)–毕升office系统 官网地址: https://ibisheng.cn/ 主要的特点: 小微企业以及小型团队(最大20连接)一键部署,免费使用. 政企客户离线,多结点部署,满足 ...
- word文档打印预览有阴影_在打印预览中编辑Microsoft Word 2007文档
word文档打印预览有阴影 When working on Word 2007 documents for the office wouldn't it be nice to edit them wh ...
- word文档打印预览有阴影_在打印预览中编辑Word文档
word文档打印预览有阴影 While viewing a Word document in the Print Preview window, you might notice a typo, or ...
- 100+文档格式预览,私有化部署,10分钟搭建专属IM
即时通讯是已经深入到我们的工作.学习和工作中,用户数量节节高升. <中国即时通信市场现状深度分析与发展前景预测报告(2022-2029年)>显示:2021年我国即时通讯用户为10.07亿人 ...
- 智能媒体管理产品文档转换/预览功能介绍(4)--快速搭建
摘要: 智能媒体管理提供了 Cloud Native 架构的文档转换/预览服务,本文介绍快速搭建的示例,让您用 DIY 的体验方式实现文档预览功能. 一.导语 智能媒体管理 提供了 Cloud Nat ...
- 智能媒体管理产品文档转换/预览功能介绍(1)---Cloud Native架构
一.导语 办公文档是每个人日常频繁使用的工具,ppt.word.xls.wps.pdf等为我们工作和生活带来了很多的便利,本文介绍在云计算和智能手机时代,基于 智能媒体管理 的新型Cloud Nati ...
最新文章
- 多模态商品推荐与认知智能背后的数学
- 包邮送书 | 中科院博士推荐的50本高质量Python、数据分析书籍
- Swift 位运算练习
- python所有变量更新_PYTHON:使用python变量更新MULTIPLE COLUMNS
- java范例_Java范例集锦(一)
- 前端学习(2663):vue3.0的todolist
- 倒序查10条数据_10 | 怎么给字符串字段加索引?
- 第一届LCI workshop @ ICCV 2019, 欢迎投稿
- Hi,我们是-MobileNet-家族
- 个人永久性免费-Excel催化剂功能第75波-标签式报表转标准数据源
- C3P0连接池详细配置
- VB界面设计与测试规则
- c+const_如何在C ++中使用const? 初学者指南
- 如何用MEGA-X构建进化树
- HTML基础学习(全)
- 控制/ 状态寄存器(RCC_CSR) 复位
- mysql 中auto_mysql中的auto_increment
- 忍者必须死代码 免费
- i5 11400f和i5 11400区别?哪个好?深度爆料评测
- Android--kotlin基础(三)
热门文章
- WebBrowser的Cookie操作
- C#开发WPF/Silverlight动画及游戏系列教程(Game Tutorial):(二)让物体动起来②
- 了解JavaScript中的prototype (实例)
- ADBannerView 的基本使用方法
- Linux 最基本命令应用
- 如何用Pygame写游戏(十九)
- 数据挖掘--挖掘建模-时序模式-ARIMA模型
- 【AI视野·今日Robot 机器人论文速览 第十一期】Mon, 21 Jun 2021
- 【深度学习】三维点云数据集总结
- Kubernetes—如何批量删除对象资源?(二十三)