飞书用户同步
飞书用户同步读取企业自建应用有权访问的通讯录，把部门、成员资料和部门关系写入千问办公。配置前先检查应用发布状态和数据访问范围，这两项经常决定哪些成员能够被读取。
一次性申请清单
在「权限管理」中开通以下应用身份读取权限，并设置可访问的数据范围。下表按部门、成员及当前映射字段拆分，便于一次提交申请。
| 权限名称 | 权限代码 | 何时需要 |
|---|---|---|
| 获取通讯录基本信息 | contact:contact.base:readonly | 读取通讯录基础信息 |
| 获取部门基础信息 | contact:department.base:readonly | 部门标识和名称 |
| 获取部门组织架构信息 | contact:department.organize:readonly | 部门层级与上级关系 |
| 获取用户基本信息 | contact:user.base:readonly | 用户标识和姓名 |
| 获取用户组织架构信息 | contact:user.department:readonly | 成员所属部门 |
| 获取用户邮箱信息 | contact:user.email:readonly | 需要将邮箱同步到千问办公时申请 |
| 获取用户手机号 | contact:user.phone:readonly | 需要将手机号同步到千问办公时申请 |
| 获取用户受雇信息 | contact:user.employee:readonly | 需要将工号或在职状态同步到千问办公时申请 |
| 获取用户 user ID | contact:user.employee_id:readonly | 需要使用飞书 user_id 作为千问办公的三方 ID 等身份字段时申请 |
请一次准备好以下信息：
- 企业与应用：企业名称、应用名称、App ID、App Secret。
- 权限与发布：权限开通结果、已发布的应用版本。
- 访问范围：通讯录数据权限设置为全部成员，并确认应用可用范围。
- 核验资料：一名普通成员的
user_id，以及预期同步的成员资料。
若同一应用还用于 SSO，请同时核对飞书登录清单中的重定向配置和登录授权。
权限、通讯录数据范围和应用发布状态须同时生效。千问办公会从飞书根部门读取组织，因此通讯录数据权限必须选择「全部成员」。不要把应用可用范围当成通讯录数据权限，也不要只授权一个测试部门。
准备飞书应用
- 进入飞书开放平台的【开发者后台】，创建或打开企业自建应用。
- 打开「权限管理」，按权限代码搜索并申请：
contact:contact.base:readonly、contact:department.base:readonly、contact:department.organize:readonly、contact:user.base:readonly、contact:user.department:readonly。对应名称见上方清单。 - 若需要将飞书成员的邮箱同步到千问办公，则申请 获取用户邮箱信息（
contact:user.email:readonly）。 - 若需要将飞书成员的手机号同步到千问办公，则申请 获取用户手机号（
contact:user.phone:readonly）。 - 若需要将飞书成员的工号或在职状态同步到千问办公，则申请 获取用户受雇信息（
contact:user.employee:readonly）。 - 新建来源时，页面默认使用飞书
user_id作为千问办公的三方 ID，因此申请 获取用户 user ID（contact:user.employee_id:readonly）。成员请求固定按user_id读取，即使改选其他 ID，也不能省略该权限。 - 在「权限管理」中打开通讯录权限范围设置，选择「全部成员」并确认。当前实现从根部门读取，选择部分成员会造成组织和成员不完整。
- 进入应用版本设置，打开「可用范围配置」，选择「全部成员」或覆盖所有实际使用该应用的成员。这里控制谁能使用应用，与上一步的数据读取权限不同。
- 在「凭证与基础信息」记录 App ID 和 App Secret。
- 在
版本管理与发布 → 版本管理创建版本并发布。新增权限后，确认本次发布已包含这些权限。
千问办公从飞书读取通讯录。完成上述读取权限申请即可，无需申请通讯录写入权限。
建立飞书数据源
- 在千问办公进入
用户与体验 → 用户管理 → 用户同步，点击【新增数据源】。 - 选择「飞书」，点击【开始配置】，填写 App ID 和 App Secret。
- 点击【测试并下一步】。新建时，成功后保存当前配置草稿并进入映射设置；编辑已有数据源时，仍需完成最后一步保存。该测试只交换访问令牌，不读取部门或成员，也不能证明通讯录权限和字段已经正确。
核对飞书 ID 和部门关系
核对飞书字段及 ID 类型后保存。成员的来源字段可从飞书支持的字段中选择，右侧目标固定；部门映射通常使用预设来源。删除可选行后，可在【添加映射】下拉重新选择目标，恢复对应的飞书预设字段。
| 配置页预设的来源字段 | 用途 |
|---|---|
user_id | 默认对应第三方用户 ID；应与飞书 SSO 的身份关联保持一致 |
name、email、mobile | 对应用户姓名、邮箱、手机号 |
employee_no、open_id | 分别默认对应工号、账号，按企业实际资料检查 |
department_id | 成员所属部门的第三方部门 ID |
部门 open_department_id、parent_department_id | 部门唯一标识和上级部门标识 |
检查成员返回的部门 ID 与部门列表使用的 ID 类型相同。飞书同时存在多种用户和部门 ID，不应仅因为字段名称相似就互换。邮箱默认读取 email。
必填映射确认后点击【下一步】。如果成员没有邮箱，先确认是否因权限导致；不要立即把空值当成成员未填写。
设置同步方式并核验结果
- 在「同步范围」选择「全部」或「指定部门及后代」，并设置「新用户默认申请席位」。这里是千问办公实际应用的范围，飞书平台仍须提供全部成员的通讯录数据权限。
- 选择“仅手动”；需要自动执行时，选择“定时同步”，再选“每天”并设置北京时间。通常先手动执行一次核对结果。
- 在「删除处理」中选择仅停用、停用并回收席位，或删除并回收席位。设置告警阈值与邮箱后保存。
- 在数据源列表启用飞书，点击【立即同步】。
- 打开这次同步记录的【详情】，检查用户数量、部门层级和席位变化，再到「用户」页面抽查一个跨部门成员。
- 在飞书修改一名核验成员的部门后再同步，确认更新的是原用户，没有新增重复账号。
维护与排障
- 只有部分部门导入： 对比飞书的通讯录数据范围、应用可用范围以及千问办公选择的范围。
- 部门关系错误： 检查
department_id与open_department_id的实际值是否对应，补齐上级部门。 - 应用发布后仍缺字段： 检查新版本包含的权限，以及相关权限的数据范围。
- 离职处理数量异常： 停用数据源并查看同步详情，先排除权限收缩或字段缺失，再继续同步。
更新 App Secret 时，编辑原数据源、重新测试并保存。同步开关只控制数据同步；飞书登录在飞书 SSO单独配置。
与已有用户衔接
同步前，先核对来源中的三方 ID 与已有用户一致。
- 匹配用户： 只通过三方 ID 查找。账号、邮箱、手机号和工号用于冲突校验；三方 ID 未命中，但其中任一值已被占用时，本条同步失败。
- 更新成功： 保留原 QID，并将当前维护来源设为这份数据源。
- 锁定资料： 来源开启期间，该来源用户的姓名、邮箱、账号、手机号、三方 ID、工号均不可手动修改；部门和状态按映射锁定。
- 删除后再出现： 不恢复旧 QID。系统按当前飞书资料创建新用户和新 QID，计为“创建”；旧历史保留，三方 ID 改为关联新用户。新用户不继承旧角色、密码、用户组、管理员权限、席位或部门，默认席位按当前数据源设置处理。
修改映射、切换来源和删除后新建的完整规则见用户同步。
返回：用户同步-概述