跳到主要内容

前端集成主动传参模式

集成示意​

集成示意图

  1. Filez文档中台和业务系统需要约定一个secret用来就算请求url的hmac
  2. 业务系统前端需要调用在线编辑/预览服务时，请求业务系统的服务端。由业务系统的服务端根据secret来生成在线编辑/预览的url。url如下面的格式
http(s)://${zOffice_domain}/docs/app/driver-callback?repoId=${repoId}&docId=${docId}&action=edit&userinfo=${userInfo}&meta=${meta}&downloadUrl=${downloadUrl}&uploadUrl=${uploadUrl}&params=${params}&ts=${ts}&HMAC=${hmac}

全部请求参数查看请求参数

  1. Filez文档中台server收到请求后，首先会根据HMAC值验证请求是否是正确，确保相关参数不会被篡改。
  2. 根据ts（时间戳）验证请求是否过期，以保证在线编辑/预览的请求不会被任意传播。缺省情况，一个在线编辑/预览请求url地址的有效期是10秒。需要业务系统和Filez文档中台时间同步。
  3. 从参数userinfo 和meta中获取相关信息后，从downloadUrl指定处下载文件。

主动传参模式​

请求地址：

GET http(s)://${zOffice-server-IP}:${zOffice-server-port}/docs/app/driver-callback

请求参数定义如下

参数名是否必选描述
repoId是第三方服务在zOffice中的唯一标识ID，第三方服务自行定义，需同时在管理控制台上设置。
docId是文档在第三方系统中的唯一ID
action否标识打开文档的行为，取值edit或view，默认为view
userinfo是标识进行操作的用户信息，是base64编码的JSON字符串。base64(JSON.stringify(userinfoObj))。拼接到URL之前需要使用encodeURIComponent编码
meta是标识当前文档的元信息，是base64编码的JSON字符串。base64(JSON.stringify(metaObj))。拼接到URL之前需要使用encodeURIComponent编码
downloadUrl是下载文件流的地址，通过该url可以下载文件。对应的URL地址不可以使用encodeURIComponent编码，请勿包含请求参数，需要传递的请求参数通过params传递。
downloadUrl 与管理控制台中该应用配置的接口地址前缀的host必须一致。host 包含hostname和端口。如果downloadUrl中的host 不带端口，相关配置也不要带端口，即使是缺省端口
uploadUrl否文件上传地址。预览文档时可以忽略，编辑文档时需要传递。对应的URL地址不可以使用encodeURIComponent编码，请勿包含请求参数，需要传递的请求参数通过params传递。
params否需要回传的信息，格式key=value;key2=value2。
如果请求downloadUrl和uploadUrl时，三方系统有权限验证，请务必在params中传递相关身份信息，否则会导致请求失败。
详细见下方params说明
ts是URL生成的时间戳，精度毫秒
HMAC是请求URL加盐哈希值，用于验证请求地址是否被篡改

示例

http://luoshuhost:8001/docs/app/driver-callback?  
repoId=thirdpart-rest&  
docId=demo-docx-123&  
action=edit&  
userinfo=eyJpZCI6ImxpY2h1biIsImRpc3BsYXlfbmFtZSI6Iueri%2BaYpSIsImVtYWlsIjoibGljaHVuQGxlbm92b2Nsb3VkLmNvbSJ9Cg%3D%3D&  
meta=eyJjcmVhdGVkX2J5Ijp7ImlkIjoibGljaHVuIiwibmFtZSI6ImxpY2h1biIsImVtYWlsIjoibGljaHVuQGxlbm92b2Nsb3VkLmNvbSJ9fQ%3D%3D&  
downloadUrl=http://thirdparty-file-server/context/content&  
params=3rd-party-token=xxx;id=demo-docx-123;x-webhook-header=xxx&  
ts=1685673093648&  
HMAC=8b48d4833bd2e22203eb890c91a6fe08df6056bf3bda126ab31e5a9d9c04aad5
uploadUrl说明

文档中台server 用http post，通过formData上传文件。content type是 multipart/form-data。

参数必须位置说明类型
Content-Type是Header固定为multipart/form-datastring
file是Body(form data)文件本身, 包含两个属性：filename（固定为 content, 请忽略。目前不会通过这个API去修改文件名），contentType（文件的mimeType，例如 'application/octet-stream'）multipartfile

上传成功，需要返回最新的文件修改时间。

例如：

{
    "modified_at": "2020-03-25T02:57:38.000Z" //必须有，这个时间应该是这个文件在业务系统中最新的保存时间，并且该保存由这个API带来。
}

userinfo说明​

属性

字段名是否必须描述
id是用户ID
display_name是用户昵称
email是用户邮箱，可以和id相同
photo_url否用户头像

