把飞书的组织架构同步到 EntVerse。
按下面 4 步顺序操作:先填凭证连通数据源 → 再定映射规则 → 然后预览无误后正式同步 → 最后查看同步结果。每一步顶部都标注了前提条件,未满足会灰显不可用。
1
数据源配置(飞书)
填入飞书自建应用的凭证,建立 EntVerse 与飞书通讯录的连接。
📋 获取飞书 App ID / App Secret 的操作步骤
2. 复制 App ID 和 App Secret
进入应用 →「凭证与基础信息」页面,能看到 App ID(cli_ 开头)和 App Secret(一串字符)。点"显示"可看 Secret,复制粘贴到本页对应输入框。
3. 开通通讯录权限(关键,不开通拉不到数据,会报 Access denied)
进入「权限管理」→「应用身份权限」,搜索并开通以下权限(按飞书后台显示的
中文名搜索):
获取用户基本信息 (用户姓名 name,必开)
获取部门基础信息 (部门列表,必开)
获取用户的基本信息 (补充基础字段,建议开)
查看成员工号 (工号 employee_no)
获取用户手机号 (手机号 mobile,可用作登录名)
获取用户的邮箱 (邮箱 email,如有此项则开)
💡 搜索框输中文权限名(如「获取用户基本信息」),不要输 scope 标识符。
权限开通后要创建新版本并发布才生效。
⚠️ 如果测试连接报「Access denied」「没有部门访问权限」等错误,说明权限没开或没生效:
① 检查上面权限是否都已开通;② 权限管理 → 通讯录权限范围设为「全部成员」;
③ 创建新版本并发布(权限变更后必须重新发布才生效)。
4. 发布应用并审批
「版本管理与发布」→ 创建版本 → 提交发布 → 飞书管理员审批通过后才能调通 API。
5. 配置可用范围
「应用能力」→「通讯录」→ 把"可用范围"设为全部成员(或至少包含要同步的部门),否则只能拉到部分人。
💡 填完凭证后点「测试连接」,成功才说明 1-5 步都配对了。失败会显示飞书返回的具体原因(如权限不足、应用未发布等)。
2
映射规则
定义"飞书的什么 → EntVerse 的什么"。按优先级匹配,第一个命中即用。三种类型:职位→权限、职位→角色、部门→OU。
前提条件:第 1 步已保存凭证且测试连接通过。(不连通飞书也能先建规则,但建议先连通确认职位/部门名长什么样)
3
执行同步
先「预览」看影响范围(不落库),确认无误再「正式同步」。正式同步会新建/更新用户与 OU,并禁用已离职用户。
前提条件:第 1 步已连通飞书 + 第 2 步至少检查过映射规则。规则可以为空(会用默认值:权限 employee、组织职级按职位推导、OU 按部门名自动建),但建议至少配几条规则把核心职位对上权限级别与组织职级。
4
同步结果与缓存
查看最近一次同步状态,以及从飞书拉取的原始数据缓存(中间态,应用规则后才会写入业务表)。
前提条件:已执行过至少一次「预览」或「正式同步」(第 3 步)。缓存是同步过程中产生的,没同步过则缓存为空。