POST /v1/sync/task。
200,任务处于 QUEUED:
生命周期
状态
遇到临时失败的任务会回到
QUEUED 并再次运行。只有重试耗尽后才会落定为 FAILED,因此 PROCESSING → QUEUED 的转换是正常的。
任务进入终止状态前,轮询不会返回 response。失败的任务则带有顶层 error 字符串:
提交与轮询时的积分
价格、冻结和限制请参阅积分与限制。
处理时间
task.latencyMs 是引擎耗费的时间:从工作进程首次领取任务到最终结果,以毫秒计,不包含排队等待。因临时失败重新入队时,仍从首次领取算起。提交响应以及 QUEUED、PROCESSING 状态下为 null,终止后的轮询和 webhook 中为数字。响应头 X-Latency-Ms 表示本服务器处理该 HTTP 请求所用的时间,是另一个值。
优先级
priority 接受 1 到 10,默认 1。超出范围的值会被截断到范围内,而不是被拒绝。该值会原样出现在任务元数据中。
保留期
终止状态的任务在完成后 24 小时内可以轮询。之后,GET /v1/async/task/{id} 返回 404 RESOURCE_NOT_FOUND,与未知 id 或其他账户的任务相同。QUEUED 和 PROCESSING 任务无论多久都保持可见。
24 小时窗口同样适用于 GET /v1/batches/{id}/items 和网格读取中的结果正文。任务的 idempotencyKey 占用得更久,在请求后至少保持占用 30 天(参见幂等性)。自动 webhook 重试按自己的计划进行,与该窗口无关。
在一个请求中等待结果
POST /v1/sync/task 接收相同的请求体,并保持请求直到任务结束,最长 290 秒。任务结束后返回 200,响应体与轮询该任务时相同,失败的任务也一样。
回答引擎比 SERP 和 Search 任务耗时更长。请按引擎目录中的分类决定保持请求的时长,并把 HTTP 客户端的超时设得比它长几秒。
- 等待结束时任务仍未结束,则返回
202、任务和Location: /v1/async/task/{id}。任务会继续运行并照常计费,请轮询该地址或通过 webhook 接收。服务同时保持大量请求时,也可能立即返回202。 - 发送
Prefer: wait=<秒数>可让请求保持少于 290 秒。请让它短于你的 HTTP 客户端超时,这样在客户端放弃之前就能拿到任务 id。 - 请发送
idempotencyKey。再次发送相同的键会返回持有该键的任务,因此你可以重发在你这边超时的请求,而不会让任务运行两次。 - 带上
Accept: text/html和payload.include.html: true时,已完成的任务会以text/html返回其保存的页面,X-Task-Id中带有任务 id。失败的任务,或页面未能保存的任务,返回406和 JSON 响应体。
选择 webhook 还是轮询
优先使用 webhook。用轮询找回未收到的结果。
健壮的客户端两者兼用:以 webhook 作为快速路径,对尚未收到通知的任务在 24 小时窗口内尽早轮询。
下一步
Webhook
负载、签名和重试。
批次与网格
一次提交最多 10,000 个任务。