> 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="/products/cn/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md">通过 API 生成解析器时</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": "每个产品的标题。",
                "items": {
                    "type": "string"
                },
                "maxItems": 5,
                "title": "产品标题",
                "type": "array"
            }
        },
        "required": [
            "product_titles"
        ],
        "title": "字段",
        "type": "object"
    }
}
```

</details>

## 使用示例

### 创建预设

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

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

**载荷：**

```json
{
    "name": "my_new_parser",
    "description": "提取页面上所有 H4 元素的文本。",
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": ["//h4/text()"],
                    "_fn": "xpath"
                }
            ]
        }
    }
}
```

<details>

<summary>输出</summary>

```json
{
    "id": 424707,
    "name": "my_new_parser",
    "description": "提取页面上所有 H4 元素的文本。",
    "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 - Provided parser_preset does not exist.`
{% 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": "提取页面上所有 H4 元素的文本。",
    "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": "提取页面上所有 H4 元素的文本。",
    "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": "解析页面上的所有书名。",
        "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": "提取页面上所有 H4 元素的文本。",
        "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 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/parser-presets.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.