Skip to main content
POST
Python SDK
使用 POST /dca/trigger 为已发布的 Bright Data Scraper Studio 采集器启动异步批量采集。请求体是输入对象的 JSON 数组,每个对象都必须与采集器的输入模式匹配。 该端点会立即返回一个 collection_id。采集完成后,使用该 ID 调用接收批量数据端点(GET /dca/dataset)来获取结果。

请求

请求体是输入对象的 JSON 数组。每个对象都必须与你在 Scraper Studio 中为采集器定义的输入模式匹配。基于 URL 的采集器可能需要 url 字段,而其他采集器可能需要 keywordlocationcountry 等字段或自定义输入字段。 请求体必须是 JSON 数组。如果只有单个输入,请发送只包含一个对象的数组。

响应

collection_id 标识本次采集运行。调用 GET /dca/dataset 时,将它作为 id 的值来获取结果。

在采集完成时发送通知

使用 notify 查询参数,在批量采集完成时发送 webhook 或邮件通知。该参数接受一个 JSON 对象,以 URL 查询参数的形式传递,因此值必须经过 URL 编码。单独使用 notify(不带 deliver)时,通知在采集作业完成后发送。 以下 cURL 示例触发批量采集,并在作业完成时发送 webhook 通知。--url-query 选项(curl 7.87.0 起可用)会自动对 JSON 值进行 URL 编码:
响应与上文所示的标准 collection_id 响应相同。采集作业完成后,Bright Data 会向配置的端点发送通知。 notify 对象包含以下字段:

为单个请求覆盖交付设置

使用 deliver 查询参数,为特定请求覆盖爬虫的默认交付设置。这样可以将采集结果交付到与控制面板交付偏好中配置的目标不同的目的地,而无需修改爬虫配置。与 notify 相同,该参数接受一个经 URL 编码的 JSON 对象。 以下示例触发批量采集,将结果交付到 Amazon S3,并在交付完成后发送 webhook 通知:
deliver 对象支持与交付偏好相同的目标类型,包括 s3gcsazuresftpwebhookemail

notify 与 deliver 的组合行为

何时使用批量采集

在以下情况下使用批量采集(POST /dca/trigger):
  • 你需要在一次运行中处理多个输入。
  • 你可以等待采集完成后再获取结果。
  • 你希望稍后通过 collection_id 获取结果。
  • 你正在构建数据集或定时采集工作流。
当你需要为单个输入立即获取结果,或在较短的请求窗口内获取结果时,请使用实时采集

错误

重试行为

使用相同的输入重新触发会创建一个带有新 collection_id 的新采集运行。该端点不是幂等的,也不会在多次运行之间对输入去重。如果只想重试失败的输入,请使用获取作业错误识别本次运行中失败的输入,然后仅用这些输入触发一次新的采集。

授权

Authorization
string
header
必填

Use your Bright Data API Key as a Bearer token in the Authorization header.

How to authenticate:

  1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
  2. Include the API Key in the Authorization header of your requests
  3. Format: Authorization: Bearer YOUR_API_KEY

Example:

Learn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication

查询参数

collector
string
必填

Collector ID of the Scraper Studio scraper to run. The ID starts with c_.

示例:

"c_abc123"

version
string

Set to dev to trigger the development version of the scraper

name
string

Human-readable name for the batch collection.

queue_next
integer
默认值:1

If another collection is already running, queue this collection to run after it.

queue
string

Queue name used to group related collection runs. Runs that share a queue start one after another.

confirm_cancel
integer
默认值:1

Cancels a running collection for this collector and runs this one instead.

no_downloads
integer
默认值:1

Disables media file downloads for this collection.

deadline
string

Sets the maximum time the collection can run. When the deadline is reached, Bright Data terminates the collection. Use h for hours, m for minutes or s for seconds, for example 1h, 30m or 45s.

示例:

"1h"

notify
string

Notification configuration for this request as a URL-encoded JSON object. Used alone, the notification is sent when the collection job completes. Used together with deliver, the notification is sent after delivery completes.

示例:

"{\"type\":\"webhook\",\"endpoint\":\"https://example.com/webhook\"}"

deliver
string

Request-level delivery configuration as a URL-encoded JSON object. Overrides the scraper's default Delivery preferences for this collection only.

示例:

"{\"type\":\"s3\",\"bucket\":\"YOUR_BUCKET\",\"credentials\":{\"aws-access-key\":\"YOUR_AWS_ACCESS_KEY\",\"aws-secret-key\":\"YOUR_AWS_SECRET_KEY\"},\"region\":\"YOUR_REGION\",\"directory\":\"brightdata/YOUR_DIRECTORY\",\"filename\":{\"template\":\"results_{[datetime]}\",\"extension\":\"json\"},\"delivery_type\":\"deliver_results\"}"

请求体

application/json

A JSON array of input objects. Each object must match the input schema defined for the collector. A URL-based collector may require a url field, while other collectors may require fields such as keyword, location or country. For a single input, send an array with one object.

url
string<uri>

Example field for collectors that take a target URL. Replace with the fields your collector expects.

响应

200 - application/json

Returns a collection_id for the new collection run.

collection_id
string

ID of the collection run. Use this value as the id when calling GET /dca/dataset to retrieve results.

start_eta
string

Estimated start time for the collection, in ISO 8601 format.