Skip to main content
Bright Data Scraper APIs 提供两种数据收集方法。本指南解释了它们的区别，并帮助您为用例选择正确的方法。

​
什么是同步和异步请求？

同步 (/scrape) 发送请求并在同一 HTTP 响应中等待爬取的数据。连接保持打开，直到结果准备好。 异步 (/trigger) 发送请求，立即接收 snapshot_id，稍后通过轮询、webhook 或外部存储交付来收集结果。

​
何时使用每种方法

在以下情况下使用同步请求：
  • 您需要少量 URL（1-20 个）的实时结果
  • 您正在构建等待数据的交互式应用程序
  • 您想要最简单的集成，无需后台任务管理
在以下情况下使用异步请求：
  • 您在一个批次中爬取超过 20 个 URL
  • 您运行发现查询（按关键字搜索、按公司查找帖子）
  • 您希望将结果交付到 webhook 或外部存储（S3、Snowflake）
  • 您正在构建需要可靠性和重试处理的生产管道

​
它们的比较

功能同步 /scrape异步 /trigger
每个请求的最大 URL 数20无限制（最多 1 GB 输入）
响应直接爬取数据snapshot_id（数据单独检索）
超时1 分钟（自动转换为异步）无超时
发现支持否是
Webhook 交付否是
外部存储否是
并发限制1,500 个请求100 个请求
理想用途快速查询、实时应用批处理作业、生产管道

​
同步请求流程

您的应用 --> POST /scrape --> [等待 10-30 秒] --> 响应中的爬取数据
整个操作发生在单一 HTTP 请求中。如果爬取花费的时间超过 1 分钟，API 会自动将其转换为异步作业并返回 snapshot_id。
如果您从同步请求收到 snapshot_id 而不是数据，您的请求已被自动转换。使用异步检索工作流来下载结果。

​
异步请求流程

您的应用 --> POST /trigger --> snapshot_id（立即）
                                    |
                     +--------------+--------------+
                     |              |              |
                  轮询 API      Webhook      S3/存储
                     |              |              |
                  GET /snapshot  POST 到 URL   桶中的文件
异步流程将触发与检索分离。您有三种获取结果的选项：
  1. 轮询 API - 使用 GET /progress/{snapshot_id} 检查状态，然后使用 GET /snapshot/{snapshot_id} 下载
  2. Webhook - 当作业完成时，Bright Data 将结果发送到您的 URL
  3. 外部存储 - 结果交付到 S3、Snowflake 或其他存储

​
常见场景

单页查询 您的应用需要从一个 URL 实时获取数据（例如，充实销售线索、检查产品页面）。使用同步。一个 URL，即时结果，简单集成。 每周批处理报告 每周一，您爬取 500 个跨多个来源匹配搜索条件的页面。使用异步和发现功能。将结果交付到 S3 供您的数据管道使用。 具有后台充实的实时应用 用户触发搜索，您立即显示初始结果。使用同步进行第一次查询，然后使用异步和 webhook 在后台收集额外数据。 每晚竞争对手监控 每晚，您爬取数百个竞争对手页面。使用异步和 S3 交付。无需轮询，数据出现在您的桶中。

​
常见误解

不正确。对于 1-5 个 URL，同步请求更快，因为没有作业调��开销。异步在爬取开始前添加了队列步骤。对于小型、实时查询，使用同步。
它们不会失败。如果同步请求超过 1 分钟超时，Bright Data API 会自动将其转换为异步作业并返回 snapshot_id。您的数据仍然会被收集。您只需使用异步流程来检索它。

​
在代码中处理自动转换

如果同步请求超过 1 分钟超时，API 返回 snapshot_id 而不是数据。处理两种情况：
Python
import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    params={"dataset_id": "DATASET_ID", "format": "json"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json=[{"url": "https://example.com/target-page"}],
)

data = response.json()

if isinstance(data, list):
    # 同步响应：数据已准备好
    print(f"Got {len(data)} results")
elif isinstance(data, dict) and "snapshot_id" in data:
    # 自动转换为异步：轮询结果
    print(f"Job running. Snapshot ID: {data['snapshot_id']}")

​
常见问题

是的。许多应用对面向用户的实时查询使用同步���对批处理后台作业使用异步。为每个用例使用适合的方法。
如果您的端点返回非 200 状态或超时，Bright Data 会重试 webhook 交付。如果您需要有保证的交付，请使用 S3 或其他外部存储选项。
没有。定价是按成功记录计算的，与请求方法无关。同步和异步之间的选择是关于数量、延迟和交付偏好，而不是成本。

​
后续步骤

Scraper APIs 概览

浏览所有可用的 Bright Data Scraper APIs。

交付选项

Webhook、S3、Snowflake、Azure 等。