> ## 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.

# Fetch API 端点

> 发送 Bright Data Fetch API 请求的可复制示例，涵盖单个 URL、国家定位、使用 custom_output_fields 选择字段以及异步批量请求。

本指南展示如何发送各类 Bright Data Fetch API 请求，包括单个 URL、国家定位、只返回部分字段以及异步批量请求。

## 前置条件

* 一个拥有有效 API 密钥的 [Bright Data 账户](https://www.bright.cn/?hs_signup=1\&utm_source=docs)
* 已完成[快速开始](/cn/products/scrapers/fetch-api/quickstart)

## 请求结构

每个同步请求都遵循相同的模式：

```http theme={null}
POST https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

[{"url": "https://..."}]
```

每个输入对象包含必填的 `url` 和可选的 `country`。Fetch API 只有一个端点，因此 `dataset_id` 始终为 `gd_m6gjtfmeh43we6cqc`。

<Note>
  `/scrape` 端点专为实时请求设计。Bright Data 建议每个请求不超过 20 个 URL，这是最佳实践，而非硬性限制，该端点最多等待 1 分钟。如果采集时间更长，响应将是 HTTP `202` 和 `snapshot_id`，而不是数据，采集会以异步方式继续。可通过[异步请求](/cn/products/scrapers/scrapers-library/async-requests)获取结果，或通过 [webhook 交付](/cn/products/scrapers/scrapers-library/data-delivery)推送给您。
</Note>

## 如何按 URL 获取网页

**数据集 ID：** `gd_m6gjtfmeh43we6cqc`

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com"}]'
```

您应该会看到 `200` 响应，其中一条记录包含 `markdown`、`html2text`、`page_html`、`page_title` 和 `final_url`。处理时间取决于目标网站的情况。

<Accordion title="示例响应">
  ```json theme={null}
  [
    {
      "markdown": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.",
      "url": "https://example.com/",
      "final_url": "https://example.com/",
      "html2text": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for\ntesting and monitoring purposes.",
      "page_html": "<!doctype html><html lang=en><head><meta charset=utf-8>...<title>Example Domain</title>...</head><body><p>This domain is for use in documentation examples without needing permission. ...</p></body></html>\n",
      "page_title": "Example Domain",
      "country": null,
      "timestamp": "2026-10-19T18:10:21.213Z",
      "input": {
        "url": "https://example.com"
      }
    }
  ]
  ```
</Accordion>

[完整响应结构](/cn/api-reference/scrapers/web-content-apis/fetch-api-collect-by-url)

## 如何从指定国家获取网页

在输入对象中添加 `country`，即可从该国家获取网页。请使用两位国家代码。以下请求分别从德国和美国获取 Google 首页：

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://www.google.com/", "country": "de"}, {"url": "https://www.google.com/", "country": "US"}]'
```

第一条记录为德语（"Über Google"），第二条为英语（"About"），说明每个网页都是从请求的国家获取的。

<Accordion title="示例响应">
  ```json theme={null}
  [
    {
      "markdown": "[Über Google](https://about.google/?fg=1&utm%5Fsource=google-DE&utm%5Fmedium=referral&utm%5Fcampaign=hp-header)[Store](https://store.google.com/DE?utm%5Fsource=...",
      "url": "https://www.google.com/",
      "final_url": "https://www.google.com/",
      "page_title": "Google",
      "country": null,
      "timestamp": "2026-10-19T18:10:23.654Z",
      "input": {
        "url": "https://www.google.com/",
        "country": "de"
      }
    },
    {
      "markdown": "[About](https://about.google/?fg=1&utm%5Fsource=google-US&utm%5Fmedium=referral&utm%5Fcampaign=hp-header)[Store](https://store.google.com/US?utm%5Fsource=...",
      "url": "https://www.google.com/",
      "final_url": "https://www.google.com/",
      "page_title": "Google",
      "country": "US",
      "timestamp": "2026-10-19T18:10:50.519Z",
      "input": {
        "url": "https://www.google.com/",
        "country": "US"
      }
    }
  ]
  ```

  此处的 `markdown` 值已截断，并省略了 `html2text` 和 `page_html`。
</Accordion>

<Note>
  请使用大写国家代码，例如 `US` 或 `DE`。使用 `de` 等小写代码时，仍会从该国家获取网页，但记录中的 `country` 字段会返回 `null`。
</Note>

## 如何只返回部分字段

将 `custom_output_fields` 查询参数设置为以竖线分隔的字段名列表。以下请求只返回 URL、标题和 Markdown：

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json&custom_output_fields=url|page_title|markdown" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com"}]'
```

<Accordion title="示例响应">
  ```json theme={null}
  [
    {
      "url": "https://example.com/",
      "page_title": "Example Domain",
      "markdown": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes."
    }
  ]
  ```
</Accordion>

不返回 `page_html` 可以在只需要为 LLM 提供文本时减小响应体积。

## 如何异步获取大量 URL

将相同的请求体发送到 `/trigger` 而不是 `/scrape`。Fetch API 会立即返回 `snapshot_id`，并在后台获取网页：

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com"}, {"url": "https://en.wikipedia.org/wiki/Web_scraping"}]'
```

<Accordion title="示例响应">
  ```json theme={null}
  {"snapshot_id":"sd_mvfklliu2mb3mi6l6y"}
  ```
</Accordion>

使用 `snapshot_id` 查看进度并下载记录，具体方法见[异步请求](/cn/products/scrapers/scrapers-library/async-requests)。

## 快速参考

| 请求 | 端点 | 关键参数 |
| :- | :- | :- |
| 一个或少量 URL | `/datasets/v3/scrape` | `url` |
| 国家定位 | `/datasets/v3/scrape` | `country`，大写代码 |
| 只返回部分字段 | `/datasets/v3/scrape` | `custom_output_fields` |
| 大批量 | `/datasets/v3/trigger` | `url`，返回 `snapshot_id` |

四种请求都使用数据集 ID `gd_m6gjtfmeh43we6cqc`。

## 输出格式

通过 `format` 查询参数控制响应格式：

| 值 | 说明 |
| :- | :- |
| `json` | JSON 数组 |
| `ndjson` | 换行分隔的 JSON，每行一条记录（默认） |
| `csv` | 逗号分隔值 |

以上是 `/scrape` 支持的 `format` 值。完整列表，即 NDJSON（默认）、JSON、JSON lines、CSV 和 Parquet，以及各自的适用场景，请参阅[输出格式](/cn/products/scrapers/scrapers-library/data-delivery#支持哪些输出格式)。

## 相关内容

<CardGroup cols={2}>
  <Card title="异步批量请求" icon="layer-group" href="/cn/products/scrapers/scrapers-library/async-requests">
    在单个批处理作业中获取数百个 URL。
  </Card>

  <Card title="API 参考" icon="code" href="/cn/api-reference/scrapers/web-content-apis/fetch-api-collect-by-url">
    完整的参数和响应字段参考。
  </Card>
</CardGroup>