← 返回首页深度篇
深度篇 · Enterprise · 企业版后台使用说明 > 账号管理

飞书组织架构一键同步:数据源配置全步骤

Enterprise | 更新于 2026-10-18

本篇涵盖的知识重点

配置路径一览

1 创建飞书企业自建应用并取凭证 2 为应用开通全部指定权限 3 按需配置应用权限范围并发布版本 4 在控制台添加飞书数据源并绑定凭证 5 配置字段映射并开启定时器 6 执行同步并查看同步记录
共 6 步,按编号顺序阅读

飞书侧与后台侧分步解读

1创建飞书企业自建应用并取凭证

作用数据源的连通依赖应用身份,APP ID 与 APP Secret 是控制台侧绑定的必需项。

操作登录飞书开放平台,单击开发者后台,在飞书开发者后台单击「创建企业自建应用」,在弹出的弹窗中填写必要信息后单击创建,进入新创建应用的详情页。在应用详情页左侧菜单栏找到「凭证与基础信息」,在应用凭证模块中获取 APP ID 和 APP Secret,复制并妥善记录。若已有稳定可用的已发布应用,也可直接选用。

注意APP Secret 等同于账号钥匙,不要贴在工单、群聊或共享文档中。

飞书开发者后台创建企业自建应用
图:登录飞书开放平台,在开发者后台创建企业自建应用
应用凭证与基础信息中的 APP ID 和 APP Secret
图:在「凭证与基础信息」中获取 APP ID 与 APP Secret
2为应用开通全部指定权限

作用权限缺失会直接导致字段拉不到数据,是同步失败最常见的原因。

操作在应用详情页左侧菜单栏找到「权限管理」,单击开通权限,或单击批量导入/导出权限。通过逐一搜索权限名称(建议用 Code 搜索)为应用开通全部 12 个权限点,配置完成后回到权限管理页面确认全部开通。

注意考虑到飞书侧可能随时更新权限名称,建议优先使用 Code 搜索;这些权限需要全部开通,漏一个就会在映射时出现字段缺失。

必须开通的 12 个权限点
  • 获取通讯录基本信息(contact:contact.base:readonly):读取通讯录的底座权限,不开通后续部门与人员都拉不到。
  • 获取部门基础信息(contact:department.base:readonly):拉取部门名称等基础字段,部门树缺它就不完整。
  • 获取通讯录部门组织架构信息(contact:department.organize:readonly):拉取部门上下级关系,决定同步后的层级是否正确。
  • 获取用户基本信息(contact:user.base:readonly):拉取人员基础字段,是人员同步的前置权限。
  • 获取用户组织架构信息(contact:user.department:readonly):确定人员归属哪个部门,缺失会导致人员无部门。
  • 获取用户 user ID(contact:user.employee_id:readonly):拿 user_id 做唯一标识,缺失会影响映射与去重。
  • 获取用户手机号(contact:user.phone:readonly):人员字段三选一之一,需要用手机号作为登录名时必开。
  • 获取用户邮箱信息(contact:user.email:readonly):人员字段三选一之一,需要用邮箱作为登录名时必开。
  • 获取用户受雇信息(contact:user.employee:readonly):拉取在职状态等雇佣信息,用于判断人员是否有效。
  • 获取企业内全部应用的信息(admin:app.info:readonly):读取企业内应用清单,用于识别应用可用性。
  • 管理应用自身资源(application:application:self_manage):让应用能管理自身资源,是发布与运行的基础。
  • 获取企业信息(tenant:tenant:readonly):读取企业租户信息,用于确认当前企业身份。
两种开通方式怎么选
  • 方式一 手动添加:逐一搜索权限名称开通;因飞书侧可能随时更新权限名称,建议优先用 Code 搜索,避免名称对不上。
  • 方式二 批量导入:在权限管理页单击批量导入/导出权限,粘贴含 tenant 级 scopes 的 JSON 一次性导入,user 数组留空。
  • 无论用哪种方式,配置完成后都要回到权限管理页面复核,确保 12 个权限点全部处于已开通状态。
权限管理页面开通权限点
图:在权限管理中逐项开通所需权限,建议优先用 Code 搜索
3按需配置应用权限范围并发布版本

作用同步范围要在飞书侧收口,且所有配置必须经发布才会真正生效。

