Primeiros passos

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

Como usar o Custom Parser

Exemplo de cenário

Extraia o preço do primeiro produto listado em um site de e-commerce, https://sandbox.oxylabs.io/products?q=super+mario:

Há três maneiras de criar um parser. Esta página mostra a mais rápida, OxyCopilot, e as outras duas são abordadas em páginas próprias:

• Gerar parsers com OxyCopilot
• Gerar parsers via API
• Escrever instruções de parsing manualmente

Gerar parsers com OxyCopilot

O OxyCopilot permite que você descreva suas necessidades em inglês simples para criar automaticamente scrapers e parsers para um site. Aprenda o básico seguindo as etapas abaixo e confira a documentação do OxyCopilot para mais informações.

Abra o Playground do Web Scraper API 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 e clique em Avançar. Vamos usar esta URL sandbox: https://sandbox.oxylabs.io/products?q=super+mario.

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

2

Configure os parâmetros do scraper

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

A página sandbox não precisa de renderização de JavaScript, então mantenha os padrões e clique em Avançar.

A renderização é importante quando os dados que você quer não estão no HTML que o servidor envia, mas são adicionados por JavaScript depois que a página carrega, como é comum em preços, listagens de produtos e avaliações. Sem renderização, Custom Parser vê apenas o HTML inicial, então instruções que apontam para esses dados não retornam nada. Leia mais sobre renderização de JavaScript.

3

Escreva o prompt

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

Cole o prompt a seguir para extrair o preço do primeiro produto:

Extraia o preço do primeiro produto na página.

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

4

Revise os dados e as instruções analisados

Quando o OxyCopilot terminar, você verá a janela a seguir, onde os dados analisados estão no lado direito:

Se quiser fazer algum ajuste, você pode fazer isso aqui. Modifique a URL(s), refine o prompt, ative a renderização de JavaScript ou edite o esquema de parsing para atender às suas necessidades. Quando você atualizar qualquer campo nesta janela, pode executar a solicitação novamente selecionando Iniciar nova solicitaçã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 parserIsso permite reutilizar o preset no OxyCopilot e com suas solicitações de API.

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

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

6

Usar o preset com solicitações de API

Para usar um preset com suas solicitações do Web Scraper API, defina parse como true e especifique o nome do preset com o parâmetro parser_preset .

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

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

Ao executar a solicitação, você obterá a seguinte saída JSON:

{
    "results": [
        {
            "_request": {...},
            "_response": {...},
            "content": {
                "parse_status_code": 12000,
                "price": 91.99
            },
            "created_at": "2026-09-08 11:21:03",
            "is_render_forced": false,
            "job_id": "7503049765014236161",
            "page": 1,
            "parser_preset": "sandbox_first_product_price",
            "parser_type": "preset",
            "session_info": {...},
            "status_code": 200,
            "type": "parsed",
            "updated_at": "2026-09-08 11:21:09",
            "url": "https://sandbox.oxylabs.io/products"
        }
    ]
}

Uso avançado

O OxyCopilot é a maneira mais rápida de criar um parser, mas cada etapa dele também está disponível diretamente pela API:

• Gerar instruções de parsing via API – envie um prompt ou um esquema JSON junto com algumas URLs de exemplo e receba instruções prontas para uso. Veja Gerando instruções de parsing via API.
• Salvar e gerenciar presets via API – crie, atualize, liste e exclua presets de parser e habilite a auto-recuperação. Veja Presets de parser.
• Escrever instruções de parsing manualmente – monte seu próprio pipeline de extração com XPath e seletores CSS. Comece com Como escrever instruções de parsing, depois navegue pelos Exemplos de instruções de parsing.

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

Se o Custom Parser não conseguir aplicar uma de suas instruções, o job ainda será concluído com sucesso: o resultado traz parse_status_code (processado com avisos) e uma lista parse_status_code 12005 (processado com avisos) e uma _warnings descrevendo qual instrução falhou e por quê. Você é cobrado por esses resultados.

Por exemplo, esta solicitação pede um campo cujo XPath não corresponde a nada na página:

{
    "source": "universal",
    "url": "https://sandbox.oxylabs.io/products",
    "parse": true,
    "parsing_instructions": {
        "first_product_price": {
            "_fns": [
                {
                    "_fn": "xpath_one",
                    "_args": [
                        "//div[contains(@class, 'price-wrapper')]/text()"
                    ]
                },
                {
                    "_fn": "amount_from_string"
                }
            ]
        },
        "number_of_reviews": {
            "_fns": [
                {
                    "_fn": "xpath",
                    "_args": [
                        "//this-will-not-match-anything"
                    ]
                },
                {
                    "_fn": "length"
                }
            ]
        }
    }
}

O preço é extraído normalmente, o campo com falha é retornado como null, com um aviso:

{
    "results": [
        {
            "_request": {...},
            "_response": {...},
            "content": {
                "_warnings": [
                    {
                        "_fn": "xpath",
                        "_fn_idx": 0,
                        "_msg": "As expressões XPath não corresponderam a nenhum dado.",
                        "_path": ".number_of_reviews"
                    }
                ],
                "first_product_price": 91.99,
                "number_of_reviews": null,
                "parse_status_code": 12005
            },
            "created_at": "2026-09-08 09:00:40",
            "is_render_forced": false,
            "job_id": "7503014433245923329",
            "page": 1,
            "parser_preset": null,
            "parser_type": "custom",
            "session_info": {...},
            "status_code": 200,
            "type": "parsed",
            "updated_at": "2026-09-08 09:00:44",
            "url": "https://sandbox.oxylabs.io/products"
        }
    ]
}

Para ignorar um campo com falha em vez de receber um aviso, veja Exemplos de instruções de parsing › Tratamento de erros.

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

Instruções que fazem referência a uma função inexistente são rejeitadas no envio e nenhum job é criado. A API retorna um HTTP 400 erro nomeando a função ausente e seu caminho: a função not_a_real_fn não está definida.

Códigos de status

Veja nossos códigos de status descritos aqui.