> 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/api-reference/cn/ren-wu-yu-fa-xian.md).

# 任务与发现

提交、批量处理和收集异步抓取任务的参考，以及在运行时列出端点和参数。

<table><thead><tr><th width="112.5">部分</th><th>端点</th></tr></thead><tbody><tr><td>请求</td><td><code>POST /v1/async/scrape/{path}</code>, <code>POST /v1/async/scrape/batch/{path}</code>, <code>GET /v1/async/scrape/{request_id}</code></td></tr><tr><td>发现</td><td><code>GET /v1/scrapers</code>, <code>OPTIONS /v1/{endpoint}</code></td></tr></tbody></table>

## 异步请求

### `POST /v1/async/scrape/{path}`

提交一个异步抓取请求。 `{path}` 是任意带有 `/v1/async/scrape/` 替代 `/v1/scrape/`.

**模式：** `async`

<table><thead><tr><th width="151">名称</th><th width="98">类型</th><th width="106.5">必填</th><th>描述</th></tr></thead><tbody><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>用于已完成请求的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应</td></tr><tr><td><code>storage.type</code></td><td>字符串</td><td>是，带有 <code>storage</code></td><td><code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>. 已验证</td></tr><tr><td><code>storage.url</code></td><td>字符串</td><td>是，带有 <code>storage</code></td><td>结果的目标位置。已验证 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>，以及 <code>tos</code>. 无效值返回 <code>400</code> 在请求创建之前</td></tr></tbody></table>

所有其他参数都是所提交端点的参数。

#### **响应** – `202 已接受`

<table><thead><tr><th width="207">字段</th><th width="95">类型</th><th>描述</th></tr></thead><tbody><tr><td><code>状态</code></td><td>字符串</td><td><code>待处理</code></td></tr><tr><td><code>参数</code></td><td>对象</td><td>按执行后的请求，已填充默认值</td></tr><tr><td><code>metadata.timestamp</code></td><td>整数</td><td>以秒为单位的 Unix 时间戳</td></tr><tr><td><code>metadata.request_id</code></td><td>字符串</td><td>请求 ID。用它来获取结果</td></tr></tbody></table>

### `POST /v1/async/scrape/batch/{path}`

为列表中的每个值提交一个请求。 `{path}` 是任意具有批处理模式的抓取路径。

**模式：** `batch`

<table><thead><tr><th width="131.5">名称</th><th width="93">类型</th><th width="158.5">必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串数组</td><td>是，如果该端点接收 <code>query</code></td><td>值，每个值一个请求</td></tr><tr><td><code>url</code></td><td>字符串数组</td><td>是，如果该端点接收 <code>url</code></td><td>URL，每个 URL 一个请求</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>每个已完成请求的 Webhook URL</td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>每个请求的 bucket 传送。字段与上面相同</td></tr></tbody></table>

所有其他参数都是所提交端点的参数，并适用于每个请求。对数组值使用单数形式的 `query` 或 `url` 字段。 `查询` 和 `URL` 不被接受。

#### **响应** – `202 已接受`

<table><thead><tr><th width="261">字段</th><th width="141.5">类型</th><th>描述</th></tr></thead><tbody><tr><td><code>data[]</code></td><td>数组</td><td>每个已接受请求一个对象。若没有接受任何请求则省略</td></tr><tr><td><code>errors[]</code></td><td>数组</td><td>每个被拒绝项一个错误对象。若没有拒绝任何项则省略</td></tr><tr><td><code>data[].state</code></td><td>字符串</td><td><code>待处理</code></td></tr><tr><td><code>data[].params</code></td><td>对象</td><td>按执行后的请求</td></tr><tr><td><code>data[].metadata.request_id</code></td><td>字符串</td><td>请求 ID</td></tr></tbody></table>

没有批处理收集路由：通过各自的 `request_id`. `/v1/scrape/batch` 返回 `404`.

### `GET /v1/async/scrape/{request_id}`

返回已提交请求的状态和结果。将 `metadata.request_id` 从提交响应中作为 `request_id` 路径参数发送。

#### **响应** – `200 OK`

<table><thead><tr><th width="118">字段</th><th width="76">类型</th><th>描述</th></tr></thead><tbody><tr><td><code>状态</code></td><td>字符串</td><td><code>待处理</code> 当请求处于队列中或运行中时， <code>完成</code> 当完成时</td></tr><tr><td><code>results[]</code></td><td>数组</td><td>与实时响应的结构相同。以下情况会填充 <code>状态</code> 为 <code>完成</code></td></tr></tbody></table>

未知或已过期的 `request_id` 返回 `404`.

## 发现

### `GET /v1/scrapers`

列出客户端已实现的实时抓取路径。

#### **响应** – `200 OK`

```json
{
  "scrapers": [
    "/v1/scrape",
    "/v1/scrape/amazon",
    "/v1/scrape/amazon/product",
    "/v1/scrape/google/search"
    ...
  ]
}
```

<table><thead><tr><th width="113">字段</th><th width="86.5">类型</th><th>描述</th></tr></thead><tbody><tr><td><code>scrapers</code></td><td>字符串数组</td><td>客户端可用的已实现实时抓取路径</td></tr></tbody></table>

### `OPTIONS /v1/{endpoint}`

返回某个端点的参数规范。该响应不是可执行的请求体。它列出可接受的参数，并标注其类型、是否必填、允许值、默认值、长度限制和描述。

`OPTIONS /v1/search` 不可用。

#### **响应** (`OPTIONS /v1/scrape`)

```json
{
  "url": "[字符串] [必填] [max_len: 8192]。要抓取的页面 URL。",
  "output": [
    "[字符串] [可选] [enum: html, screenshot, markdown, json] [default: html]。`html` 是页面源代码，`markdown` 是转换后的内容，`screenshot` 是 png，`json` 是解析后的数据。"
  ],
  "json": {
    "schema": "[JSON] [min_len: 10] [max_len: 65535]。抓取页面在 `json` 输出中解析成的 JSON Schema。不能与 `json.prompt` 同时使用。",
    "prompt": "[字符串] [max_len: 8192]。用于命名抓取页面在 `json` 输出中解析成的数据的提示词。不能与 `json.schema` 同时使用。"
  },
  "location": "[字符串] [可选]。抓取所在国家，使用 ISO 3166-1 alpha-2 代码表示，例如 `US`。",
  "device": "[字符串] [可选] [enum: desktop, mobile] [default: desktop]。抓取页面所渲染的设备。",
  "run_js": "[布尔] [可选]。在抓取前使用 JavaScript 渲染页面，`screenshot` 输出需要。"
}
```

#### **输出格式**

每个参数的值： `[类型] [必填或可选] [约束]。描述。`

<table><thead><tr><th width="297">标记</th><th>含义</th></tr></thead><tbody><tr><td><code>[字符串], [布尔], [整数], [JSON]</code></td><td>参数类型</td></tr><tr><td><code>[必填], [可选]</code></td><td>参数是否必须发送。并非每个参数都显示</td></tr><tr><td><code>[enum: a, b]</code></td><td>允许值</td></tr><tr><td><code>[default: x]</code></td><td>在省略参数时使用的值</td></tr><tr><td><code>[min_len: n], [max_len: n]</code></td><td>最小和最大长度</td></tr></tbody></table>

数组以包含元素注释的单元素数组显示。嵌套对象以对象显示。异步路径还列出 `storage` 和 `callback_url`.


---

# 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/api-reference/cn/ren-wu-yu-fa-xian.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.