触发异步数据采集 API

了解如何使用 Scrapers 触发数据采集，支持 discovery 和 PDP 两种采集方式。可自定义请求、设置交付选项，并高效获取数据。

POST /datasets/v3/trigger

cURL

cURL

curl --request POST \
  --url https://api.brightdata.com/datasets/v3/trigger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "url": "https://il.linkedin.com/company/bright-data"
  }
]
'

200

{
  "snapshot_id": "s_m4x7enmven8djfqak"
}

工作原理

默认情况下，抓取请求会以异步方式处理。提交请求后，系统会在后台开始处理任务，并立即返回一个快照 ID。任务完成后，你可以使用该快照 ID 通过 API 下载数据，从而在任意时间获取结果。你也可以将请求配置为自动将结果交付到外部存储（如 S3 或 Azure Blob Storage）。这种方式非常适合处理大规模任务或集成自动化数据管道。

Body

提供给 scraper 使用的输入。可作为 JSON 或 CSV 文件提交：

Content-Type · string

一个 JSON 数组作为输入

Example: [{"url":"https://www.airbnb.com/rooms/50122531"}]

---

一个 CSV 文件，通过字段 data 传入

Example (curl): data=@path/to/your/file.csv

Web Scraper 类型

不同 scraper 可能需要不同的输入。主要有两类：

1. PDP

这些 scraper 需要 URL 作为输入。PDP scraper 会从网页提取产品详情，如规格、价格和功能信息。

2. Discovery

Discovery scrapers 允许通过搜索、分类、关键词等方式探索并发现新的实体或产品。

请求示例

PDP URL 输入示例

PDP 的输入格式始终是指向待抓取页面的 URL。

Sample Request

curl -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" -d '[{"url":"https://www.airbnb.com/rooms/50122531"},{"url":"https://www.airbnb.com/rooms/50127677"}]' "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_ld7ll037kqy322v05&format=json&uncompressed_webhook=true"

基于 discovery 方法的 Discovery 输入示例

Sample Request

curl -H "Authorization: Bearer x2x3fdaaddrer" -H "Content-Type: application/json" -d '[{"keyword":"light bulb"},{"keyword":"dog toys"},{"keyword":"home decor"}]' "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l7q7dkf244hwjntr0&endpoint=https://webhook-url.com&auth_header=QWxhZGRpbjpPcGVuU2VzYW1l&notify=https://notify-me.com/&format=ndjson&uncompressed_webhook=true&type=discover_new&discover_by=keyword&limit_per_input=10"

discovery 的输入格式可能因具体 scraper 而异。示例如下：

keywords

[{"keyword": "light bulb"},{"keyword": "dog toys"},{"keyword": "home decor"}]

还有更多输入格式。你可以在这里查看每个 scraper 所需的输入。

Authorizations

Authorization · string · header · required

在 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

示例:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

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

Query Parameters

dataset_id · string · required

触发数据采集的数据集 ID。

Example:

"gd_l1vikfnt1wgvvqz95w"

custom_output_fields · string

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

Example:

"url|about.updated_on"

type · enum<string>

设置为 "discover_new" 以触发包含发现阶段的数据采集。

Available options: discover_new

discover_by · string

指定使用哪种发现方法。可选项包括: "keyword"、"best_sellers_url"、"category_url"、"location" 等（根据具体 API）。仅对包含发现阶段的采集相关。

include_errors · boolean

在结果中包含错误报告。

limit_per_input · number

每个输入的结果数量限制。仅对包含发现阶段的采集相关。

Required range: x >= 1

limit_multiple_results · number

限制总结果数量。

Required range: x >= 1

notify · string

当采集完成时，通知将发送到此 URL，包含 snapshot_id 和状态。

endpoint · string

数据将被传送到的 webhook URL。

format · enum<string>

指定传送到 webhook 的数据格式。

Available options: json, ndjson, jsonl, csv

auth_header · string

发送通知到 notify URL 或通过 webhook 传输数据时使用的授权头。

uncompressed_webhook · boolean

默认情况下，数据会被压缩发送到 webhook。传 true 可不压缩发送。

Body

application/jsonmultipart/form-data

仅输入 · object[]

交付配置和输入 · object

{key} · any

Response

200 - application/json

采集任务成功启动

snapshot_id · string

可在后续 API 中使用的请求 ID

Example:

"s_m4x7enmven8djfqak"