飞书人员主数据同步方案实战：从飞书拉取人员到轻易云数据中枢
这个策略解决什么问题
飞书人员主数据需要稳定落库并对外提供联查能力。一次实际项目中,我们发现客户最头疼的不是把人员写进 ERP,而是怎么让采购订单、销售订单、报销单这些下游业务单据在「经办人」字段上稳定地拿到飞书人员 ID,再映射到金蝶云星辰职员编码。这条策略的核心正是:从飞书按部门递归拉取人员,写入轻易云数据集成平台的数据集线器,供下游策略通过 _findCollection 或 _mongoQuery 联查。
数据流向与字段映射
数据流向:飞书 → 轻易云集成平台数据中枢(集线器)。
源端调用 /open-apis/contact/v3/users/find_by_department 接口,按部门递归拉取人员;目标端为「写入空操作」,源端响应按 1:1 直接落库至集线器。
| 关键字段 | 源端(飞书) | 目标端(集线器) | 映射类型 | 说明 |
|---|---|---|---|---|
| user_id | user_id | content.user_id | DIRECT | metadata.id,飞书企业内唯一 |
| union_id | union_id | content.union_id | DIRECT | 跨应用唯一,推荐用于跨系统映射 |
| name | name | content.name | DIRECT | metadata.number,显示姓名 |
| employee_no | employee_no | content.employee_no | DIRECT | 工号,常用于与金蝶职员编码对照 |
| content.email | DIRECT | 个人邮箱 | ||
| mobile | mobile | content.mobile | DIRECT | 手机号 |
| job_title | job_title | content.job_title | DIRECT | 职位 |
| status | status | content.status | DIRECT | 账号状态对象 |
| kd_number | {{name}} | content.kd_number | TRANSFORM | 扩展字段,为金蝶职员编码预留 |
其余字段(avatar、city、country、gender、join_time、open_id、work_station、enterprise_email 等)均按 DIRECT 原样落库。
在轻易云上如何配置
在轻易云数据集成平台上,这条策略的配置有几个典型要点:
Source 配置:api 选 /open-apis/contact/v3/users/find_by_department,effect 选 QUERY,method GET,id 字段取 user_id,number 字段取 name,idCheck 设为 true。请求参数中 department_id=0(从根部门开始)、page_size=50、user_id_type=union_id,dep_strategy 关联「获取飞书部门-OK」策略 ID,平台会自动递归拉取子部门人员。分页 key 配 has_more,数据路径 data.items。
Target 配置:api 选「写入空操作」,effect EXECUTE,request 和 response 都留空。这是轻易云一个很巧妙的机制——目标端不调外部接口,数据直接落库到平台集线器,按 strategy_id 持久化,供其他策略联查。
调度配置:Source 端 crontab 设为 3 2 * * *(每日凌晨 2:03 执行),Target 端 crontab 设为 1 1 1 1 1(占位,不实际触发)。
kd_number 扩展字段:默认取 {{name}},但生产环境一般会改成 _findCollection 从金蝶云星辰职员同步方案的集线器联查,或者用编码表做 COLLECTION 映射,把飞书 user_id/employee_no 稳定映射到星辰职员编码。
实施步骤
第一步:确认部门策略先就绪。「获取飞书人员」强依赖「获取飞书部门-OK」,因为递归人员拉取需要部门 ID 列表。先确认部门策略已稳定运行,集线器里有完整部门树。
第二步:配置并测试单部门拉取。先把 department_id 改成一个具体部门 ID(非 0),dep_strategy 留空,跑一次确认单部门人员拉取正常。这一步容易翻车的地方是飞书 App 的 contacts 权限范围——如果应用只授权了部分部门,根部门 0 拉出来是空的。
第三步:切换到根部门递归模式。把 department_id 改回 0,填入 dep_strategy 关联部门策略 ID,跑全量。观察分页是否走完(has_more 是否正确翻页),集线器落库条数与飞书后台人员数是否一致。
第四步:配置下游联查策略。在采购订单、销售订单等下游策略的人员字段上,用 _findCollection 从本策略集线器按 user_id 或 employee_no 查询,再映射到金蝶云星辰职员编码。
第五步:调度上线与监控告警。crontab 设为每日凌晨 2:03,错开下游业务单据同步窗口。配置集线器落库条数监控和接口成功率告警。
踩坑复盘
踩坑一:权限范围不全。飞书应用的 contacts 权限如果只勾选了部分部门,根部门 0 拉取会返回空数组。稳妥的做法是先在飞书开放平台确认应用可见范围,或者用具体部门 ID 逐个验证。
踩坑二:user_id_type 选错。如果选 open_id,则同一用户在不同应用下 open_id 不同,做跨应用映射会出问题。推荐用 union_id,跨应用唯一,便于和金蝶建立稳定映射关系。
踩坑三:kd_number 直接用 name 映射。生产环境用 {{name}} 作为金蝶职员标识,3 个月后出现重名或人事变动时就会对不上。稳妥的做法是把 kd_number 改为 _findCollection 联查金蝶云星辰职员方案,或维护一张编码映射表做 COLLECTION 映射。
踩坑四:部门策略未先跑就拉人员。部门集线器还没数据时,dep_strategy 递归会拿不到子部门列表,人员拉取不全。实施时务必让部门策略先稳定运行至少一个调度周期。
踩坑五:分页未走完就提前结束。has_more 为 true 时必须继续翻页,否则会丢数据。轻易云平台会自动处理,但人工验证时要确认总条数与飞书后台一致。
适用场景与不适用场景
适用场景:基础资料主数据缓存、跨系统人员编码映射(飞书 ↔ 金蝶职员)、下游业务单据的经办人/审批人字段联查、组织架构同步前的数据准备。
不适用场景:需要实时获取人员变更通知的场景(应改用飞书事件订阅)、需要写入外部业务系统的场景(本策略目标为空操作,不会调外部接口)、部门层级极深且递归性能不可接受的场景(应改为按业务线分批拉取)。