入门

学习使用 Oxylabs 自定义解析器。在本页中，您会找到全面的示例、技巧以及解析失败时的处理细节。

如何使用自定义解析器

场景示例

假设你想解析 总结果数 Bing Search 使用搜索词返回的结果 test:

我们将概述实现此目标的三种主要方法：

• 使用 OxyCopilot 生成解析器

• 通过 API 生成解析器

• 手动编写解析说明

使用 OxyCopilot 生成解析器

OxyCopilot 允许你用简明的英语描述需求，来 自动为网站创建爬虫和解析器 了解基础，请按照以下步骤操作，并查看 OxyCopilot 文档 以获取更多信息。

打开 Web Scraper API Playground 在我们的仪表板上访问 OxyCopilot。

1

输入要抓取和解析的 URL（或 URL 列表）

点击 OxyCopilot 按钮 在左上方并输入最多 3 个同类页面的 URL。我们使用此 Bing Search URL： https://www.bing.com/search?q=test.

你也可以通过填写 网站, 爬虫，和 URL 顶部的字段并在左侧菜单中调整 附加参数 例如启用 JavaScript 渲染，来手动配置爬虫。

2

设置爬虫参数

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

对于 Bing Search， 启用 JavaScript 渲染 然后点击 下一步.

3

编写提示

解释你想从页面提取的数据。确保描述详尽并提供最重要的信息。你可以在我们的 OxyCopilot 提示库.

中找到热门网站的提示示例。粘贴以下提示以从 Bing Search 页面中提取总结果数：

解析搜索结果的总数。

点击 生成指令 按钮以发送你的提示。

4

查看解析的数据和指令

OxyCopilot 完成后，你会看到如下窗口，解析的数据显示在右侧：

如果你想进行任何调整，可以在此处操作。修改 URL、优化提示、启用 Javascript 渲染，或 编辑解析模式 以满足你的需求。当你在此窗口中更新任何字段时，可通过选择 开始新请求.

重新运行请求。 你也可以 在这里：

查看并直接编辑解析指令 一旦对结果满意， 加载指令

5

以继续。

将解析器另存为预设 解析器预设你可以轻松将解析指令保存为一个

预设。这让你可以在 OxyCopilot 和 API 请求中重用该预设。 保存:

在 Web Scraper API Playground 中，你可以选择将预设保存到哪个用户。设置完成后，只需点击

6

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

在 API 请求中使用预设 parse to true 要在 Web Scraper API 请求中使用预设，设置 parser_preset 参数。

并使用下面的 POST https://data.oxylabs.io/v1/queries

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    端点：
}

"parser_preset": "Bing_total_results"

{
    "results": [
        {
            "content": {
                "parse_status_code": 12000,
                运行请求将返回如下 JSON 输出：
            },
            "total_search_results": 12000000
            "created_at": "2025-10-24 09:29:28",
            "page": 1,
            "updated_at": "2025-10-24 09:30:42",
            "url": "https://www.bing.com/search?q=test",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "preset",
            端点：
        }
    ]
}

"job_id": "7387419953164488705",

通过 API 生成解析器

高级用法 你可以不在 Playground 中使用 OxyCopilot，而是直接向 Web Scraper API 发送提示以生成解析器。请参阅 通过 API 生成解析指令

文档页面以了解更多信息。 我们建议 提供 3-5 个相同类型的 URL

并使用下面的 （例如，产品页面）。这有助于解析器适应不同布局并提高解析准确性。

{
    POST https://data.oxylabs.io/v1/parsers/generate-instructions/prompt
    "prompt_text": "Parse the number of total search results.",
    "urls": ["https://www.bing.com/search?q=test"],
}

输出

