用途:围绕 SerpAPI 构建长时间运行的异步搜索或定时监控流程,避免虚构不存在的 webhook 回调契约。
主要能力:使用 async=true 提交搜索而不保持连接,通过 Searches Archive API 按搜索 ID 取回结果;状态可经历 queued、processing 到 success 或 error。定义 SUBMITTED、QUEUED、PROCESSING、SUCCEEDED、FAILED、EXPIRED、TIMED_OUT 等状态及终态行为。支持按搜索 ID 与负载版本做幂等下游处理,定时监控时存储快照并比较归一化业务字段。
使用方式:在服务端提交器与轮询器中使用 SERPAPI_KEY;持久化 search ID 与安全状态,不保存含密钥的归档 URL。轮询使用官方客户端归档方法或文档化归档端点,采用递增延迟、抖动与硬截止时间。示例:submitted = client.search({"engine": "google", "q": "coffee", "async": True}),search_id = submitted["search_metadata"]["id"],再以 client.search_archive(search_id=search_id) 查询状态。下游通知端点需按其自身文档机制鉴权授权。
适用场景:需要后台处理或重复监控的引擎与用例,并已明确轮询截止时间、调度、配额与吞吐预算、检查点存储及下游负责人。
限制:async 不可与 no_cache 组合,也不适用于 Ludicrous Speed 账户。公开契约未定义通用回调 webhook,如需回调应改用轮询或取得当前书面厂商专属契约,不得自行发明。归档返回 410 时标记过期,替换搜索前需审批。创建生产调度、发送实时搜索、暴露通知端点或变更下游记录均需具名负责人审批。