> 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/parser-presets.md).

# 解析器预设

了解解析器预设的工作方式以及如何在抓取任务中使用它们。

你可以 **保存**, **复用**，以及 **修改** 通过网页爬虫API自定义解析指令。创建解析器预设后，我们会将其托管在我们的系统中，使你可以在抓取任务中通过 `parser_preset` 载荷中的参数。

此功能提供多个 **关键功能**:

* 在我们的系统上保存并管理你自己的解析器
* 在多个抓取任务中轻松复用预设
* 创建、检索、更新、删除并列出所有预设
* 访问某个预设的性能和使用统计数据
* 使用自我修复预设适应不断变化的网站

## API 参考

**端点：** `https://data.oxylabs.io/v1/parsers/presets`

下表列出每个可用操作及其端点路径：

<table><thead><tr><th width="247.30859375">操作</th><th width="152.23828125">请求方法</th><th>路径</th></tr></thead><tbody><tr><td><strong>创建</strong> 预设</td><td><code>POST</code></td><td><code>/v1/parsers/presets</code></td></tr><tr><td><strong>检索</strong> 预设</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>更新</strong> 预设</td><td><code>PUT</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>删除</strong> 预设</td><td><code>DELETE</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>列出所有</strong> 预设</td><td><code>GET</code></td><td><code>/v1/parsers/presets</code></td></tr><tr><td><strong>查看用量</strong> 和 <strong>性能</strong> 统计数据</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}/stats</code></td></tr><tr><td><strong>跟踪自我修复</strong> 变更</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}/changelog</code></td></tr></tbody></table>

## 启用自我修复

解析器预设配备了自我修复功能，可帮助在网站变化时维护解析器及其成功率。启用后，解析器预设 **会自动修复** 并在后台调整解析指令，无需额外的手动输入。

要 **启用自我修复** 用于你的自定义解析器预设，在创建或更新预设时请包含以下必需参数：

<table><thead><tr><th width="222.90234375">参数</th><th>说明</th></tr></thead><tbody><tr><td><code>self_heal</code></td><td>设置为 <code>True</code>.</td></tr><tr><td><code>prompt_schema</code></td><td>描述所需解析器输出的 JSON schema。你可以在 <a href="https://developers.oxylabs.io/products/cn/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md">使用 API 生成解析器时自动创建该 schema</a>.</td></tr><tr><td><code>urls</code></td><td>同一页面类型的最多 5 个 URL 列表。我们建议提供 3-5 个 URL，帮助解析器适应不同布局并提高解析准确率。</td></tr></tbody></table>

<details>

<summary>载荷示例</summary>

此处显示的载荷示例通过更新现有预设来启用自我修复。

**端点：** `PUT https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

```json
{
    "self_heal": true,
    "urls": ["https://sandbox.oxylabs.io/products"],
    "prompt_schema": {
        "properties": {
            "product_titles": {
                "description": "Title of each product.",
                "items": {
                    "type": "字符串"
                },
                "maxItems": 5,
                "title": "Product Titles",
                "type": "array"
            }
        },
        "required": [
            "product_titles"
        ],
        "title": "字段",
        "type": "对象"
    }
}
```

</details>

## 使用示例

### 创建预设

**端点：** `POST https://data.oxylabs.io/v1/parsers/presets`

{% hint style="info" %}
预设名称只能包含字母、数字、下划线和连字符，并且在你的账户中必须唯一。使用已存在的名称创建预设将返回 `400 - Parser preset already exists`.
{% endhint %}

**载荷：**

```json
{
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": ["//h4/text()"],
                    "_fn": "xpath"
                }
            ]
        }
    }
}
```

<details>

<summary>输出</summary>

```json
{
    "id": 424707,
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": [
                        "//h4/text()"
                    ],
                    "_fn": "xpath"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "last_used_at": null,
    "total_results": null,
    "success_rate": null,
    "created_at": "2026-09-08 08:26:02",
    "updated_at": "2026-09-08 08:26:02"
}
```

</details>

### 使用预设

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

{% hint style="info" %}
新创建的预设最多可能需要约一分钟才能供 Realtime 和 Push-Pull 上的抓取任务使用。在此之前，引用该预设的请求将被拒绝，并返回 `400 - 提供的 parser_preset 不存在。`
{% endhint %}

**载荷：**

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

<details>

<summary>输出</summary>

```json
{
    "results": [
        {
            "content": {
                "titles": [
                    "The Legend of Zelda: Ocarina of Time",
                    "Super Mario Galaxy",
                    "Super Mario Galaxy 2",
                    "Metroid Prime",
                    "Super Mario Odyssey",
                    "Halo: Combat Evolved",
                    "The House in Fata Morgana - Dreams of the Revenants Edition -",
                    "NFL 2K1",
                    "Uncharted 2: Among Thieves",
                    "Tekken 3",
                    "The Legend of Zelda: The Wind Waker",
                    "Gran Turismo",
                    "Metal Gear Solid 2: Sons of Liberty",
                    "Grand Theft Auto Double Pack",
                    "Baldur's Gate II: Shadows of Amn",
                    "Tetris Effect: Connected",
                    "The Legend of Zelda Collector's Edition",
                    "Gran Turismo 3: A-Spec",
                    "The Legend of Zelda: A Link to the Past",
                    "The Legend of Zelda: Majora's Mask",
                    "The Last of Us",
                    "Persona 5 Royal",
                    "The Last of Us Remastered",
                    "The Legend of Zelda: Ocarina of Time 3D",
                    "Chrono Cross",
                    "Gears of War",
                    "Sid Meier's Civilization II",
                    "Halo 3",
                    "Ninja Gaiden Black",
                    "Super Mario Advance 4: Super Mario Bros. 3",
                    "Jet Grind Radio",
                    "Grim Fandango"
                ],
                "parse_status_code": 12000
            },
            "created_at": "2025-10-27 11:41:18",
            "updated_at": "2025-10-27 11:41:19",
            "page": 1,
            "url": "https://sandbox.oxylabs.io/products",
            "job_id": "7388540292158203905",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "preset",
            "parser_preset": "my_new_parser"
        }
    ]
}
```

