跳转到主要内容
通过 Olostep 的 /v1/batches 端点,你可以在一个批处理中处理多达 10 万个 URL。一个批处理大约需要 5-8 分钟。使用它可以以异步方式大规模提取内容或结构化数据。
  • 每个批处理提交最多 10 万个 URL
  • 无论批处理大小,单个批处理大约需要 5–8 分钟。批处理是一个异步端点
  • 并行运行多个批处理,以扩展到数百万个并发请求。
  • 使用解析器返回结构化 JSON,或通过 /v1/retrieve 检索 markdown/html
  • 如果你想以低延迟或同步方式获取结果,请使用抓取端点并发送许多并发请求。
有关 API 详细信息,请参阅 批处理端点 API 参考。
注意:对于新账户,每个批处理限制为 100 个项目。要解除此限制,请通过 info@olostep.com 联系我们或在 Slack 上联系我们。

安装

开始一个批处理

提供一个包含 custom_id 和 url 的 items 数组。这些是将在批处理中处理的 URL,custom_id 是 URL 的内部唯一标识符。 可以选择传递 parser 或 country。通过 parser 参数,你可以为批处理指定要使用的解析器,这将从页面返回结构化 JSON。
由于 Olostep 遵循面向对象的方法,你将收到一个 batch 对象作为响应。batch 对象具有一些属性,如 id 和 status。

检查批处理状态

轮询直到 status 为 completed。你还可以检查 completed_urls 属性以查看已处理的 URL 数量。

检索内容

使用每个项目的 retrieve_id 通过 /v1/retrieve 获取 html_content、markdown_content 或 json_content。

列出项目(使用游标分页)

GET /v1/batches/{id}/items 默认返回最多 10000 个项目(也是最大值)。如果响应中包含 cursor,则表示还有更多项目 —— 在下一个请求中传递该 cursor,直到它不存在。优先使用 /v1/retrieve 和 retrieve_id 获取内容。

响应格式

当你运行提供的示例代码时,你将收到类似以下的响应
由于我们传递了解析器以检索结构化 JSON 并且我们仅打印该内容,响应包含:
  • json_content 包含结构化搜索结果,包括:
  • searchParameters: 关于搜索查询的信息
  • knowledgeGraph: 搜索主题的详细信息(如果可用)
  • organic: 搜索结果列表,包含标题、链接、位置和摘要
  • peopleAlsoAsk: 用户常搜索的相关问题
  • relatedSearches: 建议的相关搜索查询
如果你不想要结构化 JSON,而只是 markdown 或 html,你可以从检索端点获取这些内容。

Webhooks

与其轮询批处理状态,你可以在创建批处理时传递一个 webhook URL。当批处理完成时(所有项目完成或失败),Olostep 会向该 URL 发送一个 HTTP POST。 你的 webhook 端点必须通过 http:// 或 https:// 可公开访问。它不能指向本地主机或私有 IP 地址。有关完整的负载形状、重试行为和最佳实践(快速响应 2xx,使用事件 id 去重),请参阅 Webhooks。
参数名称: 规范字段是 webhook。为了向后兼容,webhook_url 也被接受为别名。
对于批处理,batch.completed 事件包括批处理 ID、状态和项目计数。失败的交付会自动重试(最多 5 次尝试,大约 30 分钟 内,具有指数退避)。你的处理程序必须在每次尝试的 30 秒 内返回 2xx 状态。

元数据

附加自定义 字符串键值 元数据到批处理中,用于跟踪、过滤和将作业与你自己的系统(订单 ID、项目名称、管道阶段等)相关联。元数据遵循我们的 元数据 参考中的相同规则。 在创建批处理时,你可以在 两个级别 设置元数据:
  • 批处理级别 — 在 请求体 上的 metadata(适用于整个批处理)
  • 项目级别 — 在 items 数组中的 每个对象 上的 metadata(每个 URL)
元数据会在该批处理的后续 GET 响应中 返回。你可以稍后使用 更新批处理(PATCH)合并更新 批处理元数据;有关添加、覆盖和删除行为,请参阅元数据指南。
类型强制转换: 数字和布尔值会转换为字符串(例如 42 → "42",true → "true")。嵌套对象和数组会被拒绝。
有关完整示例和 PATCH 语义,请参阅 元数据。

重要说明

如果你想要结构化的 JSON,你需要在发出请求之前将特定解析器传递给 API。例如,如果你想从 Google 搜索中获取 JSON,你将传递此解析器 "parser": {"id": "@olostep/google-search"} 你可以创建自己的解析器,从任何页面检索你想要的数据。请联系 info@olostep.com 了解更多信息。

结论

批处理端点在你需要在短时间内从许多 URL 获取数据时非常有用。你需要已经有了你想要获取数据的 URL 列表。 常见应用包括:
  • 价格跟踪服务,监控多个电子商务网站上的产品价格变化
  • 网站监控工具,检查多个页面的内容更新
  • 为音乐会组织者聚合数据,跟踪多个场馆的票务可用性
  • 搜索引擎同时收集和索引来自许多网站的内容
  • 新闻聚合器从各种出版物收集文章
  • 房地产平台监控多个网站上的房源
  • 招聘网站从公司招聘页面聚合职位空缺
  • 金融数据服务跟踪股票价格和市场信息
  • 社交媒体监控工具分析不同平台上的提及
  • 学术研究从多个来源收集数据进行分析
如果你想一次获取 100 到 10 万个 URL 的内容,使用批处理端点更好。如果你需要一次抓取少于 50 个 URL,我们建议使用抓取端点并并行提交 URL,因为它比批处理端点更快。

定价

批处理每个 URL 消耗 1 个积分。