本文介绍毕升office v4版本中预览协同编辑集成的使用。
在集成使用Office预览、编辑文件功能时集成方需要提供本次操作的文档信息。文档信息由5部分组成:文件信息、Token信息、用户信息、存储信息、自定义参数。信息基本形式如下,下文针对各部分进行了解释说明。
{
"doc": {
"docId": "docId001",
"title": "doc001.docx",
"fetchUrl": "http://yourhost/download/docId001",
"versionId": "docVersionId001"
},
"token": "tokenInfo001",
"user":{
"uid": "",
"nickName": "",
"avatar": ""
},
"store": {
"appId": "appId001",
"time": "2022-05-28 00:32:16",
"sign": "timeSignResult",
"folderPath": "/",
"newVersion": false
},
"opts": {
"privilege": [
"FILE_READ"
],
"callToken":""
}
}
文档信息中的doc项目为文件信息。
文档信息中的token项目为Token信息。详细请参考授权签名(默认为开启token,可以设置关闭token)。在未关闭签名授权时,token参数为必须;而用户参数则不需要。
user参数为用户信息,即预览编辑用户时的具体用户,在关闭签名授权时,该参数是必须,而无需传入token参数。
文档信息中的store项目为存储信息,记录文件在网盘中的存储位置等信息。详细请参考存储信息(APP空间)内容。
文档信息中的opts项目为可选参数,例如设置office的相关行为,用户权限等。下例设置了用户的文件读取权限。详细请参考自定义参数内容。
"opts": {
"privilege": [
"FILE_READ"
],
"callToken":""
}
callToken参数值为自定义字符串,非必传选项,如果传了该参数,文档回存时将该参数进行回传
该方法的基本原理是在对数据进行简单处理之后在毕升Office的地址中使用参数来传递数据。对于简单应用场景(例如:Office文件预览,简单编辑等需求)可以使用这种方法。这种方式的具体使用方法如下:
编辑时调用的链接为:http://bsd_ClientHost/apps/drive/openEditor?data=XXX
预览时调用的链接为:http://bsd_ClientHost/apps/drive/openPreview?data=XXX
其中data的值为上文中提到的文档信息首先经过序列化得到字符串,然后对字符串进行进行base64编码得到的值。data值首先会在毕升Office服务器上进行解析得到本次文件预览、编辑的数据,然后调用相应的Office服务进行处理。例如:本次编辑操作所需的文档信息如下:
{
"doc": {
"docId": "docId002",
"title": "doc002.docx"
},
"token": "tokenInfo001",
"store": {
"appId": "appId001",
"time": "2022-05-28 00:32:16",
"sign": "timeSignResult",
"folderPath": "/",
"newVersion": false
}
}
首先对以上json数据进行序列化,得到如下字符串:
然后对字符串进行base64编码得到:
eyJkb2MiOiB7ImRvY0lkIjogImRvY0lkMDAyIiwidGl0bGUiOiAiZG9jMDAyLmRvY3gifSwidG9rZW4iOiAidG9rZW5JbmZvMDAxIiwic3RvcmUiOiB7ImFwcElkIjogImFwcElkMDAxIiwidGltZSI6ICIyMDIyLTA1LTI4IDAwOjMyOjE2Iiwic2lnbiI6ICJ0aW1lU2lnblJlc3VsdCIsImZvbGRlclBhdGgiOiAiLyIsIm5ld1ZlcnNpb24iOiBmYWxzZX19
因此得到文件的编辑地址为:
http://bsd_ClientHost/apps/drive/openEditor?data=eyJkb2MiOiB7ImRvY0lkIjogImRvY0lkMDAyIiwidGl0bGUiOiAiZG9jMDAyLmRvY3gifSwidG9rZW4iOiAidG9rZW5JbmZvMDAxIiwic3RvcmUiOiB7ImFwcElkIjogImFwcElkMDAxIiwidGltZSI6ICIyMDIyLTA1LTI4IDAwOjMyOjE2Iiwic2lnbiI6ICJ0aW1lU2lnblJlc3VsdCIsImZvbGRlclBhdGgiOiAiLyIsIm5ld1ZlcnNpb24iOiBmYWxzZX19
在集成时,集成方需要实现一个HTTP GET请求以返回集成毕升Office所需要的数据。在使用本方法对Office对文件进行编辑或者预览的地址为:
编辑时调用的链接为:http://bsd_ClientHost/apps/drive/openEditor?callURL=XXX
预览时调用的链接为:http://bsd_ClientHost/apps/drive/openPreview?callURL=XXX
其中callURL是集成方实现的http GET服务请求地址的base64编码。
例如:在我们提供的demo示例中,该callURL对应的原始地址为http://demohost/api/getData/docId001/user001,对地址进行base64编码,得到结果为:aHR0cDovL2RlbW9ob3N0L2FwaS9nZXREYXRhL2RvY0lkMDAxL3VzZXIwMDE=
因此得到的文件编辑地址为:
http://bsd_ClientHost/apps/drive/openEditor?callURL=aHR0cDovL2RlbW9ob3N0L2FwaS9nZXREYXRhL2RvY0lkMDAxL3VzZXIwMDE=
以上流程可以用下图描述
解析请求数据时,可能返回的错误信息如下:
callURL的返回结果中也可以指定集成方的错误信息,错误信息将在客户端显示。返回案例如下:
{
"status": true,
"resError": "callURL错误"
}
文件处理时,可能返回的错误信息如下:
当文档信息中存储信息指定的APP空间设置了回调地址时,使用集成方式操作Office文件生成文件新版本时,会将文件新版本的下载地址以POST方式推送到此地址中。推送的数据格式为:
{
"docId": "文件ID",
"title": "文件名称",
"docUrl": "文件下载地址",
}
集成方可以使用此下载链接获取生成的文件新版本。
本文档主要介绍集成中的基本情况。集成中的其他配置信息参考集成配置页面。
集成demo参考中介绍了集成毕升Office的基本过程。如果有需要请参考集成Demo使用页面。
毕升提供提供App ID的HashMD5签名测试仪供开发者进行测试。该测试方法可以用来测试开发者的HashMD5签名算法是否正确。
调用url为:/apps/api/devTest/testAppIDHMAC?appid=xxx&appkey=xxx&time=xxx 请求方式为http get请求。
参数appid为使用app空间的appid, appkey为app空间的appkey,time为待签名的时间。 返回值如下:
{
status:true,
signed:"",
err:""
}
其中: signed为使用参数中的appkey对参数中的time进行签名的结果。如果参数有错误,err将会返回错误原因。主要的错误原因有:
在使用该方法集成毕升office时,需要保证参数的编码正确,javascript base64
javascript base64编码以及解码可以参考:
function base64Encode(text){
return btoa(unescape(encodeURIComponent(text)))
}
function base64Decode(text){
return JSON.parse(window.decodeURIComponent(window.atob(text)))
}