> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-api/scrape/jiao-fu-mo-shi.md).

# 交付模式

了解 Web API 如何交付结果：Realtime 响应、带轮询或回调的异步任务、云存储交付及批量请求。

Web API 提供三种交付模式，以满足不同的工作负载需求和执行量。 

<table><thead><tr><th width="315">交付</th><th width="92">最大条目数</th><th width="143">目标</th><th width="215">用于...</th></tr></thead><tbody><tr><td><a href="#realtime"><strong>Realtime</strong></a> (同步)<br><code>POST /v1/scrape/{source}</code></td><td>1</td><td>所有端点</td><td>低延迟请求、测试</td></tr><tr><td><a href="#single-job-delivery-async"><strong>异步单任务</strong></a> (轮询)<br><code>POST /v1/async/scrape/{source}</code></td><td>1</td><td>所有端点</td><td>高并发和大流量</td></tr><tr><td><a href="#batch-delivery-async"><strong>异步批量</strong></a> (批量队列)<br><code>POST /v1/async/scrape/batch/{source}</code></td><td>5,000</td><td>选择端点</td><td>批量提交</td></tr></tbody></table>

大多数 `/scrape` 端点可作为 **Realtime** 和 **异步** 结果交付，由路径决定你何时以及如何获取结果。

```http
POST /v1/scrape/...          # realtime: the result is the response
POST /v1/async/scrape/...    # async: create a job and retrieve the result separately
```

## Realtime

```http
POST /v1/scrape/{source}
```

Realtime 交付会在初始 HTTP 连接上处理抓取。请求会阻塞，直到渲染、访问解析和解析完成，并在响应体中返回内容载荷。请将客户端超时设置为至少 150 秒。

```bash
curl -X POST https://webapi.oxylabs.io/v1/scrape/amazon/product \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "query": "B0CX23V2ZK",
    "domain": "com",
    "output": ["json"]
  }'
```

{% hint style="info" %}
某些端点不支持 Realtime 交付（例如 YouTube 下载、ChatGPT、Gemini、Perplexity）。请通过 [端点发现](/products/cn/web-api/scrape/duan-dian-fa-xian.md) 或查看 [API 参考](https://developers.oxylabs.io/api-reference).
{% endhint %}

## 单任务交付（异步）

```http
POST /v1/async/scrape/{source}
```

异步单任务交付会将抓取请求入队，并立即返回一个 HTTP `202 Accepted` 状态，其中包含作业标识符。

```bash
curl https://webapi.oxylabs.io/v1/async/scrape/media/youtube/metadata \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{"query": "a1cWkClBXLI", "output": ["json"]}'
```

当作业被接受时，作业 ID 会返回在 `metadata.request_id`.

```json
{
  "status": "pending",
  "params": { "query": "a1cWkClBXLI", "output": ["json"] },
  "metadata": { "timestamp": 1787599164, "request_id": "7497734325668954113" }
}
```

提交作业的状态可通过 `状态` 结果：

<table data-header-hidden><thead><tr><th width="172"></th><th></th></tr></thead><tbody><tr><td><code>status: "pending"</code></td><td>作业正在排队或执行中。 <code>结果</code> 数组保持为空（<code>[]</code>).</td></tr><tr><td><code>status: "done"</code></td><td>作业已完成。 <code>结果</code> 数组包含解析后的输出。</td></tr><tr><td><code>status: "faulted"</code></td><td>提取失败。请检查 <code>results[].metadata.status_code</code> 了解详情。</td></tr></tbody></table>

### 结果获取

