Skip to main content
POST
抓取数据并直接在响应中返回。

工作原理

此同步 API 端点允许用户在发送抓取请求时,实时直接在响应中获取结果,例如在终端或应用程序中,无需外部存储或手动下载。此方式通过消除额外的结果获取步骤,使数据采集过程更加高效。 你可以使用 format 参数指定所需的输出格式。如果未提供格式,响应将默认使用 JSON。

请求体

POST /datasets/v3/scrape 接受两种请求体格式,返回的记录相同。 纯 JSON 数组,由输入对象组成。所有快速开始和平台页面使用此格式:
带有 input 数组的对象。当您同时传入 custom_output_fields 以只返回指定字段,或传入 limit_per_input 以限制每个输入返回的记录数时,请使用此格式:
limit_per_input 对发现请求尤为重要,因为其结果数量不固定。以下请求发现某个子版块中的帖子,并在三条后停止:
在查询字符串中附加 type=discover_new&discover_by=subreddit_url 发送。控制面板生成的 cURL 使用相同的请求体格式。在 /scrape 上,作为查询参数传入的 limit_per_input 会被忽略。 POST /datasets/v3/trigger 接受相同的两种格式。在该端点上,deliver 配置也放在对象格式中。详见异步请求

超时限制

请注意,此同步请求受 1 分钟超时限制。如果数据获取过程超过此限制,API 将返回 HTTP 202 响应,表示请求仍在处理中。在这种情况下,你将收到一个快照 ID,可通过“监控快照(Monitor Snapshot)”和“下载快照(Download Snapshot)”端点以异步方式监控并获取结果。202 响应带有 retry-after 头(撰写本文时为 10 秒),指示轮询前应等待的时间。 超时情况下的示例响应:
202

如何处理 202 响应

运行超过 1 分钟的 /scrape 请求会返回 HTTP 202 和 snapshot_id,而不是记录,任务继续在后台运行。请根据状态码分支处理,然后轮询监控进度,并通过下载快照获取记录。轮询循环见如何使用异步请求批量抓取数据
Python
200 返回记录;202 返回快照 ID。其他状态均为错误,见下方的响应部分。

自定义输入

您可以在输入结构中添加自定义字段。您在这些字段中发送的内容会随每条记录一起返回到结果中。适用于:
  • 在不同抓取器和数据集之间保持统一的输出结构。
  • 传入 idrow_index 或任意内部键,以便将结果与原始输入行对应起来。

授权

Authorization
string
header
必填

在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。

认证方法:

  1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
  2. 在请求的 Authorization 头中包含 API Key
  3. 格式: Authorization: Bearer YOUR_API_KEY

示例:

了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key?

查询参数

dataset_id
string
必填

触发数据采集的数据集 ID

custom_output_fields
string

输出列列表,用 | 分隔(例如:url|about.updated_on)。仅包含指定字段的响应。

示例:

"url|about.updated_on"

include_errors
boolean

在结果中包含错误报告

format
enum<string>
默认值:json

指定响应格式(默认: ndjson)

可用选项:
ndjson,
json,
csv

请求体

application/json
{key}
any

响应

成功

记录的 JSON 数组。空数组表示输入未产生记录;请检查输入 URL。

The response is of type string.

示例:

"OK"