> 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/parsing-instruction-examples.md).
# Exemplos de instruções de análise
Veja exemplos práticos de instruções de análise para o Custom Parser: lide com objetos aninhados, listas, erros e arrays de arrays.
O trecho de HTML a seguir é analisado usando instruções de parsing de exemplo nas seções seguintes.
### HTML de exemplo
```html
```
### Mínimo necessário
{% hint style="info" %}
Caso de uso: você quer extrair o texto de todos os **sapatos** **descrição** **itens**.
{% endhint %}
*Exemplo 1. Seleção de itens da descrição de Sapatos usando XPath.*
```json
{
"shoes_description": {
"_fns": [
{
"_fn": "xpath",
"_args": [
".//div[@id='shoes']//li[@class='description-item']/text()"
]
}
]
}
}
```
A função `xpath` encontrará um único item e o colocará em uma lista como uma string:
```json
{
"shoes_description": [
"Ótimo"
]
}
```
O comportamento exato `xpath` da função é descrito [**aqui**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/list-of-functions.md).
### Instruções de parsing aninhadas
{% hint style="info" %}
Caso de uso: você quer analisar todas as informações relacionadas aos sapatos. Além disso, o resultado analisado deve representar a estrutura do documento do HTML fornecido.
{% endhint %}
Você está apontando para esta parte do HTML de exemplo:
```html
```
E você gostaria que o resultado analisado tivesse a seguinte estrutura:
```json
{
"shoes": {
"title": "Sapatos",
"price": "223.12",
"description": [
"Ótimo"
]
}
}
```
As instruções de parsing teriam a seguinte forma.
*Exemplo 2. As instruções de parsing são usadas para analisar* `sapatos` *informações.*
```json
{
"shoes": {
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@id='shoes']/div[@class='title']/text()"]
}
]
},
"price": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@id='shoes']/div[@class='price']/text()"]
}
]
},
"description": {
"_fns": [
{
"_fn": "xpath",
"_args": ["//div[@id='shoes']//li[@class='description-item']/text()"]
}
]
}
}
}
```
`xpath_one` funciona de forma semelhante a `xpath`, mas em vez de retornar uma lista de todas as correspondências, ele **retorna o primeiro item correspondente**.
No exemplo acima, a `sapatos` propriedade é a única propriedade definida no escopo mais externo das instruções. A `sapatos` propriedade contém instruções de parsing aninhadas.
A função `sapatos` o escopo das instruções não tem um pipeline definido (`_fns` propriedade está ausente). Isso significa que os pipelines definidos em `title`, `price`, e `descrição` escopos usarão o documento em análise como entrada do pipeline.
No Exemplo 2, você pode ver uma repetição de `//div[@id='shoes']` nas expressões XPath. A repetição pode ser evitada definindo um pipeline no `sapatos` escopo:
*Exemplo 3. Definindo um pipeline no* `sapatos` *escopo de instruções para evitar repetição da expressão XPath.*
```json
{
"shoes": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@id='shoes']"]
}
],
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["./div[@class='title']/text()"]
}
]
},
"price": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["./div[@class='price']/text()"]
}
]
},
"description": {
"_fns": [
{
"_fn": "xpath",
"_args": [".//li[@class='description-item']/text()"]
}
]
}
}
}
```
Ao usar as instruções de parsing fornecidas no Exemplo 3, Custom Parser irá:
1. Comece processando o `shoes._fns` pipeline, que produzirá o `sapatos` elemento HTML;
2. Pegue `shoes._fns` a saída do pipeline e use-a como entrada para pipelines definidos em `title`, `price`, e `descrição` escopos;
3. Processe `title`, `price`, e `descrição` os pipelines para produzir os valores finais.
O resultado ficará igual ao resultado do Exemplo 2:
```json
{
"shoes": {
"title": "Sapatos",
"price": "223.12",
"description": [
"Ótimo"
]
}
}
```
A principal diferença entre o Exemplo 2 e o Exemplo 3 é que, no Exemplo 3, o pipeline é definido no `sapatos` escopo. **Esse pipeline adicional seleciona o elemento de shoes e o passa para pipelines posteriores encontrados mais profundamente na hierarquia de instruções.**
### Lista de objetos aninhados
{% hint style="info" %}
**Caso de uso:** Anteriormente, você queria analisar apenas `sapatos` informações. Agora você quer analisar as informações de todos os produtos no HTML.
{% endhint %}
A função [**HTML de exemplo**](#sample-html) é usado novamente como documento em análise.
Se você quiser que seu resultado analisado fique assim:
```json
{
"products": [
{
"title": "Sapatos",
"price": "223.12",
"description": [
"Ótimo"
]
},
{
"title": "Calças",
"price": "60.12",
"description": [
"Incrível",
"Qualidade"
]
},
{
"title": "Meias",
"price": "123.12",
"description": [
"Muito",
"Legal",
"Meias"
]
}
]
}
```
As instruções de parsing teriam a seguinte forma:
*Exemplo 4. Analisando todos os produtos encontrados no documento HTML.*
```json
{
"products": {
"_fns": [
{
"_fn": "xpath",
"_args": ["//div[@class='product']"]
}
],
"_items": {
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["./div[@class='title']/text()"]
}
]
},
"price": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["./div[@class='price']/text()"]
}
]
},
"description": {
"_fns": [
{
"_fn": "xpath",
"_args": [".//li[@class='description-item']/text()"]
}
]
}
}
}
}
```
A estrutura das instruções de parsing parece semelhante à do Exemplo 3. No entanto, há duas exceções principais:
1. `xpath` é usado em vez de `xpath_one` em `products._fns` pipeline. `products._fns` pipeline agora produzirá uma lista de todos os elementos que correspondem à expressão XPath fornecida (uma lista de elementos de produto).
2. `_items` propriedade reservada é usada para indicar que você quer formar uma lista iterando por cada item da `products._fns` saída do pipeline e **passando/processando cada item da lista separadamente** ao longo do escopo do pipeline.
Se `_items` a propriedade reservada não fosse usada nas instruções de parsing do Exemplo 4, o resultado analisado ficaria assim:
```json
{
"products": {
"title": [
"Sapatos",
"Calças",
"Meias"
],
"price": [
"223.12",
"60.12",
"123.12"
],
"description": [
[
"Ótimo"
],
[
"Incrível",
"Qualidade"
],
[
"Muito",
"Legal",
"Meias"
]
]
}
}
```
{% hint style="warning" %}
`_items` é usado para especificar que o Custom Parser deve passar ***itens separados da lista*** em vez da ***lista inteira*** pelas instruções de parsing.
{% endhint %}
### Selecionar o N-ésimo elemento de uma lista
Esta seção demonstra a flexibilidade dos pipelines. O mesmo problema pode ser abordado de maneiras diferentes.
Várias opções podem ser usadas para selecionar o N-ésimo elemento de uma lista de quaisquer valores.
{% hint style="info" %}
**Caso de uso:** você quer selecionar o segundo preço do produto na página.
{% endhint %}
A função [**HTML de exemplo**](#sample-html) é usado novamente como exemplo. Você tem várias opções para selecionar o 2º produto.
#### Opção 1
Você pode utilizar o seletor XPath `[]` e definir a seleção na expressão XPath.
*Exemplo 5. Selecionar o 2º preço usando o seletor \[] do XPath.*
```json
{
"second_price": {
"_fns": [
{
"_fn": "xpath",
"_args": [
"(//div[@class='price'])[2]/text()"
]
}
]
}
}
```
Resultado:
```json
{
"second_price": [
"60.12"
]
}
```
#### Opção 2
Você também pode usar a `xpath` função xpath para encontrar todos os preços e encaminhá-los para a função `select_nth`, que seleciona o n-ésimo elemento da lista extraída de preços.
*Exemplo 6. Selecionar o 2º valor usando a função \`select\_nth\`.*
```json
{
"second_price": {
"_fns": [
{
"_fn": "xpath",
"_args": [
"//div[@class='price']/text()"
]
},
{
"_fn": "select_nth",
"_args": 1
}
]
}
}
```
Resultado:
```json
{
"second_price": "60.12"
}
```
{% hint style="warning" %}
Observe como a `select_nth` função retorna um item de uma lista enquanto a `xpath` função retorna uma lista de itens, mesmo se um único item for encontrado.
{% endhint %}
#### Opção 3
Você pode usá-lo `select_nth` com qualquer tipo de lista, incluindo listas de elementos HTML:
*Exemplo 7. Selecionando todos os elementos HTML do produto com* `class="product"` *==> selecionando o 2º elemento de produto da lista ==> extraindo o texto do preço do elemento HTML do produto selecionado*.
```json
{
"second_price": {
"_fns": [
{
"_fn": "xpath",
"_args": ["//div[@class='product']"]
},
{
"_fn": "select_nth",
"_args": 1
},
{
"_fn": "xpath",
"_args": ["./div[@class='price']/text()"]
}
]
}
}
```
Resultado:
```json
{
"second_price": ["60.12"]
}
```
### Tratamento de erros
Ao receber o seguinte trecho de HTML:
```html
Sapatos legais
223.12
Super
```
E ao tentar analisá-lo com as seguintes instruções de parsing:
```json
{
"product": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@id='shoes']"]
}
],
"price": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@class='price']/text()"]
}
]
},
"title": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@class='title']/text()"]
}
]
},
"description": {
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@class='description']/text()"]
},
{
"_fn": "convert_to_float"
}
]
}
}
}
```
Custom Parser retornará um resultado analisado em que `price` e `title` foram analisados normalmente, mas o `descrição` falhou ao ser analisado devido à `convert_to_float` função falhar ao converter `cadeia de caracteres` para `float`:
```json
{
"product": {
"price": "223.12",
"title": "Sapatos",
"description": null
},
"_warnings": [
{
"_fn": "convert_to_float",
"_fn_idx": 1,
"_msg": "Falha ao processar a função.",
"_path": ".product.description"
}
]
}
```
Por padrão, todos os erros são contados como avisos e são colocados dentro da `_warnings` lista. Se você quiser ignorar os erros ao analisar um campo, você pode suprimir avisos/erros com `"_on_error": "suppress"` parâmetro:
```json
{
"product": {
...,
"description": {
"_on_error": "suppress",
"_fns": [
{
"_fn": "xpath_one",
"_args": ["//div[@class='description']/text()"]
},
{
"_fn": "convert_to_float"
}
]
}
}
}
```
O que então produzirá o seguinte resultado:
```json
{
"product": {
"price": "223.12",
"title": "Sapatos",
"description": null
}
}
```
### Array de arrays
Custom Parser permite arrays N-dimensionais nos resultados analisados. Como exemplo, vamos usar o seguinte trecho de HTML:
```html
```
Digamos que você queira analisar o documento para que o resultado seja um array bidimensional 3x3 de inteiros:
```json
{
"table": [
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]
}
```
Para analisar o HTML no JSON acima, você pode usar as seguintes instruções de parsing:
```json
{
"table": {
"_fns": [
{
"_fn": "xpath",
"_args": ["//div[@class='row']"]
},
{
"_fn": "xpath",
"_args": [".//div[@class='column']/text()"]
},
{
"_fn": "convert_to_int"
}
]
}
}
```
---
# 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/parsing-instruction-examples.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.