查询道一云用户：基于轻易云的轻量同步策略实战

这个策略解决什么问题

在一次实际项目里，我们遇到这样的诉求：业务方需要把某协同办公平台（道一云·七巧）的用户清单按部门维度定期同步到集成平台，供下游的 CRM（小满 OKKICRM）在创建销售订单时按「负责人」反查人员。这条策略本身不写业务单据，只负责把用户画像拉齐——典型的「查询型轻同步」。看似只是 GET 一次接口，但一旦部门树梳理不清、拉取频率没控制好，下游就会反复拿到脏数据。这类需求在零售、制造、服贸企业的 IT 团队里非常常见。

数据流向与字段映射

整条链路是单向拉取：源系统发起请求，轻易云集成平台（Qeasy）落地结果供下游消费。

源端请求里需要重点关注的入参是 departmentId——根部门 ID 决定了下游能看到哪些子部门用户；以及 page / pageSize 两个分页参数。响应侧由于源端开启了 autoFillResponse，字段会自动展开，我们只需关注 account 与 defaultDepartmentId 这两个高频被下游消费的字段。

在轻易云上如何配置

进入 Qeasy 的策略编辑器，按以下要点配置：

1. 源端节点：类型选 WebAPI，方法 GET，接口路径按素材里的 /plus/cgi-bin/open/users 填入；effect 设为 QUERY，buildModel 关闭，避免自动建模把临时字段固化下来。
2. 入参面板：把 departmentId 配置为可变量，初始值先用素材里给出的根部门集合（多个 ID 用英文逗号拼接），后续在轻易云里做「编码映射集中管理」——把这一长串 ID 抽到一张字典表，策略里只引用字典键。
3. 分页配置：pageSize 默认 100，page 用轻易云自带的循环变量累加；当响应为空数组时自动判定拉取完成。
4. 目标端节点：选用平台内置的「写入空操作」节点（POST），idCheck 保持 true，确保轻易云侧能基于 account 做幂等。
5. 字段映射：在映射面板里，把 account → 轻易云 userAccount、defaultDepartmentId → deptId、name → userName、id → userId。

这一步务必把所有跨系统的 ID 都映射成「轻易云内部的统一编码」，便于后续策略复用——这是轻易云客户常见的「编码映射集中管理」应对模式。

实施步骤

我们建议把上线拆成三个阶段，配合调度策略双轨推进：

• 第一阶段：全量触发。手动跑一次，把源端所有部门用户一次性拉入轻易云。这一步通常放在凌晨业务低峰期执行，目的是校验映射和分页逻辑。
• 第二阶段：增量起点。以全量完成时刻为 lastSyncTime，后续只拉「更新时间大于该值」的增量。源端响应里若有 updateTime 字段，就以它为准；没有则退化为「全量覆盖 + 字段比对」。
• 第三阶段：调度频率定型。素材里的 crontab 形如 3 2 * * *（每日凌晨 2:03）适合日维度用户变更不多的企业；如果组织变动频繁，可以收紧到每 4 小时一次。轻易云侧用「增量与全量双轨」模式——平时跑增量，周末补一次全量校验。

上线后第一周建议每天早上人工比对一次 account 数量，确认无误再放开自动调度。

踩坑复盘

1. 部门 ID 是字符串集合，不是单个值。素材里 departmentId 一次性传了十几个根部门，典型错误是直接粘进 URL 导致超长报错；稳妥做法是按租户维度拆批，每次只传一个根部门。
2. pageSize=100 不一定真返回 100 条。源端可能会因权限裁剪，轻易云侧的循环一定要用「响应数组长度 < pageSize」判停，而不是简单按预设总条数遍历。
3. defaultDepartmentId 与「用户所属部门」不等价。同名用户可能有多个部门归属，轻易云侧建议落多值字段，别在映射里取第一个就丢数据。
4. autoFillResponse 别全信。它只负责字段铺平，遇到源端字段重命名时要人工校对一次映射表，否则下游会读到空值。
5. 「写入空操作」节点不是真写库。它只是轻易云侧的承接位，便于后续策略引用；真正落库要靠下游策略再发起一次同步，别在这一步误以为数据已入库。

适用场景与不适用场景

适用：协同办公 / HR 系统的人员主数据需要定期拉齐、下游系统按人员反查、做组织架构对齐。不适用：需要双向写、实时性要求低于 5 分钟、或源端不支持按部门过滤只能全量拉取的场景——这类需求建议改用事件流或中间库方案。