# Exemplos de instruções de parsing
O seguinte trecho de HTML é analisado usando instruções de parsing de exemplo nas próximas seções.
### HTML de exemplo
```html
```
### Mínimo indispensável
{% hint style="info" %}
Caso de uso: você quer extrair o texto de todos os **sapatos** **descrição** **itens**.
{% endhint %}
*Exemplo 1. Seleção dos itens de descrição dos sapatos usando XPath.*
```json
{
"shoes_description": {
"_fns": [
{
"_fn": "xpath",
"_args": [
".//div[@id='shoes']//li[@class='description-item']/text()"
]
}
]
}
}
```
A `xpath` a função encontrará um único item e o colocará em uma lista como uma string:
```json
{
"shoes_description": [
"Super"
]
}
```
O exato `xpath` comportamento 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á direcionando 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": [
"Super"
]
}
}
```
As instruções de parsing teriam a seguinte aparência.
*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, **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 `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` os 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 em `sapatos` escopo:
*Exemplo 3. Definindo um pipeline nas instruções de escopo* `sapatos` *para evitar a 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()"]
}
]
}
}
}
```
Usando as instruções de parsing fornecidas no Exemplo 3, Custom Parser irá:
1. Começar processando `shoes._fns` pipeline, que produzirá o `sapatos` elemento HTML;
2. Pegar a saída do `shoes._fns` pipeline e usá-la como entrada para os pipelines definidos em `title`, `price`, e `descrição` escopos;
3. Processar `title`, `price`, e `descrição` pipelines para produzir os valores finais.
O resultado será igual ao resultado do Exemplo 2:
```json
{
"shoes": {
"title": "Sapatos",
"price": "223.12",
"description": [
"Super"
]
}
}
```
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 dos sapatos e o passa adiante para outros pipelines 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 [**HTML de exemplo**](/products/pt-br/web-scraper-api/features/custom-parser/writing-instructions-manually/parsing-instruction-examples.md#sample-html) é usado novamente como o documento em análise.
Se você quiser que o resultado analisado se pareça com isto:
```json
{
"products": [
{
"title": "Sapatos",
"price": "223.12",
"description": [
"Super"
]
},
{
"title": "Calças",
"price": "60.12",
"description": [
"Incrível",
"Qualidade"
]
},
{
"title": "Meias",
"price": "123.12",
"description": [
"Muito",
"Bonito",
"Meias"
]
}
]
}
```
As instruções de parsing teriam a seguinte aparência:
*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 da instrução 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` o pipeline agora produzirá uma lista de todos os elementos que correspondem à expressão XPath fornecida (uma lista de elementos de produto).
2. `_items` a propriedade reservada é usada para indicar que você quer formar uma lista iterando por cada item da saída do `products._fns` pipeline e **passando/processando cada item da lista separadamente** para o escopo do pipeline.
Se `_items` a propriedade reservada não fosse usada nas instruções de parsing do Exemplo 4, o resultado analisado teria a seguinte aparência:
```json
{
"products": {
"title": [
"Sapatos",
"Calças",
"Meias"
],
"price": [
"223.12",
"60.12",
"123.12"
],
"description": [
[
"Super"
],
[
"Incrível",
"Qualidade"
],
[
"Muito",
"Bonito",
"Meias"
]
]
}
}
```
{% hint style="warning" %}
`_items` é usado para especificar que o Custom Parser deve passar ***itens separados da lista*** em vez da ***lista inteira*** para baixo nas instruções de parsing.
{% endhint %}
### Selecione o enésimo elemento de uma lista
Esta seção demonstra a flexibilidade dos pipelines. O mesmo problema pode ser abordado de maneiras diferentes.
Múltiplas opções podem ser usadas para selecionar o enésimo elemento de uma lista de qualquer valor.
{% hint style="info" %}
**Caso de uso:** você quer selecionar o segundo preço do produto na página.
{% endhint %}
A [**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. Selecione o 2º preço usando o seletor 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 para encontrar todos os preços e encaminhá-la para a função `select_nth`, que seleciona o enésimo elemento da lista extraída de preços.
*Exemplo 6. Selecione 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 quando um único item é encontrado.
{% endhint %}
#### Opção 3
Você pode usar `select_nth` com qualquer tipo de lista, incluindo listas de elementos HTML:
*Exemplo 7. Selecionando todos os elementos HTML de 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 Bonitos
223.12
Super
```
E 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 ao `convert_to_float` falhar ao converter `string` até `float`:
```json
{
"product": {
"price": "223.12",
"title": "Sapatos",
"description": null
},
"_warnings": [
{
"_fn": "convert_to_float",
"_fn_idx": 1,
"_msg": "Failed to process function.",
"_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, eles podem 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
}
}
```
### Matriz de matrizes
Custom Parser permite matrizes N-dimensionais nos resultados analisados. Como exemplo, vamos usar o seguinte trecho de HTML:
```html
```
Digamos que você queira analisar o documento de forma que o resultado seja uma matriz 2D 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: 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/writing-instructions-manually/parsing-instruction-examples.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.