Primeiros passos

Aprenda a usar o Oxylabs Custom Parser. Nesta página, você encontrará exemplos abrangentes, dicas e detalhes sobre o que acontece se o parsing falhar.

Como usar o Custom Parser

Exemplo de cenário

Suponha que você queira extrair o número total de resultados que o Bing Search retorna para um termo de busca test:

Vamos apresentar as três principais maneiras de atingir esse objetivo:

• Gerar parsers com OxyCopilot

• Gerar parsers via API

• Escrever instruções de parsing manualmente

Gerar parsers com OxyCopilot

OxyCopilot permite descrever suas necessidades em inglês simples para criar automaticamente scrapers e parsers para um site. Aprenda o básico seguindo os passos abaixo e confira documentação do OxyCopilot para mais informações.

Abra o Web Scraper API Playground no nosso painel para acessar o OxyCopilot.

1

Insira a(s) URL(s)

Clique no botão OxyCopilot no canto superior esquerdo e insira até 3 URLs do mesmo tipo de página. Vamos usar esta URL do Bing Search: https://www.bing.com/search?q=test.

Você também pode configurar o scraper manualmente preenchendo os campos Website, Scraper, e URL no topo, e ajustando parâmetros adicionais como renderização de JavaScript no menu lateral esquerdo.

2

Configure os parâmetros do scraper

Em seguida, especifique os parâmetros do scraper, instruções do navegador e habilite a renderização de JavaScript se o site alvo exigir.

Para o Bing Search, ative a renderização de JavaScript e então clique Próximo.

3

Escreva o prompt

Explique os dados que você quer extrair de uma página. Seja descritivo e forneça as informações mais importantes. Você pode encontrar exemplos de prompts para sites populares em nossa biblioteca de prompts do OxyCopilot.

Cole o prompt a seguir para extrair o número total de resultados das páginas do Bing Search:

Extraia o número total de resultados de busca.

Clique no Gerar instruções botão para enviar seu prompt.

4

Revisar dados e instruções parseadas

Quando o OxyCopilot terminar, você verá a janela a seguir com os dados parseados no lado direito:

Se quiser fazer ajustes, você pode fazê‑los aqui. Modifique a(s) URL(s), refine o prompt, habilite a renderização de Javascript ou edite o esquema de parsing para atender às suas necessidades. Quando você atualizar qualquer campo nesta janela, pode rerodar a requisição selecionando Iniciar nova requisição.

Você também pode visualizar e editar diretamente as instruções de parsing aqui:

Quando estiver satisfeito com o resultado, Carregar instruções para continuar.

5

Salvar o parser como um preset

Você pode salvar facilmente suas instruções de parsing como um preset de parser. Isso permite reutilizar o preset no OxyCopilot e nas suas requisições de API.

No Web Scraper API Playground, você pode opcionalmente escolher o usuário para o qual salvar o preset. Quando estiver pronto, basta clicar Salvar:

Um pop-up aparecerá solicitando que você nomeie o preset e adicione uma descrição opcional:

6

Usar o preset em requisições de API

Para usar um preset nas suas requisições do Web Scraper API, defina parse para true e especifique o nome do preset com o 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"
}

Executar a requisição fornecerá o seguinte output 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 avançado

Gerar parsers via API

Em vez de usar o OxyCopilot no playground, você pode enviar prompts diretamente para o Web Scraper API e gerar parsers. Veja a página de Gerando instruções de parsing via API da documentação para saber mais.

Recomendamos fornecer 3-5 URLs do mesmo tipo (por exemplo, páginas de produto). Isso ajuda o parser a se adaptar a diferentes layouts e melhora a precisão do parsing.

Endpoint: 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"],
    "render": true
}

Saída

{
    "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": "O número total de resultados de busca.",
                "title": "Total Search Results",
                "type": "number"
            }
        },
        "required": [
            "total_search_results"
        ],
        "title": "Fields",
        "type": "object"
    }
}

Salvar presets de parser via API

O Web Scraper API permite salvar instruções de parsing como presets de parser reutilizáveis. Confira a documentação de Parser Presets para encontrar uma lista de ações disponíveis e exemplos 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"
                }
            ]
        }
    }
}

Saída

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

Escrever instruções manualmente

Para usar o Custom Parser manualmente, inclua um conjunto de parsing_instructions ao criar um job. Você pode usar seletores CSS e XPath para direcionar elementos no DOM.

Siga o exemplo passo a passo abaixo para aprender o básico, depois explore nosso guia aprofundado sobre escrever instruções manualmente para técnicas avançadas e documentação detalhada.

Vamos usar o cenário do Bing Search como exemplo. Os parâmetros do job ficariam assim:

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

Passo 1. Você deve fornecer o "parse": true parâmetro.

Passo 2. As instruções de parsing devem ser descritas no "parsing_instructions" campo.

As instruções de parsing de exemplo acima especificam que o objetivo é extrair o número de resultados de busca do documento raspado e colocar o resultado no campo number_of_results O campo. As instruções sobre como parsear o campo definindo uma “pipeline” são dadas como:

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

A pipeline descreve uma lista de funções de processamento de dados a serem executadas. As funções são executadas na ordem em que aparecem na lista e recebem a saída da função anterior como entrada.

Na pipeline de exemplo acima, a função xpath_one (lista completa de funções disponíveis) é usada. Ela permite processar um documento HTML usando expressões XPath e funções XSLT. Como argumento da função, especifique o caminho exato onde o elemento alvo pode ser encontrado: .//span[@class='sb_count']. Você também pode instruir o parser a selecionar o text() encontrado no elemento alvo.

O resultado parseado do job de exemplo acima deve ficar assim:

{
    "results": [
        {
            "content": {
                "number_of_results": "About 16,700,000 results",
                "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
        }
    ]
}

O Custom Parser não oferece apenas extração de texto de um HTML raspado, mas também pode executar funções básicas de processamento de dados.

Por exemplo, as instruções de parsing descritas anteriormente extraem number_of_results como um texto com palavras extras que você pode não precisar necessariamente. Se quiser obter o número de resultados para a dada query=test no tipo de dado numérico, você pode reutilizar as mesmas instruções de parsing e adicionar a função amount_from_string à 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"
                }
            ]
        }
    }
}

O resultado parseado do job de exemplo acima deve ficar assim:

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

O que acontece se o parsing falhar ao usar o Custom Parser

Se o Custom Parser falhar ao processar instruções de parsing definidas pelo cliente, retornaremos o 12005 código de status (parseado com avisos).

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

Você será cobrado por tais resultados:

{
    "results": [
        {
            "content": {
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "_msg": "As expressões XPath não corresponderam a nenhum dado.",
                        "_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
        }
    ]
}

Se o Custom Parser encontrar uma exceção e falhar durante a operação de parsing, ele pode retornar estes códigos de status: 12002, 12006, 12007. Você não será cobrado por esses erros inesperados.

Códigos de status

Veja nossos códigos de status descritos aqui.