Primeros pasos

Aprende a usar Oxylabs Custom Parser. En esta página encontrarás ejemplos completos, consejos y detalles sobre qué ocurre si falla el parsing.

Cómo usar Custom Parser

Ejemplo de escenario

Supongamos que quieres analizar el número total de resultados que devuelve Bing Search con un término de búsqueda test:

Veremos de forma general los tres métodos principales para lograr este objetivo:

• Generar analizadores con OxyCopilot

• Generar analizadores mediante API

• Escribir instrucciones de análisis manualmente

Generar analizadores con OxyCopilot

OxyCopilot te permite describir tus necesidades en inglés sencillo para crear automáticamente scrapers y analizadores para un sitio web. Aprende lo básico siguiendo los pasos que se indican a continuación y consulta la documentación de OxyCopilot para más información.

Abra la ventana de Web Scraper API Playground en nuestro panel para acceder a OxyCopilot.

1

Introduce la(s) URL(s)

Haz clic en el botón de OxyCopilot en la parte superior izquierda e introduce hasta 3 URL del mismo tipo de página. Usemos esta URL de Bing Search: https://www.bing.com/search?q=test.

También puedes configurar el scraper manualmente rellenando los Sitio web, campos de Scraper, y URL en la parte superior, y ajustando parámetros adicionales como la renderización de JavaScript en el menú de la izquierda.

2

Configurar los parámetros del scraper

A continuación, especifica los parámetros del scraper, las instrucciones del navegador y activa la renderización de JavaScript si tu sitio objetivo lo requiere.

Para Bing Search, activa la renderización de JavaScript y luego haz clic en Siguiente.

3

Escribe el prompt

Explica los datos que quieres extraer de una página. Asegúrate de ser descriptivo y proporcionar la información más importante. Puedes encontrar ejemplos de prompts para sitios web populares en nuestra biblioteca de prompts de OxyCopilot.

Pega el siguiente prompt para extraer el número total de resultados de las páginas de Bing Search:

Analiza el número total de resultados de búsqueda.

Haz clic en el Generar instrucciones botón para enviar tu prompt.

4

Revisar los datos analizados y las instrucciones

Una vez que OxyCopilot termine, verás la siguiente ventana donde los datos analizados están en el lado derecho:

Si quieres hacer algún ajuste, puedes hacerlo aquí. Modifica la(s) URL, refina el prompt, activa la renderización de JavaScript o edita el esquema de análisis para adaptarlo a tus necesidades. Cuando actualices cualquier campo en esta ventana, puedes volver a ejecutar la solicitud seleccionando Iniciar nueva solicitud.

También puedes ver y editar directamente las instrucciones de análisis aquí:

Una vez que estés conforme con el resultado, Cargar instrucciones para continuar.

5

Guardar el analizador como un preset

Puedes guardar fácilmente tus instrucciones de análisis como un preseteo del analizador. Esto te permite reutilizar el preset en OxyCopilot y con tus solicitudes de API.

En el Web Scraper API Playground, opcionalmente puedes elegir el usuario para el que guardar el preset. Una vez que esté todo listo, simplemente haz clic en Guardar:

Aparecerá una ventana emergente pidiéndote que nombres el preset y añadas una descripción opcional:

6

Usar el preset con solicitudes de API

Para usar un preset con tus solicitudes de Web Scraper API, configura parse a true y especifica el nombre del preset con el parser_preset parámetro.

Endpoint: POST https://data.oxylabs.io/v1/queries

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parser_preset": "Bing_total_results"
}

Al ejecutar la solicitud se obtendrá la siguiente salida JSON:

{
    "results": [
        {
            "content": {
                "parse_status_code": 12000,
                "total_search_results": 12000000
            },
            "created_at": "2025-10-24 09:29:28",
            "updated_at": "2025-10-24 09:30:42",
            "page": 1,
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7387419953164488705",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "preset",
            "parser_preset": "Bing_total_results"
        }
    ]
}

Uso avanzado

Generar analizadores mediante API

En lugar de usar OxyCopilot en el playground, puedes enviar prompts directamente a Web Scraper API y generar analizadores. Consulta la documentación sobre generación de instrucciones de análisis mediante API para aprender más.

Recomendamos proporcionar 3-5 URL del mismo tipo (por ejemplo, páginas de producto). Esto ayuda al analizador a adaptarse a diferentes diseños y mejora la precisión del análisis.

Endpoint: POST https://data.oxylabs.io/v1/parsers/generate-instructions/prompt

{
    "prompt_text": "Analiza el número total de resultados de búsqueda.",
    "urls": ["https://www.bing.com/search?q=test"],
    "render": true
}

Salida