操作若只需同步部分成员数据,开通权限后在权限管理页面单击配置,进入可访问的数据范围页面再次单击配置,按需选择数据范围并保存。随后在应用详情页左侧菜单栏找到「版本管理与发布」,单击创建版本,填写版本号与更新说明并保存,再单击确认发布。常规发布由飞书自动审核,部分场景会进入手动审核,需在飞书管理后台的工作台 > 应用审核中通过审核。

注意配置完成后一定要发布,否则以上配置不会生效;控制台侧暂不支持设置部门或人员范围,范围要在这一步完成。

发布环节的三个检查点
  • 创建版本:在「版本管理与发布」中单击创建版本,填写版本号与更新说明并保存,再单击确认发布。
  • 审核:常规发布由飞书自动审核;部分场景会进入手动审核,需到飞书管理后台的 工作台 > 应用审核 中通过。
  • 确认状态:回到版本发布页面检查当前版本审核状态,确定为「已发布」才算真正生效。
版本管理与发布页面
图:填写版本号与更新说明后创建版本并确认发布
4在控制台添加飞书数据源并绑定凭证

作用这是把飞书侧准备好的应用接入企业控制台的关键一步。

操作在 企业管理后台 > 组织与成员 > 数据源管理 中单击添加数据源,跳转数据源选择页面后选择飞书数据源。若数据源已绑定飞书应用凭证,可直接引用已有凭证;若未绑定或已绑定中没有想要的凭证,可自行输入上一步获取的 APP ID 和 APP Secret。若飞书为私有化部署,需填写正确的私有化域名地址,非私有化部署则忽略此项。

注意私有化域名地址非必填,只在私有化部署场景下使用;填错会导致连通失败。

控制台侧飞书数据源凭证绑定
图:在数据源管理中选择飞书数据源并绑定 APP ID 与 APP Secret
5配置字段映射并开启定时器

作用映射决定同步后数据的可用性,定时器决定架构变更能否自动跟进。

操作在数据源功能详情配置中完成字段映射:部门字段对应关系固定不可修改;人员字段中姓名为企业控制台侧固有字段,必须设置对应关系,邮箱、手机号、登录名为三选一必填字段,至少有一个对应关系存在才可正常保存。随后按需开启定时器(默认关闭),设置同步周期,最后单击保存按钮保存页面全局改动。

注意使用自定义脚本时可先用映射配置数据测试验证;若测试提示字段缺失,通常是飞书侧应用未开通对应字段权限。

字段映射与可选能力
  • 部门字段:对应关系固定,不可修改,只能按平台约定同步。
  • 人员字段:姓名为企业控制台侧固有字段,必须设置对应关系;邮箱 / 手机号 / 登录名为三选一必填,至少有一个对应关系存在才可正常保存。
  • 自定义脚本:飞书侧下拉选框仅提供基础字段,需要的字段不在其中时,可选择「自定义脚本」并在弹窗中输入自定义字段或脚本。
  • 映射配置数据测试:调试功能按钮,单击后可用模拟数据或搜索真实人员数据,查看当前映射关系下同步后的数据形式。
6执行同步并查看同步记录

作用同步结果要落到可核对的记录上,才能判断这次是成功了还是悄悄没跑。

操作详情配置完成后单击「手动同步」按钮执行一次导入和同步;若已开启定时器,也可等定时器触发自动同步。同步任务完成后在同步记录列表中查看结果,单击进入结果详情页:右侧为整体情况概览,左侧可查看人员或部门的具体变更记录并筛选。

注意本页面只记录变更记录,若本次同步无变更内容不会留下记录;一个部门或人员因操作内容不同会产生多条记录,请注意查看备注中的操作行为。

同步与查看的三条要点
  • 手动同步:详情配置未完成时按钮不可单击;定时器默认关闭,开启后可按设定周期自动触发。
  • 结果详情页右侧:整体情况概览,包含人员与部门的成功变更条数及失败记录条数。
  • 结果详情页左侧:可选择查看人员或部门的具体变更记录,并通过筛选条件筛选;同一部门或人员因操作内容不同会产生多条记录,需查看备注中的操作行为。
同步记录列表与结果详情页
图:同步完成后查看同步记录,可下钻查看人员与部门的变更明细

发布、映射与同步提示

练手任务

