Preajustes de parser

Descubre cómo funcionan los preajustes de parser y cómo usarlos en tus trabajos de scraping.

Puedes guardar, reutilizar, y modificar instrucciones personalizadas de análisis a través de Web Scraper API. Una vez que crees un preset de parser, lo alojaremos en nuestro sistema, lo que te permitirá referenciarlo en tus trabajos de scraping mediante el parser_preset parámetro en el payload.

Esta función ofrece varias capacidades clave:

• Guarda y administra tus propios parsers en nuestro sistema
• Reutiliza fácilmente los presets en múltiples trabajos de scraping
• Crear, recuperar, actualizar, eliminar y listar todos los presets
• Acceder a estadísticas de rendimiento y uso de un preset
• Adaptarse a sitios cambiantes usando presets con auto-reparación

Referencia de API

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

La tabla enumera cada operación disponible y su ruta de endpoint:

Acción	Método de solicitud	Ruta
Crear un preset	POST	/v1/parsers/presets
Recuperar un preset	GET	/v1/parsers/presets/{preset_name}
Actualizar un preset	PUT	/v1/parsers/presets/{preset_name}
Eliminar un preset	DELETE	/v1/parsers/presets/{preset_name}
Listar todos presets	GET	/v1/parsers/presets
Ver uso y rendimiento estadísticas	GET	/v1/parsers/presets/{preset_name}/stats
Rastrear la auto-reparación cambios	GET	/v1/parsers/presets/{preset_name}/changelog

Activar la auto-reparación

Los presets de parser están equipados con la función de auto-reparación, que ayuda a mantener los parsers y sus tasas de éxito a medida que los sitios web cambian. Cuando está habilitada, los presets de parser se reparan automáticamente y ajustan las instrucciones de análisis en segundo plano sin entrada manual adicional.

Para habilitar la auto-reparación para tu preset de Custom Parser, incluye los siguientes parámetros obligatorios al crear o actualizar un preset:

Parámetro	Descripción
self_heal	Activa la funcionalidad de auto-reparación cuando se establece en True.
prompt_schema	Un esquema JSON que describe la salida requerida del parser. Puedes crear automáticamente el esquema al generar parsers con API.
urls	Una lista de hasta 5 URLs del mismo tipo de página. Recomendamos proporcionar de 3 a 5 URLs para ayudar al parser a adaptarse a diferentes diseños y mejorar la precisión del análisis.

Ejemplo de payload

El ejemplo de payload que se muestra aquí habilita la auto-reparación al actualizar un preset existente.

Endpoint: 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": "Título de cada producto.",
                "items": {
                    "type": "string"
                },
                "maxItems": 5,
                "title": "Títulos de productos",
                "type": "array"
            }
        },
        "required": [
            "product_titles"
        ],
        "title": "Campos",
        "type": "object"
    }
}

Ejemplos de uso

Crear un preset

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

Los nombres de los presets solo pueden contener letras, dígitos, guiones bajos y guiones, y deben ser únicos para tu cuenta. Crear un preset con un nombre existente devuelve 400 - El preset de parser ya existe.

Payload:

{
    "name": "my_new_parser",
    "description": "Extrae texto de todos los elementos H4 de la página.",
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": ["//h4/text()"],
                    "_fn": "xpath"
                }
            ]
        }
    }
}

Salida

{
    "id": 424707,
    "name": "my_new_parser",
    "description": "Extrae texto de todos los elementos H4 de la página.",
    "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"
}

Usar un preset

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

Un preset recién creado puede tardar hasta aproximadamente un minuto en estar disponible para los trabajos de scraping tanto en Realtime como en Push-Pull. Hasta entonces, las solicitudes que lo referencian se rechazan con 400 - El parser_preset proporcionado no existe.

Payload:

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

Salida

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

Recuperar un preset

Endpoint: GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}

Salida

{
    "id": 424707,
    "name": "my_new_parser",
    "description": "Extrae texto de todos los elementos H4 de la página.",
    "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"
}

Actualizar un preset

Endpoint: PUT https://data.oxylabs.io/v1/parsers/presets/{preset_name}

Define los campos del preset que quieres actualizar. En el siguiente ejemplo, solo las parsing_instructions se actualizarán.

Payload:

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

Salida

{
    "id": 424707,
    "name": "my_new_parser",
    "description": "Extrae texto de todos los elementos H4 de la página.",
    "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"
}

Eliminar un preset

Endpoint: DELETE https://data.oxylabs.io/v1/parsers/presets/{preset_name}

Una eliminación exitosa devuelve 204 No Content. Luego, recuperar el preset devuelve 404.

Listar todos los presets

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

Salida

[
    {
        "id": 424710,
        "name": "books_parser",
        "description": "Analiza todos los títulos de libros en la página.",
        "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": "Extrae texto de todos los elementos H4 de la página.",
        "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"
    }
]

Ver estadísticas

Endpoint: GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}/stats

Salida

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

Puedes filtrar los resultados por fecha y hora usando los date_from y/o date_to parámetros de URL. Usa el formato YYYY-MM-DDTHH, donde T indica la hora, y HH es la hora en formato de 24 horas.

Por ejemplo, para obtener estadísticas de 9 a. m. a 2 p. m. el 5 de agosto de 2025:

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

Rastrear los cambios de auto-reparación

Endpoint: GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}/changelog

Nuestro sistema registra automáticamente la actividad de auto-reparación. Puedes acceder a este registro histórico para revisar todas las modificaciones realizadas por la función de auto-reparación. Un preset que nunca ha sido reparado devuelve un registro vacío:

{
    "log": []
}