轻易云 QueryStrategyData 接口权威指南——跨方案查询执行队列数据的字段手册与实战教程

这个接口解决什么问题

在轻易云集成平台里,一个业务域往往由多个方案串联而成,例如销售订单场景中常见的「发货单=>销售出库单」「退换货订单=>销售退货单」等。当下游方案需要根据上游方案的执行队列状态决定是否立即触发、或需要把上游「队列中」的记录复位为「待处理」以重新调度时,就要用到 QueryStrategyData 这个查询型接口。它解决的是跨方案调度编排问题,常用于级联调度、失败重试、队列状态同步等集成平台内部运维场景,让上下游方案之间形成可控、可重放的数据链路。

接口能力总览

• 认证方式:基于轻易云平台内部认证,调用方需在平台中持有目标方案的访问权限。
• 请求结构:POST 调用 QueryStrategyData,核心入参包括 strategy_id(方案ID)、status(单值或逗号拼接多值,如 "5" 或 "5,4")、created_at_begin/end、response_at_begin/end、id、number、page、pageSize、projection、lastId。
• 响应结构:response.rows[] 数组,每行对应一条队列记录,平台内部字段由 _autoFillResponse 自动填充。
• 分页与增量:支持传统 page/pageSize 翻页,也支持 lastId 游标式增量;按时间范围过滤时,务必使用 10 位 Unix 时间戳。

典型字段映射

在轻易云上如何配置

在轻易云集成平台里,该接口已被封装为「查询另一方案数据」类型的源端组件,选择 QueryStrategyData 适配器即可使用。配置步骤通常为:填写目标 strategy_id → 设置 status 默认值(常用 5)→ 配置时间窗口与分页参数 → 在「字段映射器」中勾选需要下发的列(_id、F_status、F_created_at、F_response_at 等)→ 在 Target 端选择「写入空操作」,把真正的业务逻辑交给 AfterSourceInvoke 脚本:遍历 rows → 调 updateMany 把目标方案数据存储里的对应记录状态置为 AWAIT;若 rows 为空,则触发目标方案的立即调度。最后用 crontab(如 3 8 * * *)控制每天的执行节拍。轻易云的字段映射器会自动把 _id 之外的平台内部字段隐藏,避免误映射。

跨方案实战要点

1. 默认 status 一定要显式写出来:5(队列中)是最常用的过滤值,但线上常出现「忘了传 status 导致拉到全量已完成记录」的翻车,稳妥做法是把它固化在适配器默认值里。
2. 多状态查询用逗号拼接:平台支持 "5,4" 这种字符串语法,如果目标方案同时需要重试队列中和未审核的记录,直接用多值过滤比跑两次查询更省。
3. _id 才是真正的批量更新锚点:primaryWriteback 看起来像主键,实际只是回写标识;真正做 updateMany 时必须用 _id,否则会出现命中不到记录的情况。
4. 时间窗口比 created_at 优先选 response_at:跨方案调度更关心「最近一次处理时间」,按 response_at 窗口过滤比 created_at 更贴近业务真实状态。
5. 空结果不是异常,反而是触发器:rows 为空时无需报错,直接作为「无待处理数据」的信号,转而触发目标方案立即调度即可。
6. F_respone 是 object 而不是 string:在映射器里要按嵌套结构识别,否则会被序列化成字符串塞进下游,造成脏数据。

踩坑复盘

• 坑 1:status 不传导致全表扫。表现是定时任务一跑就拉几十万条已完成记录,目标库被写爆。修法:在轻易云适配器层把 status 默认值写死为 5,并加上必填校验。
• 坑 2:用 primaryWriteback 当主键去 update。表现是脚本里 updateMany 永远命中 0 条。修法:统一改用 $row->_id,并在代码里加注释固化约定。
• 坑 3:时间戳少写或多写一位。F_created_at 是 10 位 Unix 时间戳,若误传 13 位毫秒值,过滤结果会全为空或全命中。修法:在请求前用 Math.floor(Date.now()/1000) 统一规整。
• 坑 4:F_respone 被当成字符串下发。表现是下游解析报错、字段值带转义符。修法:在轻易云字段映射器里把它标记为 object 类型,只在调试通道输出,业务通道不勾选。
• 坑 5:跨方案没设依赖却忘了加节流。表现是上下游同时高频触发,目标方案库压力飙升。修法:在 crontab 上错峰(如上游 3:08、下游 3:10),并在脚本里加并发锁。

何时选用

该接口适用于同一业务域内多方案串联、需要按上游队列状态驱动下游调度的场景,典型如销售订单域的级联同步、失败重试、跨方案状态复位等。边界在于:它只服务于轻易云平台内部编排,不直接对接外部业务系统;若上下游属于不同业务域、需要的是业务数据本身而非队列状态,应改用对应业务系统的业务查询接口(如管易云的奇门接口、金蝶云星空的业务单据查询接口)。