> 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/writing-instructions-manually/tips-for-writing-xpath-expressions.md).
# Dicas para escrever expressões XPath
Aprenda a escrever expressões XPath eficazes para o Custom Parser com técnicas comprovadas e melhores práticas que garantem extração precisa de dados.
## A estrutura do HTML pode diferir entre o documento coletado e o carregado no navegador
Ao escrever funções de seleção de elementos HTML, **certifique-se de trabalhar com documentos coletados em vez da versão ao vivo do site carregada no seu navegador**, pois os documentos podem diferir. A principal razão por trás desse problema é a renderização de JavaScript. Quando um site é aberto, seu navegador é responsável por carregar documentos adicionais, como folhas de estilo CSS e scripts JavaScript, que podem alterar a estrutura do documento HTML inicial. Ao analisar HTMLs coletados, Custom Parser não carrega o documento HTML da mesma forma que os navegadores fazem (os parsers ignoram instruções JavaScript), portanto a árvore HTML pode diferir entre o que o parser e o navegador renderizam.
Como exemplo, veja o seguinte documento HTML:
```html
Documento
Este é um produto
Este é o preço:
E aqui está uma descrição
```
Se você abrir o documento no navegador, ele mostrará o preço que você pode selecionar usando a seguinte expressão XPath `//p[@id="price"]`:
Agora, se você desativar a renderização de JavaScript no navegador, o site será renderizado da seguinte forma:
A mesma `//p[@id="price"]` expressão XPath não corresponde mais ao preço, pois ele não é renderizado.
## Certifique-se de escrever todos os seletores HTML possíveis para o elemento de destino
Por vários motivos, a mesma página coletada duas vezes pode ter layouts diferentes (diferentes User Agents usados na coleta, site de destino fazendo testes A/B etc.).
Para lidar com esse problema, sugerimos definir `parsing_instructions` para o documento coletado inicialmente e testar essas instruções imediatamente com vários outros resultados de tarefas coletados do mesmo tipo de página.
funções de seletor HTML (`xpath`/`xpath_one`) suportam [**fallbacks de seletor**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/list-of-functions/function-examples.md#xpath).
## Fluxo sugerido para escrever seletores HTML
1. Colete o documento HTML da página de destino usando Scraper API.
2. Desative o JavaScript e abra o HTML coletado localmente no seu navegador. Se o JavaScript estiver desativado **depois** depois que o HTML for aberto, certifique-se de recarregar a página para que o HTML possa recarregar sem JavaScript.
3. [**Use as ferramentas de desenvolvimento do navegador**](https://www.computerhope.com/issues/ch002153.htm).
### Como escrever instruções de análise
Digamos que você tenha a seguinte página para analisar:
```html
`
Este é um produto legal
Esta é uma descrição do produto
Durável
Nice
Doce
Picante
Variações
Vermelho
99.99
Verde
87.99
Azul
65.99
Preto
99.99
```
### Analise o título do produto
Crie um novo objeto JSON e atribua a ele um novo campo.
Você pode nomear o campo da maneira que preferir, com algumas exceções (o nome do campo definido pelo usuário não pode começar com um sublinhado `_` , por exemplo, `"_title"`).
O nome do campo será exibido no resultado analisado.
O novo campo deve conter um valor do tipo objeto JSON:
```json
{
"title": {} // definindo um campo title a ser analisado
}
```
Se você fornecer essas instruções ao Custom Parser, ele não fará nada ou enviará uma reclamação de que você não forneceu instruções.
Para realmente analisar o título no `title` campo, você deve definir um pipeline de processamento de dados dentro do `title` objeto usando a `_fns` propriedade reservada (que é sempre do tipo array):
```json
{
"title": {
"_fns": [] // definindo um pipeline de processamento de dados para o campo title
}
}
```
Para que o Custom Parser selecione o texto do título, você pode utilizar a função de seletor HTML `xpath_one`. Para usar a função no documento HTML, ela deve ser adicionada ao pipeline de processamento de dados. A função é definida como um objeto JSON com os campos obrigatórios `_fn` (nome da função) e `_args` (argumentos da função). Veja a lista completa de definições de função [**aqui**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/list-of-functions.md).
```json
{
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//h1/text()"]
}
]
}
}
```
As instruções de análise acima devem produzir o seguinte resultado:
```json
{
"title": "Este é um produto legal"
}
```
### Analise a descrição
Da mesma forma, nas instruções de análise, você pode definir outro campo no qual o contêiner da descrição do produto, o título da descrição e os itens serão analisados. Para que o título e os itens da descrição fiquem aninhados sob o `descrição` objeto, a estrutura das instruções deve ser a seguinte:
```json
{
"title": {...},
"description": { // contêiner da descrição
"title": {}, // título da descrição
"items": {} // itens da descrição
}
}
```
A estrutura fornecida das instruções de análise implica que `description.title` e `description.items` serão analisados com base no `descrição` elemento. Você pode definir um pipeline para o `descrição` campo. Neste caso, isso é feito primeiro, pois simplificará a expressão XPath do título da descrição.
```json
{
"title": {...},
"description": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@id='description-container']"]
}
], // O resultado do pipeline será usado ao analisar `title` e `items`.
"title": {},
"items": {}
}
}
```
No exemplo, o `description._fns` pipeline selecionará o `description-container` elemento HTML, que será usado como ponto de referência para analisar o título e os itens da descrição.
Para analisar os campos restantes da descrição, adicione dois pipelines diferentes para os campos `description.items`, e `description.title`:
```json
{
"title": {...},
"description": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
"//div[@id='description-container']"
]
}
],
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
"//h2/text()"
]
}
]
},
"items": {
"_fns": [
{
"_fn": "xpath",
"_args": [
"//li/text()"
]
}
]
}
}
}
```
Observe como a `xpath` a função é usada em vez de `xpath_one` para extrair todos os itens que correspondem à expressão XPath.
As instruções de análise produzem o seguinte resultado:
```json
{
"title": {...},
"description": {
"title": "Esta é uma descrição sobre o produto",
"items": [
"Durável",
"Legal",
"Doce",
"Picante"
]
}
}
```
### Analise as variações do produto
O exemplo a seguir mostra a estrutura das instruções se você quiser analisar informações no `product_variants` campo, que conterá uma lista de objetos de variação. Neste caso, o objeto de variação tem `preço` e `color` campos.
```json
{
"title": {...},
"description": {...},
"product_variants": [
{
"price": ...,
"color": ...
},
{
...
},
...
]
}
```
Comece selecionando todos os elementos de variação do produto:
```json
{
"title": {...},
"description": {...},
"product_variants": {
"_fns": [
{
"_fn": "xpath",
"_args": ["//div[@class='variant']"]
}
]
}
}
```
Para fazer `product_variants` uma lista contendo objetos JSON, você terá que iterar pelas variações encontradas usando `_items` iterador:
```json
{
"title": {...},
"description": {...},
"product_variants": {
"_fns": [
{
"_fn": "xpath",
"_args": ["//div[@class='variant']"]
}
],
"_items": { // com isso, você está instruindo a processar os elementos encontrados um por um
// instruções de campo a serem descritas aqui
}
}
}
```
Por fim, defina instruções sobre como analisar os `color` e `preço` campos:
```json
{
"title": {...},
"description": {...},
"product_variants": {
"_fns": [
{
"_fn": "xpath",
"_args": [
"//div[@class='variant']"
]
}
],
"_items": {
"color": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
// Como estamos usando expressões XPath relativas,
// certifique-se de que o XPath comece com um ponto (.)
".//p[@class='color']/text()"
]
}
]
},
"price": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
".//p[@class='price']/text()"
]
}
]
}
}
}
}
```
Com `product_variants` descrito, as instruções finais ficarão assim:
```json
{
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
"//h1/text()"
]
}
]
},
"description": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
"//div[@id='description-container']"
]
}
],
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
"//h2/text()"
]
}
]
},
"items": {
"_fns": [
{
"_fn": "xpath",
"_args": [
"//li/text()"
]
}
]
}
},
"product_variants": {
"_fns": [
{
"_fn": "xpath",
"_args": [
"//div[@class='variant']"
]
}
],
"_items": {
"color": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
".//p[@class='color']/text()"
]
}
]
},
"price": {
"_fns": [
{
"_fn": "xpath_one",
"_args": [
".//p[@class='price']/text()"
]
}
]
}
}
}
}
```
O que produzirá a seguinte saída:
```json
{
"title": "Este é um produto legal",
"description": {
"title": "Esta é uma descrição do produto",
"items": [
"Durável",
"Legal",
"Doce",
"Picante"
]
},
"product_variants": [
{
"color": "Vermelho",
"price": "99.99"
},
{
"color": "Verde",
"price": "87.99"
},
{
"color": "Azul",
"price": "65.99"
},
{
"color": "Preto",
"price": "99.99"
}
]
}
```
Você pode encontrar mais exemplos de instruções de análise aqui: [**Exemplos de instruções de análise**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/parsing-instruction-examples.md).
---
# 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/writing-instructions-manually/tips-for-writing-xpath-expressions.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.
