# Começando ## 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](#generate-parsers-with-oxycopilot) * [Gerar parsers via API](#generate-parsers-via-api) * [Escrever instruções de parsing manualmente](#write-instructions-manually) ### 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](/products/pt-br/web-scraper-api/web-scraper-api-playground/oxycopilot.md#custom-parser-builder) para mais informações. {% hint style="success" %} Abra a janela [**Web Scraper API Playground**](https://dashboard.oxylabs.io/en/api-playground) no nosso dashboard para acessar o OxyCopilot. {% endhint %} {% stepper %} {% step %} #### 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`.
{% hint style="info" %} 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. {% endhint %} {% endstep %} {% step %} #### 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**.
{% endstep %} {% step %} #### 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](https://oxylabs.io/resources/prompts-code-samples). 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. {% endstep %} {% step %} #### 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](/products/pt-br/web-scraper-api/web-scraper-api-playground/oxycopilot.md#step-2-optional-adjust-parsing-schema) 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. {% endstep %} {% step %} #### Salve o parser como predefinição Você pode salvar facilmente suas instruções de parsing como uma [preset do parser](/products/pt-br/web-scraper-api/features/custom-parser/parser-presets.md). 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:
{% endstep %} {% step %} #### 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` ```json { "source": "bing_search", "query": "test", "render": "html", "parse": true, "parser_preset": "Bing_total_results" } ``` Executar a solicitação fornecerá a seguinte saída JSON: ```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" } ] } ``` {% endstep %} {% endstepper %} ## 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](/products/pt-br/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md) para saber mais. {% hint style="success" %} 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. {% endhint %} **Endpoint:** `POST https://data.oxylabs.io/v1/parsers/generate-instructions/prompt` ```json { "prompt_text": "Analise o número total de resultados de busca.", "urls": ["https://www.bing.com/search?q=test"], "render": true } ```
Saída ```json { "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](/products/pt-br/web-scraper-api/features/custom-parser/parser-presets.md) 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` ```json { "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 ```json { "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](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually.md) 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: ```json { "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: ```json "_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](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/list-of-functions.md)) é 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: ```json { "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: ```json { "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: ```json { "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). ```json { "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: ```json { "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**](/products/pt-br/web-scraper-api/response-codes.md#parsers). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/custom-parser/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.