解析器预设

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

你可以 保存, 复用，并且 修改 通过网页爬虫API使用自定义解析指令。创建解析器预设后，我们会将其托管在我们的系统中，使你能够在抓取任务中通过 parser_preset 请求体中的参数进行引用。

此功能提供若干 关键能力:

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

API 参考

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

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

操作	请求方法	路径
创建 一个预设	POST	/v1/parsers/presets
检索 一个预设	GET	/v1/parsers/presets/{preset_name}
更新 一个预设	PUT	/v1/parsers/presets/{preset_name}
删除 一个预设	DELETE	/v1/parsers/presets/{preset_name}
列出所有 预设	GET	/v1/parsers/presets
查看使用 和 性能 统计	GET	/v1/parsers/presets/{preset_name}/stats
跟踪自愈 变更	GET	/v1/parsers/presets/{preset_name}/changelog

启用自愈

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

要 启用自愈 你的自定义解析器预设，请在创建或更新预设时包含以下必填参数：

参数	描述
self_heal	设置为 True.
prompt_schema	描述所需解析器输出的 JSON schema。你可以在 通过 API 生成解析器时.
urls	同一页面类型的最多 5 个 URL 列表。我们建议提供 3-5 个 URL，以帮助解析器适应不同布局并提高解析准确率。

载荷示例

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

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

{
    "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"
    }
}

使用示例

创建预设

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

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

载荷：

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

输出

{
    "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"
}

使用预设

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

新创建的预设在 Realtime 和 Push-Pull 中最多需要约一分钟才能可供抓取任务使用。在此之前，引用它的请求会被拒绝，并返回 400 - Provided parser_preset does not exist.

载荷：

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

输出

{
    "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"
        }
    ]
}

检索一个预设

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

输出

{
    "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"
}

更新一个预设

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

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

载荷：

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

输出

{
    "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"
}

删除一个预设

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

删除成功将返回 204 No Content。随后检索该预设将返回 404.

列出所有预设

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

输出

[
    {
        "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"
    }
]

查看统计

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

输出

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

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

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

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

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

{
    "log": []
}