documentação de Parser Presets

Saiba como os presets de parser funcionam e como usá-los em seus jobs de scraping.

Você pode salvar, reutilizar, e modificar instruções de parsing personalizadas por meio da Web Scraper API. Depois de criar um preset de parser, iremos hospedá-lo em nosso sistema, permitindo que você o referencie em seus jobs de scraping via o parser_preset parâmetro no payload.

Este recurso oferece várias capacidades principais:

• Salve e gerencie seus próprios parsers em nosso sistema

• Reutilize facilmente presets em múltiplos jobs de scraping

• Crie, recupere, atualize, exclua e liste todos os presets

• Acesse estatísticas de desempenho e uso de um preset

• Adapte-se a sites em mudança usando presets com self-healing

Referência da API

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

A tabela lista cada operação disponível e seu caminho de endpoint:

Ação	Método de Requisição	Caminho
Criar um preset	POST	/v1/parsers/presets
Recuperar um preset	GET	/v1/parsers/presets/{preset_name}
Atualizar um preset	PUT	/v1/parsers/presets/{preset_name}
Excluir um preset	DELETE	/v1/parsers/presets/{preset_name}
Listar todos presets	GET	/v1/parsers/presets
Ver uso e desempenho estatísticas	GET	/v1/parsers/presets/{preset_name}/stats
Acompanhar alterações de self-healing	GET	/v1/parsers/presets/{parser_name}/changelog

Habilitar self-healing

Presets de parser vêm com a função de self-healing, que ajuda a manter os parsers e suas taxas de sucesso conforme os sites mudam. Quando habilitado, os presets de parser se reparam automaticamente e ajustam as instruções de parsing em segundo plano sem necessidade de intervenção manual adicional.

Para habilitar o self-healing do seu preset de parser personalizado, inclua os seguintes parâmetros obrigatórios ao criar ou atualizar um preset:

Parâmetro	Descrição
self_heal	Ativa a funcionalidade de self-healing quando definido como True.
prompt_schema	Um esquema JSON descrevendo a saída de parser exigida. Você pode criar automaticamente o esquema ao gerar parsers com a API.
urls	Uma lista de até 5 URLs do mesmo tipo de página. Recomendamos fornecer 3-5 URLs para ajudar o parser a se adaptar a diferentes layouts e melhorar a precisão do parsing.

Exemplo de payload

O exemplo de payload mostrado aqui habilita o self-healing atualizando um 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 produto.",
                "items": {
                    "type": "string"
                },
                "maxItems": 5,
                "title": "Títulos de Produtos",
                "type": "array"
            }
        },
        "required": [
            "product_titles"
        ],
        "title": "Fields",
        "type": "object"
    }
}

Exemplos de uso

Criar um preset

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

Payload:

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

Saída

{
    "id": 421947,
    "name": "my_new_parser",
    "description": "Extrai texto de todos os elementos H4 na 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,
    "created_at": "2025-10-27 11:40:22",
    "updated_at": "2025-10-27 11:40:22"
}

Usar um preset

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

Payload:

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

Saída

{
    "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 um preset

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

Saída

{
    "id": 421947,
    "name": "my_new_parser",
    "description": "Extrai texto de todos os elementos H4 na 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,
    "created_at": "2025-10-27 11:40:22",
    "updated_at": "2025-10-27 11:40:22"
}

Atualizar um preset

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

Defina os campos do preset que você deseja atualizar. No exemplo a seguir, apenas o parsing_instructions será atualizado.

Payload:

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

Saída

{
    "id": 421947,
    "name": "my_new_parser",
    "description": "Extrai texto de todos os elementos H4 na 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,
    "created_at": "2025-10-27 11:40:22",
    "updated_at": "2025-10-27 11:44:24"
}

Excluir um preset

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

Listar todos os presets

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

Saída

[
    {
        "id": 421950,
        "name": "books_parser",
        "description": "Analisa todos os títulos de livros na 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,
        "created_at": "2025-10-27 11:46:59",
        "updated_at": "2025-10-27 11:46:59"
    },
    {
        "id": 421947,
        "name": "my_new_parser",
        "description": "Extrai texto de todos os elementos H4 na 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,
        "created_at": "2025-10-27 11:40:22",
        "updated_at": "2025-10-27 11:45:20"
    }
]

Ver estatísticas

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

Saída

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

Você pode filtrar resultados por data e hora usando os date_from e/ou date_to parâmetros de URL. Use o formato YYYY-MM-DDTHH, onde T indica o horário, e HH é a hora em formato de 24 horas.

Por exemplo, para obter estatísticas das 9h às 14h em 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

Acompanhar alterações de self-healing

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

Nosso sistema registra automaticamente a atividade de self-healing. Você pode acessar esse registro histórico para revisar todas as modificações feitas pela função de self-healing.