# 批量抓取

> 通过单个批处理作业抓取多个 URL

import BatchScrapePython from '/snippets/zh/v2/batch-scrape/base/python.mdx';
import BatchScrapeNode from '/snippets/zh/v2/batch-scrape/base/js.mdx';
import BatchScrapeCURL from '/snippets/zh/v2/batch-scrape/base/curl.mdx';
import BatchScrapeOutput from '/snippets/zh/v2/batch-scrape/base/output.mdx';
import BatchScrapeAsyncOutput from '/snippets/zh/v2/batch-scrape/base/async-output.mdx';
import BatchScrapeExtractPython from '/snippets/zh/v2/batch-scrape/json/python.mdx';
import BatchScrapeExtractNode from '/snippets/zh/v2/batch-scrape/json/js.mdx';
import BatchScrapeExtractCURL from '/snippets/zh/v2/batch-scrape/json/curl.mdx';
import BatchScrapeExtractOutput from '/snippets/zh/v2/batch-scrape/json/output.mdx';
import BatchScrapeExtractAsyncOutput from '/snippets/zh/v2/batch-scrape/json/async-output.mdx';
import BatchScrapeWebhookCURL from '/snippets/zh/v1/batch-scrape-webhook/base/curl.mdx';

批量抓取让你能够在单个任务中抓取多个 URL。传入一个 URL 列表和可选参数后，Firecrawl 会并发处理这些 URL，并一次性返回所有结果。

* 类似 `/crawl`，但适用于明确指定的一组 URL
* 支持同步和异步模式
* 支持所有抓取选项，包括结构化提取
* 可为每个任务配置并发数

<div id="operations">
  ## 操作
</div>

| 任务          | API 参考                                                                       | SDK 术语                                                                    |
| ----------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| 启动批量任务      | [`batch-scrape`](/zh/api-reference/endpoint/batch-scrape)                       | `batchScrape` / `batch_scrape`, `startBatchScrape` / `start_batch_scrape` |
| 查看状态和结果     | [`batch-scrape-get`](/zh/api-reference/endpoint/batch-scrape-get)               | `getBatchScrapeStatus` / `get_batch_scrape_status`                        |
| 取消正在运行的批量任务 | [`batch-scrape-delete`](/zh/api-reference/endpoint/batch-scrape-delete)         | 通过 ID 取消或删除批量任务                                                           |
| 查看错误        | [`batch-scrape-get-errors`](/zh/api-reference/endpoint/batch-scrape-get-errors) | 用于失败 URL 的错误/状态辅助工具                                                       |

<div id="how-it-works">
  ## 工作方式
</div>

你可以通过两种方式运行批量抓取：

| 模式 | SDK 方法 (JS / Python)                      | 行为                           |
| -- | ----------------------------------------- | ---------------------------- |
| 同步 | `batchScrape` / `batch_scrape`            | 启动批量任务并等待其完成，返回所有结果          |
| 异步 | `startBatchScrape` / `start_batch_scrape` | 启动批量任务并返回作业 ID，用于轮询或 Webhook |

<div id="basic-usage">
  ## 基本用法
</div>

<CodeGroup>
  <BatchScrapePython />

  <BatchScrapeNode />

  <BatchScrapeCURL />
</CodeGroup>

<div id="response">
  ### 响应
</div>

调用 `batchScrape` / `batch_scrape` 会在批处理完成后返回完整结果。

<BatchScrapeOutput />

调用 `startBatchScrape` / `start_batch_scrape` 会返回一个作业 ID。你可以通过 `getBatchScrapeStatus` / `get_batch_scrape_status`、API 端点 `/batch/scrape/{id}`，或 webhooks 来跟踪进度。作业结果在完成后会通过 API 保留 24 小时。在此之后，你仍然可以在[活动日志](https://www.firecrawl.dev/app/logs)中查看批量抓取历史和结果。

<BatchScrapeAsyncOutput />

<div id="concurrency">
  ## 并发
</div>

默认情况下，批量抓取作业会使用你团队的全部浏览器并发上限 (参见 [Rate Limits](/zh/rate-limits)) 。你可以通过 `maxConcurrency` 参数为每个作业降低并发数。

例如，`maxConcurrency: 50` 会将该作业限制为最多 50 个同时抓取。对于大批量作业，如果将这个值设得过低，会显著减慢处理速度，因此只有在你需要为其他并发作业预留容量时才应降低它。

<div id="structured-extraction">
  ## 结构化提取
</div>

你可以使用批量抓取，从该批次中的每个页面提取结构化数据。当你希望对一组 URL 应用相同的 schema 时，这会非常有用。

<CodeGroup>
  <BatchScrapeExtractPython />

  <BatchScrapeExtractNode />

  <BatchScrapeExtractCURL />
</CodeGroup>

<div id="response-2">
  ### 响应
</div>

`batchScrape` / `batch_scrape` 返回完整结果：

<BatchScrapeExtractOutput />

`startBatchScrape` / `start_batch_scrape` 返回任务 ID：

<BatchScrapeExtractAsyncOutput />

<div id="webhooks">
  ## Webhook
</div>

你可以配置 Webhook，在批次中的每个 URL 被抓取时接收实时通知。这样你可以立即处理结果，而无需等待整个批次完成。

<BatchScrapeWebhookCURL />

<div id="event-types">
  ### 事件类型
</div>

| 事件                       | 描述            |
| ------------------------ | ------------- |
| `batch_scrape.started`   | 批量抓取任务已开始     |
| `batch_scrape.page`      | 单个 URL 已成功抓取  |
| `batch_scrape.completed` | 所有 URL 均已处理完毕 |
| `batch_scrape.failed`    | 批量抓取任务遇到错误    |

<div id="payload">
  ### 载荷
</div>

每次 webhook 投递都包含一个 JSON 请求体，结构如下：

```json
{
  "success": true,
  "type": "batch_scrape.page",
  "id": "batch-job-id",
  "data": [...],
  "metadata": {},
  "error": null
}
```

<div id="verifying-webhook-signatures">
  ### 验证 webhook 签名
</div>

来自 Firecrawl 的每个 webhook 请求都会包含一个 `X-Firecrawl-Signature` 请求头，其中包含一个 HMAC-SHA256 签名。始终验证该签名，以确保 webhook 是真实的且未被篡改。

1. 在你账号设置中的 [Advanced 选项卡](https://www.firecrawl.dev/app/settings?tab=advanced) 获取你的 webhook secret
2. 从 `X-Firecrawl-Signature` 请求头中提取签名
3. 使用你的 secret 对原始请求体计算 HMAC-SHA256
4. 使用时间安全 (timing-safe) 的比较函数将其与签名请求头的值进行比较

<Warning>
  切勿在未先验证签名的情况下处理 webhook。`X-Firecrawl-Signature` 请求头中的签名格式为：`sha256=abc123def456...`
</Warning>

如需查看 JavaScript 和 Python 的完整实现示例，请参阅 [Webhook 安全文档](/zh/webhooks/security)。

如需查看更全面的 webhook 文档，包括详细的事件负载、高级配置和故障排查，请参阅 [Webhooks 文档](/zh/webhooks/overview)。

> 你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 获取自动化入门说明。