# Presets de parser

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:

<table><thead><tr><th width="247.30859375">Ação</th><th width="152.23828125">Método de Requisição</th><th>Caminho</th></tr></thead><tbody><tr><td><strong>Criar</strong> um preset</td><td><code>POST</code></td><td><code>/v1/parsers/presets</code></td></tr><tr><td><strong>Recuperar</strong> um preset</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>Atualizar</strong> um preset</td><td><code>PUT</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>Excluir</strong> um preset</td><td><code>DELETE</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>Listar todos</strong> presets</td><td><code>GET</code></td><td><code>/v1/parsers/presets</code></td></tr><tr><td><strong>Ver uso</strong> e <strong>desempenho</strong> estatísticas</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}/stats</code></td></tr><tr><td><strong>Acompanhar alterações de</strong> self-healing</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{parser_name}/changelog</code></td></tr></tbody></table>

## 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:

<table><thead><tr><th width="222.90234375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><code>self_heal</code></td><td>Ativa a funcionalidade de self-healing quando definido como <code>True</code>.</td></tr><tr><td><code>prompt_schema</code></td><td>Um esquema JSON descrevendo a saída de parser exigida. Você pode criar automaticamente o esquema ao <a href="generating-parsing-instructions-via-api">gerar parsers com a API</a>.</td></tr><tr><td><code>urls</code></td><td>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.</td></tr></tbody></table>

<details>

<summary>Exemplo de payload</summary>

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}`

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

</details>

## Exemplos de uso

### Criar um preset

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

**Payload:**

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

<details>

<summary>Saída</summary>

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

</details>

### Usar um preset

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

**Payload:**

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

<details>

<summary>Saída</summary>

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

</details>

### Recuperar um preset

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

<details>

<summary>Saída</summary>

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

</details>

### 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:**

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

<details>

<summary>Saída</summary>

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

</details>

### 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`

<details>

<summary>Saída</summary>

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

</details>

### Ver estatísticas

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

<details>

<summary>Saída</summary>

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

</details>

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:

```url
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.