跳转到主要内容
本指南将向 Bright Data Scraper Studio API 发送您的第一个请求：从您自己的代码触发一个已发布的爬虫，并取回结构化 JSON。
还没有爬虫？ 爬虫是您在此处触发的已发布抓取程序。先用几分钟构建一个，拿到它的 Collector ID（c_...）后再回到本页：本快速开始从您已拥有 Collector ID 之后开始。
Bright Data Scraper Studio API 围绕两个 HTTP 调用构建：
  1. POST /dca/trigger，将一个或多个输入入队并返回一个快照 ID。
  2. GET /dca/dataset?id=<snapshot_id>，在快照就绪后提供该快照。
对于包含 1 到 10 个输入的爬虫，首条记录通常约需 3 分钟。

​
前置条件

将这两个值设置为环境变量一次，即可在下方所有代码片段中复用： 
export BRIGHT_DATA_API_TOKEN="your_api_token_here"
export BRIGHT_DATA_COLLECTOR_ID="c_xxxxxxxxxxxxxxxx"

​
发送您的第一个请求

1

为每个调用进行身份验证

每个 Bright Data Scraper Studio API 调用都使用 bearer-token 身份验证。为每个请求添加以下请求头：
Authorization: Bearer YOUR_BRIGHT_DATA_API_TOKEN
缺失或无效的 token 会返回 401 Unauthorized。
2

触发您的爬虫

将您希望爬虫处理的输入作为 JSON 数组放入请求体。数组中的每个对象都必须匹配您构建爬虫时定义的输入 schema。默认 schema 是单个 url 字段。
curl -X POST \
  "https://api.brightdata.com/dca/trigger?collector=$BRIGHT_DATA_COLLECTOR_ID&queue_next=1" \
  -H "Authorization: Bearer $BRIGHT_DATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"url": "https://ecommerce-shop-brd.vercel.app/product/echo-portable-speaker"},
    {"url": "https://ecommerce-shop-brd.vercel.app/product/nimbus-cloud-storage"}
  ]'
Bright Data Scraper Studio API 返回一个快照 ID：
{
  "collection_id": "j_abc123def456"
}
请保存此 ID。您将在第 3 步中把它作为 snapshot_id 使用。
queue_next=1 会立即运行您的输入。省略它（或设为 0）会将这些输入排在同一爬虫尚未完成的工作之后。
3

轮询直到就绪，然后下载

同一个 /dca/dataset 端点同时提供进行中和已就绪的响应。每 5 秒轮询一次，直到响应是一个 JSON 数组。
# 每 5 秒轮询一次，直到响应是 JSON 数组（而非对象）。
while :; do
  response=$(curl -s \
    "https://api.brightdata.com/dca/dataset?id=$SNAPSHOT_ID" \
    -H "Authorization: Bearer $BRIGHT_DATA_API_TOKEN")
  if [[ "${response:0:1}" == "[" ]]; then
    echo "$response" > results.json
    break
  fi
  sleep 5
done
在快照构建期间，响应是一个状态对象：
{ "status": "building" }
快照就绪后，响应是一个 JSON 数组。默认情况下每个成功的输入对应一行：
[
  {
    "url": "https://ecommerce-shop-brd.vercel.app/product/echo-portable-speaker",
    "title": "Echo Portable Speaker",
    "price": 49.99,
    "availability": "in stock",
    "input": { "url": "https://ecommerce-shop-brd.vercel.app/product/echo-portable-speaker" }
  },
  {
    "url": "https://ecommerce-shop-brd.vercel.app/product/nimbus-cloud-storage",
    "title": "Nimbus Cloud Storage",
    "price": 12.99,
    "availability": "in stock",
    "input": { "url": "https://ecommerce-shop-brd.vercel.app/product/nimbus-cloud-storage" }
  }
]
确切的字段集取决于您构建爬虫时定义的输出 schema。

​
这需要多长时间？