任务1:生成一份可直接批量导入的飞书权限配置说明
提示词(点右上角「复制」,可直接发给 WorkBuddy)
```markdown
我要为飞书自建应用配置数据源同步所需的权限,请帮我产出一份操作说明。
必须包含的权限点(Code 请原样保留,不要增删):contact:contact.base:readonly、contact:department.base:readonly、contact:department.organize:readonly、contact:user.base:readonly、contact:user.department:readonly、contact:user.employee_id:readonly、contact:user.phone:readonly、contact:user.email:readonly、contact:user.employee:readonly、admin:app.info:readonly、application:application:self_manage、tenant:tenant:readonly。
必须包含的事实:
- 入口为应用详情页左侧菜单栏的「权限管理」,可单击开通权限,也可单击批量导入导出权限;
- 考虑到飞书侧可能随时更新权限名称,建议优先使用 Code 搜索;
- 这些权限需要全部开通;
- 配置完成后必须创建版本并发布,否则配置不生效。
请输出:
1. 一段可直接复制使用的批量导入 JSON(包含上述 12 个 tenant 级权限,user 数组为空);
2. 一张「权限 Code / 对应权限名称 / 不开通会怎样」的对照表,其中「不开通会怎样」只写可推断的后果,不确定的写「以飞书侧实际表现为准」;
3. 一段发布前的自检清单(不超过 150 字)。
```
预期结果

得到一段可粘贴的批量导入 JSON、一张权限对照表和一段发布前自检清单,12 个权限 Code 完整无误。

任务2:设计飞书字段映射方案并写自定义脚本
提示词(点右上角「复制」,可直接发给 WorkBuddy)
```markdown
我要配置飞书数据源的字段映射,请帮我设计方案。
已知规则(请严格按此设计):
- 部门字段对应关系固定,不可修改;
- 人员字段中,姓名为企业控制台侧固有字段,必须设置对应关系;邮箱、手机号、登录名为三选一必填字段,至少有一个对应关系存在才可正常保存;
- 飞书侧字段下拉选框仅提供基础字段,若需要的字段不在下拉框中,可选择「自定义脚本」,在弹窗中输入自定义字段或脚本;
- 「映射配置数据测试」按钮为调试功能,单击后可使用模拟数据或搜索真实人员数据,查看当前映射关系下同步后的数据形式;
- 若测试提示「字段缺失」,通常是因为飞书侧应用创建时未开通对应字段权限。
请输出:
1. 一张基础字段映射表(控制台字段 / 是否必填 / 飞书侧来源字段 / 备注);
2. 两个自定义脚本示例:一个用于拼接「部门-职位」作为展示字段,一个用于把入职日期格式化为 YYYY-MM-DD。脚本用伪代码表达即可,并注明这是示例,需在弹窗中按实际字段名调整;
3. 一段「字段缺失」的三步排查流程。
```
预期结果

得到字段映射表、两个带免责说明的自定义脚本示例和三步排查流程,必填规则表述准确。

任务3:制定同步监控与异常处置方案
提示词(点右上角「复制」,可直接发给 WorkBuddy)
```markdown
我的飞书数据源已经配置完成并开启定时器,请帮我制定同步监控与异常处置方案。
已知事实(请严格按此设计,不要新增功能):
- 定时器默认关闭,关闭时可通过手动单击「手动同步」按钮同步;开启后可按设定周期定时触发;详情配置未完成时手动同步按钮不可单击;
- 同步记录列表可进入结果详情页:右侧为整体情况概览,包含人员与部门的成功变更条数及失败记录条数;左侧可查看人员或部门的具体变更记录,并可通过筛选条件筛选;
- 本页只记录变更记录,若本次同步无变更内容将不会记录;一个部门或人员因操作内容不同会产生多条记录,需查看备注中的操作行为;
- 更换数据源会清空原有数据源的所有配置和同步记录,已同步至控制台侧的人员保留;若只是更换应用凭证而非数据源类型,可修改凭证操作。
请输出:
1. 一份定时器配置建议(什么规模适合什么频率,并说明为什么默认关闭时不建议长期依赖手动同步);
2. 一张「异常现象—可能原因—处置动作」对照表,至少覆盖:同步记录为空、失败条数大于 0、同一人员多条记录、手动同步按钮点不动;
3. 一段月度巡检清单(不超过 150 字)。
```
预期结果

得到定时器配置建议、异常对照表和巡检清单,能正确解释「无变更不留记录」与「按钮不可点」的原因。

参考文档:飞书集成(WorkBuddy 官方文档)
本文基于官方文档再创作,具体以官方文档站实际展示为准。