Skip to main content

如何对接按角色授权（protectRole）

文字文档从 v9.0 版本支持「按角色授权」能力：作者可将文档中某个段落/区域绑定到保护角色，只有持有对应角色的用户才能编辑该区域。角色的来源是第三方业务系统，Filez文档中台不做角色管理（增删改均由三方负责）。

三方系统需要完成以下三个对接步骤：

  1. 在管理控制台中勾选支持按角色授权
  2. 既有 meta 回调接口的响应中新增 protectRole 字段（标识当前编辑用户的保护角色）
  3. 实现新的保护角色列表回调 API（返回文档的全量保护角色）
  1. 在管理控制台中勾选按角色授权

需要在Filez文档中台管理控制台的应用管理中，针对当前 app 开启「按角色授权」能力。未开启时，编辑器不提供按角色授权功能，也不会调用相关回调接口。

  1. 在 meta 响应中携带 protectRole 字段
GET/context/{docId}/meta既有 APImeta 响应中新增 protectRole 字段：单个 JSON 对象 {id, name}，只支持 1 个 role，不是数组。表示当前在线编辑用户在该文档上的保护角色，可以随请求上下文变动。用户没有保护角色时不携带该字段或值为空。

说明：

  • 字段非法（非 {id, name} 对象、id 为空等）时会被忽略，等同于没有保护角色。
  1. 实现新的保护角色列表回调 API
GET/context/{docId}/protect-rolesNew API返回由 docId 指定的文档的保护角色列表。响应为 JSON 数组，每个元素为 {id, name}。

响应示例：

[
  { "id": "r-001", "name": "法务审核" },
  { "id": "r-002", "name": "部门编辑" }
]

回调接口的详细规范参见：获取保护角色列表API

注意：

  1. 对于已经实现了标准集成回调接口的业务系统，两个接口与别的回调 API 类似（认证、回调前缀等机制完全复用）。

  2. 对于采用前端集成方式的业务系统，首先需要确定回调前缀，再实现相关回调接口。

  3. protectRole / 角色列表反映的是三方的实时数据：三方删除或改名角色后，历史文档引用的旧角色会失效，需要三方自行评估影响。

Last updated on