首条记录通常在一分钟内到达，但总耗时取决于爬虫和目标站点。以一个典型的电商商品页爬虫为基准测量：
输入数量典型实际耗时
1 到 10 个 URL30 到 90 秒
11 到 100 个 URL2 到 5 分钟
100 个以上 URL5 分钟以上。请改用推送交付，而非轮询。
对于长时间运行的作业，请将轮询替换为推送交付目标（webhook、S3、GCS、Azure、SFTP 或电子邮件），这样快照就绪时由 Bright Data 主动通知您。

​
这些 ID 分别代表什么？

Bright Data Scraper Studio 中会出现三个标识符。它们容易混淆，因为触发响应对某个值使用的名称，与另一个端点读取它时使用的名称不同。
术语形如它标识什么
Collector IDc_xxxxxxxxxxxxxxxx已发布的爬虫定义。稳定不变。您将它作为 /dca/trigger 上的 collector 查询参数传入。
Collection ID（返回为 collection_id）j_xxxxxxxxxxxxxxxx爬虫的一次运行。触发响应的字段名为 collection_id，但其他所有端点都以 snapshot_id 指代同一个值。它们是同一个字符串。
Dataset一个 JSON 数组一次运行产出的结果行。运行完成后 /dca/dataset 端点返回它。
将触发响应中的 collection_id 视为其他所有地方的 snapshot_id。它们是同一个值的两个名称。

​
可能遇到哪些错误？

状态含义修复方法
401 Unauthorizedtoken 缺失、格式错误或已吊销从 账户设置 → API Tokens 重新复制
404 Not FoundCollector ID 不存在，或您的账户无访问权限在 Scraper Studio 中打开该爬虫并重新复制 ID
422 Unprocessable Entity请求体中的对象与爬虫的输入 schema 不匹配对照爬虫的 Inputs 标签页确认字段名
5xxBright Data API 暂时性错误使用指数退避重试，例如 1s、2s、4s
[]（空数组）快照没有任何行，或快照已过期批处理结果保留 16 天，实时结果保留 7 天。参见 规格说明

​
使用生产级入门模板

以下开源仓库正是上面这些调用，并经过加固：环境变量配置、针对暂时性故障的重试/退避、库辅助函数和完整的 README。Fork 任意一个，30 秒内即可拥有一个可运行的客户端。

Node.js 入门模板

Node 18+、ES modules、dotenv、重试/退避，约 150 行代码

Python 入门模板

Python 3.8+、requests、python-dotenv、重试/退避，约 150 行代码
两个仓库都附带 CodeSandbox devcontainer，无需任何本地设置即可在浏览器中 fork 并运行。

​
后续步骤

选择交付类型

跳过轮询。让 Bright Data 在快照就绪时将结果推送到 webhook、S3、GCS 或电子邮件。

触发批量收集

在单个请求中发送数百或数千个输入，并分批接收结果。

运行同步实时作业

适用于低输入量、对延迟敏感的工作负载。在单个 HTTP 调用中触发并接收结果。

构建新爬虫

需要一个尚不存在的爬虫？用 CLI、AI Agent 或 IDE 构建一个。

​
常见问题

用以下三种路径之一构建 Scraper Studio 爬虫，然后在此处使用它返回的 Collector ID（c_...）：
  • Bright Data CLI 最快。运行 bdata scraper create <url> "<要提取的数据>"，AI Agent 会编写爬虫。该 CLI 在 Claude Code、Cursor 或 Codex 中可原样运行。
  • AI Agent 在控制面板中根据一段自然语言提示词构建爬虫，无需写代码。
  • IDE 让您完全掌控爬虫代码。
Collection API（/dca/*，即本页）运行一个现有爬虫来获取数据。 AI Flow API 运行 AI Agent 来创建或自我修复爬虫。 大多数将 Bright Data Scraper Studio 集成进产品的开发者使用 Collection API。
可以，只要数组中的每个对象都符合爬虫的输入 schema。如果您的爬虫同时接受 url 和 keyword 作为输入字段，您可以在一个请求中混用它们。未包含的字段被视为 null。
在 My Scrapers 中打开快照并点击 Last errors，查看哪些输入失败及原因。在一个新的 POST /dca/trigger 调用中仅重新触发那些输入。
有。每爬虫的并发限制按账户应用。当前限制参见 规格说明。上面链接的入门模板已为暂时性 5xx 响应实现指数退避。