跳到主要内容

三方集成机制

文件、用户、权限​

文件：文件存储在业务系统，每个文件都需要有一个文件id。id的命名规则由业务系统决定，要求同一个文件同一个id，不同文件不同id（支持多版本的文件系统除外）。业务系统调用在线编辑/预览时，需要提供文件id。Filez文档中台根据文件id回调业务系统获取相应文件。

用户：Filez文档中台不需要同步业务系统的组织和用户。在线编辑和在线预览时，需要调用方（业务系统）提供当前用户信息。这些用户信息会记录在文档中台，并且体现在文件中，比如：修订记录，批注，协作记录中。

权限：只有业务系统知道某个用户在某一时刻是否可以在线编辑/预览某个文件。这些信息无需同步到文档中台。文档中台每次提供在线编辑/预览服务时，都会向业务系统询问当前用户是否有权限。

集成的方式​

文件、用户和权限信息都是在业务系统中。因此，每次业务系统请求在线编辑/预览时，Filez文档中台都需要从业务系统那获取文件、用户和权限信息。根据获取的方式不同，有不同的对接方式。

标准对接方式​

下面以Filez文档中台与三方集成完成后，API的调用过程来说明集成原理。

  1. 用户在第三方服务的前端页面中需要使用文档编辑/预览服务时，按照以下url模式请求zOffice编辑页面。

http(s)://${zOffice_domain}/docs/app/${app_id}/${docId}/${action}/content

其中，zOffice_domain是zOffice server的域名，可以和第三方服务的域名相同。app_id是调用zOffice的第三方业务系统的id，由第三方业务系统决定，相关信息配置在zOffice系统中。docId是操作文档的Id。对于一个文档，其Id必须在第三方系统中是唯一的。对于编辑action的值是edit，对于预览action的值是view。

  1. zOffice server收到文档编辑或者预览的请求。首先需要验证这个请求。zOffice会带着第三方服务传来的token向第三方服务发送profiles请求（获取当前用户信息）。如果能得到正确的返回，则验证通过，同时获取当前用户信息。

  2. 验证通过后，zOffice server 向第三方服务发送获取文档meta的请求。该请求的返回json 中包含文件名、大小等信息，以及当前用户对该文件的权限信息。根据返回判断该用户能否编辑/预览这个文件。

  3. 如果用户有权访问这个文件，zOffice server向第三方服务请求下载这个文件。

  4. 获取文件后，zOffice会处理文件，并把处理后的内容返回给前端。这时用户可以编辑/预览文档了。

基本回调API​

zOffice回调业务系统的API，以约定好的path来回调。相关API约定如下

名称方法API描述
获取文件内容GET/{context}/{docId}/content获取docId指定的文档内容，docId是文档在第三方服务中的ID。返回一个可下载的文件。
获取文件元数据GET/{context}/{docId}/meta获取docId指定的文档元数据，docId是文档在第三方服务中的ID。以json形式返回。
存储文件内容POST/{context}/{docId}/content上传docId指定的文档，docId是文档在第三方服务中的ID。以json形式返回该文档的最新meta信息。
当前用户信息GET/{context}/profiles返回当前用户的详细信息

其中，{context}，是业务系统提供回调API的域名和path前缀。比如: context设置为

http://my.integration.com/zoffice/files (注意: 这个url没有最后的'/')。zOffice 发出的get content API(docId = 12168237) ，即业务系统实现的文件下载回调API是：GET http://my.integration.com/zoffice/files/12168237/content

前端集成方式​

 

  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指定处下载文件。

前端SDK集成方式​

适用版本

Filez文档中台从v8.1 开始支持前端SDK集成方式

 

  1. Filez文档中台和业务系统需要约定一个secret用来计算请求参数的token
  2. 业务系统前端需要调用在线编辑/预览服务时，请求业务系统的服务端。由业务系统的服务端根据打开的文档和用户生成初始化配置，使用secret生成token
  3. 业务系统前端使用初始化配置和token调用文档中台的JSSDK API访问文档中台的在线编辑/预览服务
  4. 文档中台JSSDK会创建iframe，然后访问文档中台的在线编辑/预览服务，并传递初始化配置和token
  5. Filez文档中台server收到请求后，做必要的验证，比如token是否有效，token是否过期，回调地址是否正确等
  6. Filez文档中台从userinfo 和meta等参数中获取相关信息，从downloadUrl指定处下载文件。
  7. 文档中台将包含文档内容的页面返回给iframe。这时用户可以编辑/预览文档了。

集成方式选择​

  1. 如果仅仅集成文档中台的在线预览能力，推荐客户使用前端集成方式。原因是集成方式比较简单，快速，同时能利用业务系统已有的文件下载接口。

  2. 如果习惯开发服务端API的业务系统，可以采用标准集成方式。该方式要求业务系统通过服务端回调方式返回重要信息，比如：userinfo, meta等。

  3. 前端集成方式的在线编辑/预览请求url中包含时间戳。Filez文档中台服务根据时间戳确保请求地址的时效性。以防止请求地址被传播。为了保证时间戳的有效性，要求业务系统只能在服务端产生时间戳。同时需要保证业务系统服务端的时间和文档中台服务端的时间严格一致（误差小于1秒）。

  4. 前端JSSDK集成方式，重要的信息不会在请求url上传递。这样可以防止请求地址被传播。并且主要的集成能力都是通过JSSDK来实现。但是它要求必须在业务系统的页面中以iframe的形式嵌入在线编辑或者预览页面。

最后于 更新