跳转到主要内容
每个请求都会保存为一个任务。你提交任务,立即拿到任务 id,之后通过 webhook 或轮询获取结果。如需在同一个请求中拿到结果,请改为发送到 POST /v1/sync/task。
提交响应为 200,任务处于 QUEUED:
用 id 轮询(参考):

生命周期

状态

遇到临时失败的任务会回到 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 个任务。