结果可通过以下方式获取： [轮询](#option-a-polling-endpoint-get-v1-async-scrape-jobid), [webhooks](#option-b-webhooks-callback_url) （回调 URL），或直接通过 [云存储上传](#option-c-cloud-bucket-upload-storage).

#### **轮询端点（`GET /v1/async/scrape/{jobId}`)**

请将数字 `metadata.request_id` 传给轮询端点。

```bash
curl -X GET https://webapi.oxylabs.io/v1/async/scrape/7497971512142465025 \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY"
```

#### **Webhooks（`callback_url`)**

在初始请求体中包含 `callback_url` 。一旦执行转为 `done` 或 `faulted`，API 会向 `POST` 发送包含作业结果的载荷到你指定的端点。

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "callback_url": "https://your-api.example.com/webhooks-oxylabs"
}
```

提交时会验证 URL，格式错误的 URL 会被拒绝，错误为 `400`.

#### **云存储上传（`storage`)**

`storage` 将结果写入存储桶，而不是响应体。仅适用于 Async 路径。

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "s3",
    "url": "s3://your-bucket-name/scraped-data/B0CX23V2ZK.json"
  }
}
```

| 字段             | 值                                              |
| -------------- | ---------------------------------------------- |
| `storage.type` | `s3`, `s3_gzip`, `s3_compatible`, `gcs`, `tos` |
| `storage.url`  | 结果的目标位置                                        |

{% hint style="danger" %}
**`storage.url` 不会进行验证。** 格式错误或拼写错误的目标位置也会被接受，作业会执行，并按交付失败计费。

**`storage.type` 会与上面的列表进行比对。** 类型不正确会导致你获得 `400`。在使用批量前，先用单个请求测试一次目标。
{% endhint %}

## 批量交付（异步）

{% hint style="warning" %}
批量路由仅适用于部分 `/scrape` 来源。请通过 [端点发现](/products/cn/web-api/scrape/duan-dian-fa-xian.md) 或查看 [API 参考](https://developers.oxylabs.io/api-reference).
{% endhint %}

```http
POST /v1/async/scrape/batch/{source}
```

批量交付会在单个 HTTP 请求中提交最多 5,000 个抓取任务。而不是传入单个 `url` 或 `query` 字符串，输入字段接受字符串数组。载荷中的其他所有字段都会应用到批量中的每个任务。

```bash
curl -X POST https://webapi.oxylabs.io/v1/async/scrape/batch/amazon/product \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "query": ["B0CX23V2ZK", "B09B33PQS9", "INVALID_ASIN_XYZ"],
    "domain": "com",
    "output": ["json"]
  }'
```

批量端点会返回一个 HTTP `202 Accepted` 状态，其中包含 `data[]` 以及一个 `errors[]` 数组，列出被拒绝的项目（例如，ASIN 格式无效或 URL 语法无效）。请参见下面示例：

<details>

<summary>输出示例</summary>

```json
{
  "data": [
    {
      "state": "pending",
      "params": {
        "query": "B0CX23V2ZK",
        "output": [
          "json"
        ],
        "json": {
          "schema": null,
          "prompt": null
        },
        "location": null,
        "device": "desktop",
        "run_js": null,
        "storage": {
          "type": null,
          "url": null
        },
        "callback_url": null,
        "client_notes": null,
        "domain": "com",
        "locale": null,
        "autoselect_variant": false,
        "check_empty_geo": null,
        "safe_search": true,
        "currency": null
      },
      "metadata": {
        "timestamp": 1790852882,
        "request_id": "7511381408825235457"
      }
    },
    {
      "state": "pending",
      "params": {
        "query": "B09B33PQS9",
        "output": [
          "json"
        ],
        "json": {
          "schema": null,
          "prompt": null
        },
        "location": null,
        "device": "desktop",
        "run_js": null,
        "storage": {
          "type": null,
          "url": null
        },
        "callback_url": null,
        "client_notes": null,
        "domain": "com",
        "locale": null,
        "autoselect_variant": false,
        "check_empty_geo": null,
        "safe_search": true,
        "currency": null
      },
      "metadata": {
        "timestamp": 1790852882,
        "request_id": "7511381408825229313"
      }
    }
  ],
  "errors": [
    {
      "detail": "ASIN should only contain alphanumeric values.",
      "pointer": "/query/2"
    }
  ]
}
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-api/scrape/jiao-fu-mo-shi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.