> 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
O seguinte trecho HTML é analisado usando instruções de parsing de exemplo nas próximas seções.
### Exemplo de HTML
```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 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 URL `xpath` a função 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á 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": [
"Ótimo"
]
}
}
```
As instruções de parsing ficariam assim.
*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, ela **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 URL `sapatos` o escopo das instruções não tem um pipeline definido (`_fns` a propriedade está ausente). Isso significa que os pipelines definidos em `title`, `preço`, 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 no `sapatos` escopo:
*Exemplo 3. Definindo um pipeline no* `sapatos` *escopo das instruções 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 `shoes._fns` a saída do pipeline e usá-la como entrada para os pipelines definidos em `title`, `preço`, e `descrição` escopos;
3. Processar `title`, `preço`, e `descrição` pipelines para produzir 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 dos sapatos e o passa para outros pipelines encontrados mais profundamente na hierarquia das instruções.**
### Lista de objetos aninhados
{% hint style="info" %}
**Caso de uso:** Antes, você queria analisar apenas `sapatos` informações. Agora você quer analisar as informações de todos os produtos no HTML.
{% endhint %}
A URL [**Exemplo de HTML**](#sample-html) é usado novamente como o documento em análise.
Se você quiser que seu resultado analisado se pareça com isto:
```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 ficariam assim:
*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 se parece com a 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 `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` é usada 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 diferentes maneiras.
Várias opções podem ser usadas para selecionar o N-ésimo elemento de uma lista de qualquer valor.
{% hint style="info" %}
**Caso de uso:** você quer selecionar o preço do segundo produto na página.
{% endhint %}
A URL [**Exemplo de HTML**](#sample-html) é usado novamente como exemplo. Você tem várias opções para selecionar o 2º produto.
#### Opção 1
Você pode usar o seletor XPath `[]` e definir a seleção na expressão XPath.
*Exemplo 5. Selecione 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 para encontrar todos os preços e encaminhá-la para a função `select_nth`, que seleciona o n-ésimo elemento da lista de preços extraída.
*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 que um único item seja 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 de 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 HTML:
```html
Sapatos legais
223.12
Ótimo
```
E tentando 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 `preço` e `title` foram analisados normalmente, mas o `descrição` não pôde ser analisado devido à `convert_to_float` falha da função ao converter `texto` a `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 HTML:
```html
```
Digamos que você queira analisar o documento de modo que o resultado seja uma matriz 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.