</details>

### 检索预设

**端点：** `GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

<details>

<summary>输出</summary>

```json
{
    "id": 424707,
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": [
                        "//h4/text()"
                    ],
                    "_fn": "xpath"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "last_used_at": null,
    "total_results": null,
    "success_rate": null,
    "created_at": "2026-09-08 08:26:02",
    "updated_at": "2026-09-08 08:26:02"
}
```

</details>

### 更新预设

**端点：** `PUT https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

定义你要更新的预设字段。在下面的示例中，只有 `parsing_instructions` 会被更新。

**载荷：**

```json
{
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": ["//h4/text()"],
                    "_fn": "xpath"
                }
            ]
        },
        "prices": {
            "_fns": [
                {
                    "_args": [".price-wrapper"],
                    "_fn": "css"
                },
                {"_fn": "element_text"}
            ]
        }
    }
}
```

<details>

<summary>输出</summary>

```json
{
    "id": 424707,
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "prices": {
            "_fns": [
                {
                    "_args": [
                        ".price-wrapper"
                    ],
                    "_fn": "css"
                },
                {
                    "_fn": "element_text"
                }
            ]
        },
        "titles": {
            "_fns": [
                {
                    "_args": [
                        "//h4/text()"
                    ],
                    "_fn": "xpath"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "last_used_at": null,
    "total_results": null,
    "success_rate": null,
    "created_at": "2026-09-08 08:26:02",
    "updated_at": "2026-09-08 08:26:27"
}
```

</details>

### 删除预设

**端点：** `DELETE https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

{% hint style="info" %}
成功删除后会返回 `204 No Content`。之后检索该预设会返回 `404`.
{% endhint %}

### 列出所有预设

**端点：** `GET https://data.oxylabs.io/v1/parsers/presets`

<details>

<summary>输出</summary>

```json
[
    {
        "id": 424710,
        "name": "books_parser",
        "description": "Parses all book titles on the page.",
        "prompt_text": null,
        "prompt_schema": null,
        "urls": [],
        "render": false,
        "parsing_instructions": {
            "titles": {
                "_fns": [
                    {
                        "_args": [
                            "//h3//text()"
                        ],
                        "_fn": "xpath"
                    }
                ]
            }
        },
        "self_heal": false,
        "heal_status": "disabled",
        "last_healed_at": null,
        "last_used_at": null,
        "total_results": null,
        "success_rate": null,
        "created_at": "2026-09-08 08:26:02",
        "updated_at": "2026-09-08 08:26:02"
    },
    {
        "id": 424707,
        "name": "my_new_parser",
        "description": "Extract text from all H4 elements on the page.",
        "prompt_text": null,
        "prompt_schema": null,
        "urls": [],
        "render": false,
        "parsing_instructions": {
            "prices": {
                "_fns": [
                    {
                        "_args": [
                            ".price-wrapper"
                        ],
                        "_fn": "css"
                    },
                    {
                        "_fn": "element_text"
                    }
                ]
            },
            "titles": {
                "_fns": [
                    {
                        "_args": [
                            "//h4/text()"
                        ],
                        "_fn": "xpath"
                    }
                ]
            }
        },
        "self_heal": false,
        "heal_status": "disabled",
        "last_healed_at": null,
        "last_used_at": null,
        "total_results": null,
        "success_rate": null,
        "created_at": "2026-09-08 08:26:02",
        "updated_at": "2026-09-08 08:26:27"
    }
]
```

</details>

### 查看统计数据

**端点：** `GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}/stats`

<details>

<summary>输出</summary>

```json
{
    "total_results": 9,
    "successful_results": 9,
    "success_rate": 100,
    "success_rate_by_path": {
        "titles": 100
    }
}
```

</details>

你可以 **按日期和时间筛选结果** 使用 `date_from` 和/或 `date_to` URL 参数。使用格式 `YYYY-MM-DDTHH`，其中 `T` 表示时间， `HH` 是 24 小时制的小时。

例如，要获取 2025 年 8 月 5 日上午 9 点到下午 2 点的统计数据：

```url
https://data.oxylabs.io/v1/parsers/presets/{preset_name}/stats?date_from=2025-08-05T9&date_to=2025-08-05T14
```

### 跟踪自我修复变更

**端点：** `GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}/changelog`

我们的系统会自动记录自我修复活动。你可以访问这份历史日志，查看自我修复功能所做的所有修改。未曾修复过的预设会返回空日志：

<pre><code>{
    "log": []
<strong>}
</strong></code></pre>


---

# 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-scraper-api/features/custom-parser/parser-presets.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.
