Começando

Aprenda a usar o Oxylabs Custom Parser. 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

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

Vamos apresentar os três principais métodos para alcançar esse objetivo:

• 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 os passos abaixo e confira a documentação do OxyCopilot para mais informações.

Abra a janela Web Scraper API Playground no nosso dashboard para acessar o OxyCopilot.

1

Insira a(s) URL(s)

Clique no botão do 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 Site, campos do Scraper, e URL na parte superior e ajustando parâmetros adicionais como a renderização JavaScript no menu à esquerda.

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 JavaScript se o site de destino exigir isso.

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

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 prompts para sites populares na 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:

Analise o número total de resultados de busca.

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

4

Revise os dados analisados e as instruções

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

Se quiser fazer algum ajuste, você pode fazer isso aqui. Modifique a(s) URL(s), refine o prompt, ative a renderização JavaScript ou edite o esquema de parsing conforme suas necessidades. Quando você atualizar quaisquer campos nesta janela, você pode executar a solicitação novamente selecionando Iniciar nova solicitação.

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

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

5

Salve o parser como predefinição

Você pode salvar facilmente suas instruções de parsing como uma preset do parser. Isso permite reutilizar a predefinição no OxyCopilot e nas suas solicitações de API.

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

Um pop-up aparecerá pedindo que você nomeie a predefinição e adicione uma descrição opcional:

6

Use a predefinição com solicitações de API

Para usar uma predefinição com suas solicitações da Web Scraper API, defina parse até true e especifique o nome da predefinição 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 solicitação fornecerá a seguinte saída 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 a Web Scraper API e gerar parsers. Veja a página de documentação Gerando instruções de parsing via API para saber mais.

Recomendamos fornecer 3 a 5 URLs do mesmo tipo (por exemplo, páginas de produtos). 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": "Analise o número total de resultados de busca.",
    "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": "Resultados totais da busca",
                "type": "number"
            }
        },
        "required": [
            "total_search_results"
        ],
        "title": "Campos",
        "type": "object"
    }
}

Salvar predefinições de parser via API

A Web Scraper API permite salvar instruções de parsing como predefinições de parser reutilizáveis. Confira a Predefinições de Parser documentação 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"
}

Escreva instruções manualmente

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

Siga o exemplo passo a passo abaixo para aprender o básico e depois explore nosso guia detalhado 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 da tarefa 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()"]
                }
            ]
        }
    }
}

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

Etapa 2. As instruções de parsing devem ser descritas em "parsing_instructions" .

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

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

O 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 usam a saída da função anterior como entrada.

No pipeline de exemplo acima, a xpath_one função (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 de destino pode ser encontrado: .//span[@class='sb_count']. Você também pode instruir o parser a selecionar o text() encontrado no elemento de destino.

O resultado analisado da tarefa de exemplo acima deve ficar assim:

{
    "results": [
        {
            "content": {
                "number_of_results": "Cerca de 16.700.000 resultados",
                "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 só oferece 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 texto com palavras-chave extras de que você talvez não precise necessariamente. Se você quiser obter o número de resultados para a query=test dada no tipo de dado numérico, você pode reutilizar as mesmas instruções de parsing e adicionar a amount_from_string função ao 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 analisado da tarefa 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 não conseguir processar as instruções de parsing definidas pelo cliente, retornaremos o 12005 código de status (analisado 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 esses 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.