{
    "parsing_instructions": {
        "render": true
            "_fns": [
                {
                    "_args": [
                        "total_search_results": {
                    ],
                    "_fn": "xpath_one"
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    },
    "prompt_schema": {
        "properties": {
            "render": true
                "//span[contains(@class, 'count')]/text()"
                "description": "The number of total search results.",
                "type": "number"
            }
        },
        "required": [
            "title": "Total Search Results",
        ],
        "title": "字段",
        "type": "object"
    }
}

"total_search_results"

通过 API 保存解析器预设 解析器预设 Web Scraper API 允许你将解析指令保存为可重用的解析器预设。查看

并使用下面的 文档以查找可用操作列表和完整代码示例。

{
    POST https://data.oxylabs.io/v1/parsers/presets
    "parsing_instructions": {
        "render": true
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [
                        "total_search_results": {
                    ]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    }
}

输出

{
    "name": "Bing_total_results",
    POST https://data.oxylabs.io/v1/parsers/presets
    "id": 421938,
    "description": null,
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "parsing_instructions": {
        "render": true
            "_fns": [
                {
                    "_args": [
                        "total_search_results": {
                    ],
                    "_fn": "xpath_one"
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    },
    "render": false,
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "created_at": "2025-10-27 09:28:37",
}

"updated_at": "2025-10-27 09:28:37"

手动编写指令 parsing_instructions 要手动使用自定义解析器，在创建任务时包含一组 解析指令。 你可以使用

CSS 和 XPath 选择器 来定位 DOM 中的元素。 按照下面的分步示例学习基础，然后查看我们关于

手动编写指令

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        的深入指南以获取高级技巧和详细文档。
            "_fns": [
                {
                    "_fn": "xpath_one",
                    以 Bing Search 场景为例。任务参数如下所示：
                }
            ]
        }
    }
}

步骤 1。 您必须提供 "parse": true 参数。

步骤 2。 "number_of_results": { "_args": [".//span[@class='sb_count']/text()"] 字段。

解析指令必须在 "parsing_instructions" 中描述。

"_fns": [
    {
        "_fn": "xpath_one",
        以 Bing Search 场景为例。任务参数如下所示：
    }
]

上面的示例解析指令指定目标是从抓取的文档中解析搜索结果数量，并将结果放入

number_of_results xpath_one 字段。解析该字段的说明通过定义“流水线”给出：流水线描述了一系列要执行的数据处理函数。函数按列表中出现的顺序执行，并将前一个函数的输出作为下一个函数的输入。在上面的示例流水线中， 函数（可用函数完整列表 ）被使用。它允许你使用 XPath 表达式和 XSLT 函数处理 HTML 文档。作为函数参数，指定目标元素所在的确切路径： .//span[@class='sb_count']

。你也可以指示解析器选择目标元素中找到的

{
    "results": [
        {
            "content": {
                text()
                "parse_status_code": 12000
            },
            。
            上述示例任务的解析结果应如下所示：
            "page": 1,
            "updated_at": "2025-10-24 09:30:42",
            "number_of_results": "About 16,700,000 results",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "created_at": "2025-10-27 09:48:04",
            "parser_preset": null
        }
    ]
}

"updated_at": "2025-10-27 09:48:38",

"job_id": "7388511797231226881", "parsing_instructions" "parser_type": "custom", 自定义解析器不仅提供从抓取的 HTML 中提取文本，还可以执行基本的数据处理函数。 例如，上述解析指令提取了 amount_from_string 作为包含你可能不需要的额外关键字的文本。如果你想以数值类型获取给定

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        的深入指南以获取高级技巧和详细文档。
            "_fns": [
                {
                    "_fn": "xpath_one",
                    以 Bing Search 场景为例。任务参数如下所示：
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    }
}

。你也可以指示解析器选择目标元素中找到的

{
    "results": [
        {
            "content": {
                query=test
                "parse_status_code": 12000
            },
            的结果数量，可重用相同的解析指令并向现有流水线添加
            函数：
            "page": 1,
            "updated_at": "2025-10-24 09:30:42",
            "number_of_results": 14200000,
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "created_at": "2025-10-27 09:48:04",
            "parser_preset": null
        }
    ]
}

"created_at": "2025-10-27 10:00:36",

"updated_at": "2025-10-27 10:01:05", 12005 "job_id": "7388514950961963009",

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        的深入指南以获取高级技巧和详细文档。
            "_fns": [
                {
                    "_fn": "xpath_one",
                    以 Bing Search 场景为例。任务参数如下所示：
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        },
        当使用自定义解析器时，如果解析失败会发生什么
            "_fns": [
                {
                    "_fn": "xpath",
                    如果自定义解析器无法处理客户端定义的解析指令，我们将返回
                },
                {
                    "_fn": "length"
                }
            ]
        }
    }
}

状态码（带警告的解析）。

{
    "results": [
        {
            "content": {
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "number_of_organics": {
                        "_args": ["//this-will-not-match-anything"]
                        这类结果会产生费用：
                    }
                ],
                query=test
                "parse_status_code": 12005,
                "_msg": "XPath 表达式未匹配到任何数据。",
            },
            "_path": ".number_of_organics",
            "_fn_idx": 0
            "page": 1,
            "updated_at": "2025-10-24 09:30:42",
            "number_of_organics": null
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "created_at": "2025-10-27 09:48:04",
            "parser_preset": null
        }
    ]
}

"created_at": "2025-10-27 10:03:54", 12002, 12006, 12007"updated_at": "2025-10-27 10:04:22",

状态代码

"job_id": "7388515782126234625", 此处.