钉钉消息明细查询与机器人通知策略实战教程

这个策略解决什么问题（场景与价值）

某制造企业的业务同步策略运行在公有云上，供应链人员需要及时知道哪些单据处理失败。如果只看到“策略异常”的汇总，值班人员仍要逐个系统排查；等业务方反馈，积压可能已经扩大。本策略连接轻易云集成平台的消息明细查询与钉钉机器人通知：先按策略名或单据编号查询异常明细，再把策略名称、租户信息、业务编号、响应时间、问题描述和响应内容送入通知流程。价值不在“发消息”本身，而在于形成可追踪、可分派、可复核的异常闭环。

数据流向与字段映射（源 → 中间层 → 目标）

该策略为两个 WebAPI 动作串联。第一段是查询动作，查询范围为最近 300 秒，可按策略名或记录编号筛选；第二段是执行动作，将查询结果组装为机器人通知。密钥类字段应配置在平台凭据或安全变量中，不应直接写入策略配置。

中间层负责固定查询窗口、校验必填参数、合并查询结果，并为通知模板准备上下文。目标侧按“策略—单据—时间—问题—详情”组织消息，使接收人能快速判断影响范围。

在轻易云上如何配置（给出典型配置要点，可读性好）

我们用轻易云数据集成平台承接查询与通知的串联，不让两段逻辑散落在脚本中。

第一步，在来源连接中配置第一段查询 API：请求方式为 POST，主标识按 strategy_name 或 number 传值，并开启重复校验。查询参数 recentSeconds 默认设为 300；ids 适用于一次查询多个明确编号，不建议与策略名同时作为互相冲突的主条件。响应模型映射 strategy_name、strategy_id、number、response_at、problem、response_content 等字段。

第二步，在目标连接中配置机器人明细执行 API。name 映射 strategy_name，lessee_name 映射租户名称，number、response_at、problem 和响应内容逐项对应。消息正文采用模板生成，建议将响应内容放在折叠或低优先级区域，避免一次异常产生过长消息。

第三步，启用轻易云数据集成平台的凭据引用和敏感字段保护。机器人访问凭据应由具备权限的管理员注入，配置中只保留变量引用。响应详情若含账号、内部地址或业务敏感字段，需要在中间层脱敏。客户现场常见的稳健模式有两种：一是把策略名与单据编号集中维护在编码映射区；二是把表头级告警先发出，再按需要发送完整响应内容。

实施步骤（分阶段调度：增量起点 / 全量触发 / 调度频率）

1. 增量起点。 先固定最近 300 秒作为查询窗口，确保新产生的错误能够进入通知链。若首次上线无法确认历史范围，可从较小窗口启动，再依据平台保存时间逐步扩大。

2. 全量触发。 全量不是把全部历史消息重复发送，而是一次性补查指定时间范围，并设置批次数或数量上限。补查前先验证编号格式、时间边界和消息去重键，避免同一异常重复告警。

3. 调度频率。 素材给出的业务时段为每日 9:00—21:00，查询与通知都按 5 分钟粒度执行，并错开分钟相位，避免整点同时触发。两段调度不应简单地完全一致；应给查询预留执行时间，并保留失败重试。

4. 上线验证。 先用可识别的测试策略或测试单据验证成功、无详情、超时和敏感内容四类场景，再切换正式通知。上线后观察消息延迟、重复率、接口返回和失败队列；必要时采用“增量与全量双轨”应对历史补查，但全量任务必须受窗口和批次约束。

踩坑复盘（3-5 条实战经验）

1. 把编号校验当成绝对可靠。 典型错误是只依赖前端校验，没有处理空格、大小写和特殊字符。稳妥做法是在平台中保留原始值，同时生成标准化值用于比对。
2. 查询窗口与调度频率脱节。 如果 5 分钟执行一次，却只查固定 60 秒，边界时段容易漏报。应按最近 300 秒查询，并允许时间重叠换取完整性。
3. 通知包含原始响应。 响应中可能出现内部信息。这里容易翻车；中间层必须做敏感字段检查、长度限制和截断提示。
4. 重试导致重复告警。 机器人已收到消息，但平台因超时无法确认时，重试可能再次发送。去重键建议由策略标识、编号、响应时间和规范化问题摘要组成。
5. 两段调度同相位。 查询尚未结束，通知任务就开始，会漏掉刚返回的记录。应错开调度时间，并设置依赖或合理等待窗口。

适用场景与不适用场景（150 字内，讲清边界）

适用于需要把集成异常、接口响应和业务编号及时推送给运维或业务团队的公有云场景，尤其适合值班监控和快速排障。不适合作为业务数据归档、复杂审批或大规模明细传输通道。高频日志分析应使用日志平台；只有需要触发告警、补充通知和形成可追踪闭环时，才应使用本策略。