JSON表示

{  
  "id": "301", //用户ID  
  "display_name": "docstest02", //用户昵称  
  "email": "docstest02@lenovocloud.com", //用户邮箱  
  "photo_url": "https://avatar.thirdparty.com/testOrg/people/301.png", //用户头像  
}

meta说明​

meta支持传入如下信息，其他信息会被过滤，以下信息可选择只传输部分信息

属性

字段名是否必须类型示例值描述
id是String577唯一的文件ID，必须与请求url中的docId一致
name是String预览中心.docx包含拓展名的文件名
modified_at是String2023-08-17T13:57:38.000Z修改时间，格式需要和左侧示例一致。详细描述见下面
created_by.id是String301文档创建者id
created_by.name是Stringdocstest02文档创建者名称
permissions.write是Booleantrue是否有编辑权限
permissions.read是Booleantrue是否有读权限
permissions.download否Booleantrue是否可以下载文件。不能下载文件，文件的内容也不能复制到除当前文件外的地方。缺省值是false
permissions.print否Booleantrue是否可以打印文件。缺省值是false
role否Stringcommenter该项值可以是"contributor", "commenter"，"auditor"。缺省值没有
waterMark.line1否StringFilez zOffice docstest02水印第一行，默认为空
waterMark.line2否Stringlast modified user水印第二行，默认为空
waterMark.line3否Stringproduct info水印第三行，默认为空
waterMark.line4否Stringmore info水印第四行，默认为空
waterMark.withData否Booleantrue水印是否带日期，默认true
waterMark.fontcolor否String#cecece水印颜色，默认灰色
waterMark.transparent否Number70透明度。值越小，透明效果越明显，默认70，类型为数字
waterMark.rotation否Number315旋转角度，取范围0-360，例如左倾斜=315，右倾斜=45，水平=0，类型为数字
waterMark.fontsize否String16水印字号，默认16
waterMark.font否String黑体水印字体，默认黑体
waterMark.spacing否Number50行间距，默认50，类型为数字
owner.id否String301文档所有者id
owner.name否Stringdocstest02文档所有者名称
extension.previewWithTrackChange否Booleanfalsetrue表示预览时自动显示修订。false或者不提供该字段表示预览时不显示修订。仅针对文字文档
extension.trackChangeForceOn否Booleanfalsetrue表示编辑时自动打开修订，并且不能关闭。false或者不提供该字段表示编辑时不强制打开修订。仅针对文字文档。

JSON表示

{  
  "id": "577",  
  "name": "预览中心.docx",  
  "modified_at": "2023-08-17T13:57:38.000Z",  
  "created_by": {  
    "id": "301",  
    "name": "docstest02"  
  },  
  "permissions": {  
    "write": true, //控制文档是否可以被编辑  
    "read": true, //控制文档是否可以被预览  
  },
  "role": "commenter", //可选项，指明当前用户对当前文档在zoffice编辑器里的角色(仅针对文字文档)。该项值可以是"contributor"，"commenter"，"auditor"。  
  "extension": {  
    "previewWithTrackChange":false, //true表示预览时自动显示修订。false或者不提供该字段表示预览时不显示修订。仅针对文字文档。  
    "trackChangeForceOn":false, //true表示编辑时自动打开修订，并且不能关闭。false或者不提供该字段表示编辑时不强制打开修订。仅针对文字文档。  
  },  
  "waterMark":{ //文档水印相关  
    "linel": "李明liming@lenovo.com", //比如文件最后更新者信息  
    "line2": "张三hangshan@lenovo.com", //比如：文件编辑者/预览者信息  
    "line3": "", //比如：其他自定义文字  
    "line4": "", //比如：其他自定义文字  
    "withDate": true, //每行文字后，是否带日期  
    "fontcolor": "#fD4147", //RGB值，  
    "transparent": 30, //0-100,透明度。值越小，透明效果越明显。  
    "rotation": 315, //旋转角度0-360，左倾斜=315，右倾斜=45，水平=0  
    "fontsize": "72",  
    "font": "黑体"  
  }  
}

modified_at 实现时，必须注意 请参考：缓存说明

params​

params中传递的信息会在调用三方接口时，同时在header，cookie，queryParams中回传。

比如当params=x-param-1=aaa;x-param-2=bbb时，三方接口为/v2/context/docId/content时，三方实际收到的请求如下

请求地址： /v2/context/docId/content?x-param-1=aaa&x-param-2=bbb

请求头：

x-param-1: aaa
x-param-2: bbb

Cookie: x-param-1=aaa;x-param-2=bbb

注意： 需要在header中回传的参数，必须开头是x-（可以通过修改特殊配置headerPrefix默认值）

最后于 更新