> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 理解同步与异步请求

> 了解何时使用 Bright Data Scraper APIs 的同步或异步请求，以及每种方法的权衡。

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`。

<Tip>
  如果您从同步请求收到 `snapshot_id` 而不是数据，您的请求已被自动转换。使用异步检索工作流来下载结果。
</Tip>

## 异步请求流程

```
您的应用 --> 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 交付。无需轮询，数据出现在您的桶中。

## 常见误解

<Accordion title="异步总是比同步快">
  不正确。对于 1-5 个 URL，同步请求更快，因为没有作业调��开销。异步在爬取开始前添加了队列步骤。对于小型、实时查询，使用同步。
</Accordion>

<Accordion title="如果同步请求花费时间过长，它们会失败">
  它们不会失败。如果同步请求超过 1 分钟超时，Bright Data API 会自动将其转换为异步作业并返回 `snapshot_id`。您的数据仍然会被收集。您只需使用异步流程来检索它。
</Accordion>

## 在代码中处理自动转换

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

```python Python theme={null}
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']}")
```

## 常见问题

<Accordion title="我可以在同一应用中混合同步和异步吗？">
  是的。许多应用对面向用户的实时查询使用同步���对批处理后台作业使用异步。为每个用例使用适合的方法。
</Accordion>

<Accordion title="当异步结果准备好时，如果我的 webhook 关闭了会发生什么？">
  如果您的端点返回非 200 状态或超时，Bright Data 会重试 webhook 交付。如果您需要有保证的交付，请使用 S3 或其他外部存储选项。
</Accordion>

<Accordion title="同步和异步之间有成本差异吗？">
  没有。定价是按成功记录计算的，与请求方法无关。同步和异步之间的选择是关于数量、延迟和交付偏好，而不是成本。
</Accordion>

## 后续步骤

<CardGroup cols={2}>
  <Card title="Scraper APIs 概览" icon="grid-2" href="/cn/datasets/scrapers">
    浏览所有可用的 Bright Data Scraper APIs。
  </Card>

  <Card title="交付选项" icon="truck" href="/cn/datasets/scrapers/scrapers-library/delivery-options">
    Webhook、S3、Snowflake、Azure 等。
  </Card>
</CardGroup>