> 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-scraper-api/features/custom-parser/getting-started.md).

# 入门

学习使用 Oxylabs 自定义解析器。此页面包含完整示例、技巧，以及解析失败时的处理说明。

## 如何使用自定义解析器 <a href="#how-to-use-custom-parser" id="how-to-use-custom-parser"></a>

### 场景示例

解析 **第一个产品的价格** 在电商网站上列出的， **`https://sandbox.oxylabs.io/products?q=super+mario`**:

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FsyYKUF76MWH5no3UxjZW%2Fimage.png?alt=media&amp;token=9b40f065-61e3-447a-b72e-a68d1cdd385e" alt="" width="375"><figcaption></figcaption></figure>

创建解析器有三种方式。本页将介绍最快的一种，OxyCopilot，另外两种则在各自的页面中说明：

* [使用 OxyCopilot 生成解析器](#generate-parsers-with-oxycopilot)
* [通过 API 生成解析器](/products/cn/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md)
* [手动编写解析指令](/products/cn/web-scraper-api/features/custom-parser/writing-instructions-manually/tips-for-writing-xpath-expressions.md#how-to-write-parsing-instructions-inlineextension)

### 使用 OxyCopilot 生成解析器

OxyCopilot 让你可以用简单英语描述需求， **自动创建爬虫和解析器** 用于某个网站。按照下面的步骤学习基础知识，并查看 [OxyCopilot 文档](/products/cn/web-scraper-api/web-scraper-api-playground/oxycopilot.md#custom-parser-builder) 了解更多信息。

{% hint style="success" %}
打开 [**网页爬虫API Playground**](https://dashboard.oxylabs.io/en/api-playground) 在我们的控制面板中访问 OxyCopilot。
{% endhint %}

{% stepper %}
{% step %}

#### 输入 URL

点击 **OxyCopilot 按钮** 在左上角输入最多 3 个相同页面类型的 URL，然后点击 **下一步**。我们使用这个 sandbox URL： **`https://sandbox.oxylabs.io/products?q=super+mario`**.

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FFmFBG02HI7hRLK7L2cj5%2Fimage.png?alt=media&amp;token=9aaeebfb-2bad-443e-be66-2570235f3299" alt="" width="545"><figcaption></figcaption></figure>

{% hint style="info" %}
你也可以通过填写以下内容手动配置爬虫： **网站**, **爬虫**、 **URL** 字段，并调整 **其他参数** ，例如左侧菜单中的 JavaScript 渲染。
{% endhint %}
{% endstep %}

{% step %}

#### 设置爬虫参数

接下来，指定爬虫参数、浏览器指令，并在目标网站需要时启用 JavaScript 渲染。

sandbox 页面不需要 JavaScript 渲染，因此保持默认设置并点击 **下一步**.&#x20;

{% hint style="info" %}
当你想要的数据不在服务器发送的 HTML 中，而是在页面加载后由 JavaScript 添加时，渲染就很重要，这在价格、商品列表和评论中很常见。如果没有渲染，自定义解析器只能看到初始 HTML，因此针对这些数据的指令不会返回任何内容。了解更多关于 [**JavaScript 渲染**](/products/cn/web-scraper-api/features/js-rendering-and-browser-control.md#javascript-rendering).
{% endhint %}

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FnywZ0UXzVmsthQQmIbht%2Fimage.png?alt=media&amp;token=9be92716-53c5-4230-a6ba-b1484c532be7" alt="" width="470"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 编写提示词

说明你想从页面中提取的数据。请尽量具体并提供最重要的信息。你可以在我们的 [OxyCopilot 提示词库](https://oxylabs.io/resources/prompts-code-samples).

粘贴以下提示词以提取第一个产品的价格：

```
解析页面上第一个产品的价格。
```

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FOG3MoIvtLoulTzaPFq26%2Fimage.png?alt=media&amp;token=3565708a-082c-4e42-b62c-98f60ff73a73" alt="" width="470"><figcaption></figcaption></figure>

点击 **生成指令** 按钮发送你的提示词。
{% endstep %}

{% step %}

#### 查看解析数据和指令

OxyCopilot 完成后，你会看到如下窗口，解析数据位于右侧：

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2F8Yd8bNBQXPwscHKdSK1U%2Fimage.png?alt=media&amp;token=ce799a13-a229-43b6-9de9-36cfd4873990" alt=""><figcaption></figcaption></figure>

如果你想进行任何调整，可以在这里完成。修改 URL、优化提示词、启用 JavaScript 渲染，或 [编辑解析架构](/products/cn/web-scraper-api/web-scraper-api-playground/oxycopilot.md#step-2-optional-adjust-parsing-schema) 以满足你的需求。更新此窗口中的任意字段后，你可以通过选择 **开始新请求**.

你也可以 **查看并直接编辑解析指令** ：

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FvW521rQpr277NpSDPSP8%2Fimage.png?alt=media&amp;token=ecf24ec7-a5b6-42bc-877e-79d9187dcf39" alt=""><figcaption></figcaption></figure>

当你对结果满意后， **加载指令** 继续。

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2F2bVplkgKW67lmAd7zWS9%2Fimage.png?alt=media&amp;token=5c067a5e-0b0e-4d47-b28d-c96e07deedcf" alt="" width="469"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 将解析器保存为预设

你可以轻松将解析指令保存为 [解析器预设](/products/cn/web-scraper-api/features/custom-parser/parser-presets.md)。这样你就可以在 OxyCopilot 和 API 请求中重用该预设。

在网页爬虫API Playground 中，你可以选择为其保存预设的用户。设置完成后，只需点击 **保存**:

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FKuZLB7HY6298sZhClts8%2Fimage.png?alt=media&amp;token=f0429fc1-ad0a-4159-bf23-60b0bcccc25e" alt=""><figcaption></figcaption></figure>

将弹出一个窗口，提示你为预设命名并添加可选描述：

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FnpBJz2wlknd0kfAR1ayx%2Fimage.png?alt=media&amp;token=3e031dc5-3bd1-49a3-bdb8-81cb1473adc2" alt="" width="333"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 在 API 请求中使用预设

要在你的网页爬虫API 请求中使用预设，请将 `parse` 设为 `true` 并使用 `parser_preset` 参数指定预设名称。

**端点：** `POST https://realtime.oxylabs.io/v1/queries`

```json
{
    "source": "universal",
    "url": "https://sandbox.oxylabs.io/products",
    "parse": true,
    "parser_preset": "sandbox_first_product_price"
}
```

运行请求将返回以下 JSON 输出：

```json
{
    "results": [
        {
            "_request": {...},
            "_response": {...},
            "content": {
                "parse_status_code": 12000,
                "price": 91.99
            },
            "created_at": "2026-09-08 11:21:03",
            "is_render_forced": false,
            "job_id": "7503049765014236161",
            "page": 1,
            "parser_preset": "sandbox_first_product_price",
            "parser_type": "preset",
            "session_info": {...},
            "status_code": 200,
            "type": "parsed",
            "updated_at": "2026-09-08 11:21:09",
            "url": "https://sandbox.oxylabs.io/products"
        }
    ]
}

```

{% endstep %}
{% endstepper %}

## 高级用法

OxyCopilot 是创建解析器最快的方式，但其中每个步骤也都可以直接通过 API 实现：

* **通过 API 生成解析指令** —发送提示词或 JSON schema，并附上几个示例 URL，即可获得可直接使用的指令。参见 [**通过 API 生成解析指令**](/products/cn/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md).
* **通过 API 保存和管理预设** —创建、更新、列出和删除解析器预设，并启用自修复。参见 [**解析器预设**](/products/cn/web-scraper-api/features/custom-parser/parser-presets.md).
* **手动编写解析指令** —使用 XPath 和 CSS 选择器构建你自己的提取流程。先阅读 [**如何编写解析指令**](/products/cn/web-scraper-api/features/custom-parser/writing-instructions-manually.md)，然后浏览 [**解析指令示例**](/products/cn/web-scraper-api/features/custom-parser/writing-instructions-manually/parsing-instruction-examples.md).

## 使用自定义解析器时，如果解析失败会发生什么 <a href="#what-happens-if-parsing-fails-when-using-custom-parser" id="what-happens-if-parsing-fails-when-using-custom-parser"></a>

如果自定义解析器无法应用你的某条指令，任务仍然会成功：结果会包含 `parse_status_code` `12005` （带警告解析）以及一个 `_warnings` 列表，说明哪条指令失败以及原因。此类结果会计费。&#x20;

例如，此请求要求的字段的 XPath 在页面上没有匹配项：

```json
{
    "source": "universal",
    "url": "https://sandbox.oxylabs.io/products",
    "parse": true,
    "parsing_instructions": {
        "first_product_price": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [
                        "//div[contains(@class, 'price-wrapper')]/text()"
                    ]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        },
        "number_of_reviews": {
            "_fns": [
                {
                    "_fn": "xpath",
                    "_args": [
                        "//this-will-not-match-anything"
                    ]
                },
                {
                    "_fn": "length"
                }
            ]
        }
    }
}
```

价格会正常解析，失败的字段返回为 `null`，并带有警告：

```json
{
    "results": [
        {
            "_request": {...},
            "_response": {...},
            "content": {
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "_fn_idx": 0,
                        "_msg": "XPath expressions did not match any data.",
                        "_path": ".number_of_reviews"
                    }
                ],
                "first_product_price": 91.99,
                "number_of_reviews": null,
                "parse_status_code": 12005
            },
            "created_at": "2026-09-08 09:00:40",
            "is_render_forced": false,
            "job_id": "7503014433245923329",
            "page": 1,
            "parser_preset": null,
            "parser_type": "custom",
            "session_info": {...},
            "status_code": 200,
            "type": "parsed",
            "updated_at": "2026-09-08 09:00:44",
            "url": "https://sandbox.oxylabs.io/products"
        }
    ]
}
```

如需忽略失败字段而不是接收警告，请参见 [**解析指令示例 › 错误处理**](/products/cn/web-scraper-api/features/custom-parser/writing-instructions-manually/parsing-instruction-examples.md#error-handling).

如果自定义解析器在解析过程中遇到异常并中断，它可以返回状态码 `12002`, `12006`、 `12007`。这些意外错误不会计费。

引用不存在函数的指令会在提交时被拒绝，不会创建任务。API 会返回 HTTP `400` 错误，其中会指出缺失的函数及其路径：函数 `not_a_real_fn` 未定义。

## 状态码 <a href="#status-codes" id="status-codes"></a>

查看我们列出的状态码 [**此处**](/products/cn/web-scraper-api/response-codes.md#parsers).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/cn/web-scraper-api/features/custom-parser/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.