{
    "parsing_instructions": {
        "total_search_results": {
            "_fns": [
                {
                    "_args": [
                        "//span[contains(@class, 'count')]/text()"
                    ],
                    "_fn": "xpath_one"
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    },
    "prompt_schema": {
        "properties": {
            "total_search_results": {
                "description": "El número total de resultados de búsqueda.",
                "title": "Resultados Totales de Búsqueda",
                "type": "number"
            }
        },
        "required": [
            "total_search_results"
        ],
        "title": "Campos",
        "type": "object"
    }
}

Guardar presets del analizador mediante API

Web Scraper API te permite guardar instrucciones de análisis como presets reutilizables. Consulta la Presets de analizador documentación para encontrar una lista de acciones disponibles y ejemplos de código completos.

Endpoint: POST https://data.oxylabs.io/v1/parsers/presets

{
    "name": "Bing_total_results",
    "parsing_instructions": {
        "total_search_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [
                        "//span[contains(@class, 'count')]/text()"
                    ]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    }
}

Salida

{
    "id": 421938,
    "name": "Bing_total_results",
    "description": null,
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "total_search_results": {
            "_fns": [
                {
                    "_args": [
                        "//span[contains(@class, 'count')]/text()"
                    ],
                    "_fn": "xpath_one"
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    },
    "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"
}

Escribir instrucciones manualmente

Para usar Custom Parser manualmente, incluye un conjunto de parsing_instructions al crear un trabajo. Puedes usar selectores CSS y XPath para apuntar a elementos en el DOM.

Sigue el ejemplo paso a paso a continuación para aprender lo básico, y luego explora nuestra guía detallada sobre escribir instrucciones manualmente para técnicas avanzadas y documentación detallada.

Tomemos el escenario de Bing Search como ejemplo. Los parámetros del trabajo se verían así:

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        "number_of_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [".//span[@class='sb_count']/text()"]
                }
            ]
        }
    }
}

Paso 1. Debes proporcionar el "parse": true parámetro.

Paso 2. Las instrucciones de análisis deben describirse en "parsing_instructions" .

Las instrucciones de análisis de ejemplo anteriores especifican que el objetivo es analizar el número de resultados de búsqueda del documento extraído y poner el resultado en el campo number_of_results . Las instrucciones sobre cómo analizar el campo definiendo una “pipeline” se dan como:

"_fns": [
    {
        "_fn": "xpath_one",
        "_args": [".//span[@class='sb_count']/text()"]
    }
]

La pipeline describe una lista de funciones de procesamiento de datos que se ejecutarán. Las funciones se ejecutan en el orden en que aparecen en la lista y toman la salida de la función anterior como entrada.

En la pipeline de ejemplo anterior, se usa la función xpath_one (lista completa de funciones disponibles). Permite procesar un documento HTML usando expresiones XPath y funciones XSLT. Como argumento de la función, especifica la ruta exacta donde se puede encontrar el elemento objetivo: .//span[@class='sb_count']. También puedes indicar al analizador que seleccione el text() encontrado en el elemento objetivo.

El resultado analizado del trabajo de ejemplo anterior debería verse así:

{
    "results": [
        {
            "content": {
                "number_of_results": "Aproximadamente 16,700,000 resultados",
                "parse_status_code": 12000
            },
            "created_at": "2025-10-27 09:48:04",
            "updated_at": "2025-10-27 09:48:38",
            "page": 1,
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7388511797231226881",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "custom",
            "parser_preset": null
        }
    ]
}

Custom Parser no solo ofrece extracción de texto de un HTML extraído, sino que también puede ejecutar funciones básicas de procesamiento de datos.

Por ejemplo, las instrucciones de análisis descritas anteriormente extraen number_of_results como texto con palabras clave adicionales que quizá no necesites necesariamente. Si quieres obtener el número de resultados para la query=test en el tipo de dato numérico, puedes reutilizar las mismas instrucciones de análisis y añadir la amount_from_string función al pipeline existente:

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        "number_of_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [".//span[@class='sb_count']/text()"]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        }
    }
}

El resultado analizado del trabajo de ejemplo anterior debería verse así:

{
    "results": [
        {
            "content": {
                "number_of_results": 14200000,
                "parse_status_code": 12000
            },
            "created_at": "2025-10-27 10:00:36",
            "updated_at": "2025-10-27 10:01:05",
            "page": 1,
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7388514950961963009",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "custom",
            "parser_preset": null
        }
    ]
}

Qué ocurre si falla el análisis al usar Custom Parser

Si Custom Parser no puede procesar las instrucciones de análisis definidas por el cliente, devolveremos el 12005 código de estado (analizado con advertencias).

{
    "source": "bing_search",
    "query": "test",
    "render": "html",
    "parse": true,
    "parsing_instructions": {
        "number_of_results": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [".//span[@class='sb_count']/text()"]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        },
        "number_of_organics": {
            "_fns": [
                {
                    "_fn": "xpath",
                    "_args": ["//this-will-not-match-anything"]
                },
                {
                    "_fn": "length"
                }
            ]
        }
    }
}

Se te cobrará por tales resultados:

{
    "results": [
        {
            "content": {
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "_msg": "XPath expressions did not match any data.",
                        "_path": ".number_of_organics",
                        "_fn_idx": 0
                    }
                ],
                "number_of_results": 14200000,
                "parse_status_code": 12005,
                "number_of_organics": null
            },
            "created_at": "2025-10-27 10:03:54",
            "updated_at": "2025-10-27 10:04:22",
            "page": 1,
            "url": "https://www.bing.com/search?q=test",
            "job_id": "7388515782126234625",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "custom",
            "parser_preset": null
        }
    ]
}

Si Custom Parser encuentra una excepción y falla durante la operación de análisis, puede devolver estos códigos de estado: 12002, 12006, 12007. No se te cobrará por estos errores inesperados.

Códigos de estado

Consulta nuestros códigos de estado descritos aquí.