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

请求

请求体是输入对象的 JSON 数组。每个对象都必须与你在 Scraper Studio 中为采集器定义的输入模式匹配。基于 URL 的采集器可能需要 url 字段,而其他采集器可能需要 keyword、location、country 等字段或自定义输入字段。 请求体必须是 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 对象支持与交付偏好相同的目标类型,包括 s3、gcs、azure、sftp、webhook 和 email。

notify 与 deliver 的组合行为

何时使用批量采集

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

错误

重试行为

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

授权

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?

查询参数

collector
string
必填

scraper 的唯一标识

version
string

设置为 dev 以触发 scraper 的开发版本

name
string

human_name - 批处理的可读名称

queue_next
integer
默认值:1

如果抓取队列中已有任务,将此任务加入队列

queue
string

发送另一个批次的请求,该批次将在上一个完成后启动

confirm_cancel
integer
默认值:1

取消正在运行的任务并替换运行,提交请求后取消当前任务

no_downloads
integer
默认值:1

禁用媒体文件下载

deadline
string

设置任务截止时间,超过指定时间任务将被终止。h 表示小时,m 表示分钟,s 表示秒。

notify
string

本请求的通知配置,为 URL 编码的 JSON 对象。单独使用时,在采集作业完成后发送通知;与 deliver 一起使用时,在交付完成后发送通知。

示例:

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

deliver
string

请求级交付配置,为 URL 编码的 JSON 对象。仅对本次采集覆盖爬虫在交付偏好中配置的默认交付设置。

示例:

"{\"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
url
string<uri>

响应

200 - application/json

OK