← 完整教程目录离线阅读器与全文搜索

42|轮询与 webhook:怎样可靠等待生成结果

媒体生成通常比一次工具调用持续更久。可靠的等待方式要保存任务 ID,让等待进程可恢复,并把本地超时与服务端终态分开。本篇先提供能执行的轮询,再说明 webhook 在系统里的正确边界。

最小可执行等待

已有 Node 示例 run 目录与 ID 时,直接查询,不重新提交:

node examples/node/atlas-media.mjs get --run-dir tutorial-output/node-001
node examples/node/atlas-media.mjs wait --run-dir tutorial-output/node-001 --seconds 120

或者使用 CLI 的原 ID:

PREDICTION_ID='替换为真实已受理任务ID'
atlas generate get "$PREDICTION_ID" --json
atlas generate wait "$PREDICTION_ID" --timeout 10m --json

等待上限只限制本地进程。结束时仍在 processing,就记录“仍处理中”;不要转成生成失败,也不要新发一个请求当作延长等待。任务只有实际返回终态时才更新终态。

对已受理的 Atlas 任务实现可恢复等待。只查询原 ID,保留账户与任务关系,按有限间隔轮询并设置本地截止时间;401/403 或 ID 不一致时停止,不更换账号。超时记录 pending/unknown,不再次提交。

应用里的持久状态

至少保存业务任务 ID、Atlas ID、账户引用、请求摘要、上次检查时间、下一次检查时间和终态。工作进程从队列领取待查询项;同一任务的状态更新使用乐观锁或数据库事务,防止多个 worker 互相覆盖。

对 429、可恢复网络错误和非终态 5xx 使用有上限的退避与适当抖动;收到服务端重试提示时按契约处理。HTTP 5xx 内部可能已经返回 failed 的任务体,不应无限重查该终态。具体限流配额需要实际接口说明,本篇不给一个虚构的“安全 QPS”。

未核实 Atlas 回调参数,先不要编造

本次查阅的契约不足以确认可通用使用的 Atlas webhook 注册字段、签名算法与事件投递保证。因此本包没有 callback_url 或 webhook_secret 的假执行示例,也不把 n8n 的 Wait URL 写成 Atlas 原生回调功能。

如果需要对你的应用发通知,可以由你自己的查询服务在确认终态后,将一个内部事件写入数据库/outbox,再投递到你控制的队列或回调接口。事件包含业务任务 ID、已核实状态、事件 ID 和版本,不含 API key。接收方验证你定义的身份与签名,并按事件 ID 去重。这是你的应用协议,不是 Atlas 标准。

真有官方 webhook 后仍需核对

上线前必须确认注册入口、签名覆盖字节、时间窗、重投机制、重复与乱序语义。验证事件后仍核对账户/任务归属,必要时读回服务端任务。不要允许某个伪造回调直接把另一个用户任务标成完成,或触发对任意 URL 的带凭据请求。

通知投递采用至少一次时,接收方应幂等处理;“事件发出”“用户收到通知”“生成已完成”“文件保存完毕”仍是不同状态。通知失败重发通知,不重生成媒体。

交付本教程时保留一次从 pending 到终态的实际状态记录,以及超时/重复查询测试。随包测试为模拟接口,不声称已经验证 Atlas 云端 webhook。

依据与复现范围

依据:S3、S6、S9、S10。本文使用本包约定的教学文件;模型能力与价格以执行时实际目录为准。线上付费步骤未代用户执行,离线验证结果见 测试报告。通用路径、授权和状态约定见 执行约定。