> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/custom-parser/getting-started.md). # Primeiros passos ## Como usar o Custom Parser ### Exemplo de cenário Suponha que você queira extrair o **número de resultados totais** o Bing Search retorna com um termo de pesquisa `test`:
Vamos apresentar os três métodos principais para atingir este 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 OxyCopilot permite que você descreva suas necessidades em inglês simples para **criar scrapers e parsers automaticamente** para um site. Aprenda o básico seguindo os passos descritos abaixo e confira [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 [**Playground da Web Scraper API**](https://dashboard.oxylabs.io/en/api-playground) no nosso painel 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**, **Scraper**, e **URL** campos na parte superior e ajustando **parâmetros adicionais** recursos como a renderização de JavaScript no menu à esquerda. {% endhint %} {% endstep %} {% step %} #### Configurar 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. Para Bing Search, **ative a renderização de 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 seguinte prompt para extrair o número total de resultados das páginas do Bing Search: ``` Extraia o número total de resultados de pesquisa. ```
Clique no **Gerar instruções** botão para enviar seu prompt. {% endstep %} {% step %} #### Revisar dados parseados e instruções Quando o OxyCopilot terminar, você verá a seguinte janela, em que os dados parseados estão do lado direito:
Se quiser fazer ajustes, você pode fazê-los aqui. Modifique a(s) URL(s), refine o prompt, ative a renderização de 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) para atender às suas necessidades. Quando você atualizar qualquer campo nesta janela, poderá 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. {% endstep %} {% step %} #### Salvar o parser como um preset Você pode facilmente salvar suas instruções de parsing como um [predefinição de parser](/products/pt-br/web-scraper-api/features/custom-parser/parser-presets.md). Isso permite reutilizar o preset no OxyCopilot e nas suas requisições de API. No Playground da 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á pedindo que você nomeie o preset e adicione uma descrição opcional:
{% endstep %} {% step %} #### Usar o preset com requisições de API Para usar um preset com suas requisições da Web Scraper API, defina `parse` a `verdadeiro` e especifique o nome do preset 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 [Gerando instruções de parsing via API](/products/pt-br/web-scraper-api/features/custom-parser/generating-parsing-instructions-via-api.md) página de documentação para saber mais. {% hint style="success" %} Recomendamos **fornecer 3-5 URLs do mesmo tipo** (por exemplo, páginas de produto). Isso ajuda o parser a se adaptar a layouts diferentes e melhora a precisão do parsing. {% endhint %} **Endpoint:** `POST https://data.oxylabs.io/v1/parsers/generate-instructions/prompt` ```json { "prompt_text": "Parse the number of total search results.", "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": "The number of total search results.", "title": "Total Search Results", "type": "number" } }, "required": [ "total_search_results" ], "title": "Fields", "type": "object" } } ```
### Salvar presets de parser via API A Web Scraper API permite salvar instruções de parsing como presets reutilizáveis de parser. Confira a [Presets 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 completos de código. **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" } ```
### 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 localizar 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 do job 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"` campo. As instruções de parsing de exemplo acima especificam que o objetivo é extrair o número de resultados de pesquisa do documento raspado e colocar o resultado no campo `number_of_results` . As instruções sobre como extrair o campo definindo um “pipeline” são dadas assim: ```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 parseado do job de exemplo acima deve ficar assim: ```json { "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 texto com palavras-chave extras de que você talvez não precise. Se quiser obter o número de resultados para a `query=test` 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 parseado do job 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 falhar ao processar instruções de parsing definidas pelo cliente, retornaremos o `12005` código de status (parseado 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": "XPath expressions did not match any data.", "_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 Consulte nossos códigos de status descritos [**aqui**](/products/pt-br/web-scraper-api/response-codes.md#parsers). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/custom-parser/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.