[comment]: # ({ece5d44c-16d8a00a})
# 4 Funcionalidade JSONPath

[comment]: # ({/ece5d44c-16d8a00a})

[comment]: # ({aac69794-a806c032})
#### Visão geral

Esta seção descreve a funcionalidade JSONPath suportada nas etapas de pré-processamento de valores de item.

JSONPath é composto por segmentos separados por pontos.
Um segmento pode assumir a forma de uma palavra simples, representando um nome de valor JSON, o caractere curinga (`*`) ou uma construção mais complexa entre colchetes.
O ponto antes de um segmento entre colchetes é opcional e pode ser omitido.

|Exemplo de JSONPath|Descrição|
|-----|-----|
|`$.object.name`|Retorna o conteúdo de `object.name`.|
|`$.object['name']`|Retorna o conteúdo de `object.name`.|
|`$.object.['name']`|Retorna o conteúdo de `object.name`.|
|`$["object"]['name']`|Retorna o conteúdo de `object.name`.|
|`$.['object'].["name"]`|Retorna o conteúdo de `object.name`.|
|`$.object.history.length()`|Retorna o número de elementos do array `object.history`.|
|`$[?(@.name == 'Object')].price.first()`|Retorna o valor da propriedade `price` do primeiro objeto chamado "Object".|
|`$[?(@.name == 'Object')].history.first().length()`|Retorna o número de elementos do array history do primeiro objeto chamado "Object".|
|`$[?(@.price > 10)].length()`|Retorna o número de objetos com preço maior que 10.|

Veja também: [Escapando caracteres especiais de valores de macros LLD em JSONPath](/manual/config/items/preprocessing/jsonpath_functionality/escaping_lld_macros).

[comment]: # ({/aac69794-a806c032})

[comment]: # ({1298c5a2-74fc1571})
#### Segmentos suportados

|Segmento|Descrição|
|--|--------|
|`<name>`|Corresponde à propriedade do objeto pelo nome.|
|`*`|Corresponde a todas as propriedades do objeto.|
|`['<name>']`|Corresponde à propriedade do objeto pelo nome.|
|`['<name>', '<name>', ...]`|Corresponde à propriedade do objeto por qualquer um dos nomes listados.|
|`[<index>]`|Corresponde ao elemento do array pelo índice.|
|`[<number>, <number>, ...]`|Corresponde ao elemento do array por qualquer um dos índices listados.|
|`[*]`|Corresponde a todas as propriedades do objeto ou elementos do array.|
|`[<start>:<end>]`|Corresponde aos elementos do array pelo intervalo definido:<br>**<start>** - o primeiro índice a ser correspondido (incluindo); se não especificado, corresponde a todos os elementos do array desde o início; se negativo, especifica o deslocamento inicial a partir do final do array;<br>**<end>** - o último índice a ser correspondido (excluindo); se não especificado, corresponde a todos os elementos do array até o final; se negativo, especifica o deslocamento inicial a partir do final do array.|
|`[?(<expression>)]`|Corresponde a objetos/elementos do array aplicando uma expressão de filtro.|

Para encontrar um segmento correspondente ignorando sua ancestralidade (segmento destacado), ele deve ser prefixado com dois pontos (`..`).
Por exemplo, `$..name` ou `$..['name']` retornam valores de todas as propriedades `name`.

Os nomes dos elementos correspondentes podem ser extraídos adicionando um sufixo til (`~`) ao JSONPath.
Ele retorna o nome do objeto correspondente ou um índice em formato de string do item do array correspondente.
O formato de saída segue as mesmas regras de outras consultas JSONPath - resultados de caminho definido são retornados 'como estão', e resultados de caminho indefinido são retornados em um array.
No entanto, há pouco valor em extrair o nome de um elemento que corresponde a um caminho definitivo, pois ele já é conhecido.

[comment]: # ({/1298c5a2-74fc1571})

[comment]: # ({67ca5f43-5eac028e})
#### Expressão de filtro

A expressão de filtro é uma expressão aritmética em notação infixa.

Operandos suportados:

|Operando|Descrição|
|---|-------|
|`"<texto>"`<br>`'<texto>'`|Constante de texto.<br><br>Exemplo:<br>`'value: \\'1\\''`<br>`"value: '1'"`|
|`<número>`|Constante numérica que suporta notação científica.<br><br>Exemplo: `123`|
|`<jsonpath começando com $>`|Valor referenciado pelo JSONPath a partir do nó raiz do documento de entrada; apenas caminhos definidos são suportados.<br><br>Exemplo: `$.object.name`|
|`<jsonpath começando com @>`|Valor referenciado pelo JSONPath a partir do objeto/elemento atual; apenas caminhos definidos são suportados.<br><br>Exemplo: `@.name`|

Operadores suportados:

|Operador|Tipo|Descrição|Resultado|
|-|---|---|---|
|`-`|Binário|Subtração|Número|
|`+`|Binário|Adição|Número|
|`/`|Binário|Divisão|Número|
|`*`|Binário|Multiplicação|Número|
|`==`|Binário|Igualdade|Booleano (1/0)|
|`!=`|Binário|Desigualdade|Booleano (1/0)|
|`<`|Binário|Menor que|Booleano (1/0)|
|`<=`|Binário|Menor ou igual a|Booleano (1/0)|
|`>`|Binário|Maior que|Booleano (1/0)|
|`>=`|Binário|Maior ou igual a|Booleano (1/0)|
|`=~`|Binário|Corresponde à expressão regular|Booleano (1/0)|
|`!`|Unário|NÃO booleano|Booleano (1/0)|
|`||`|Binário|OU booleano|Booleano (1/0)|
|`&&`|Binário|E booleano|Booleano (1/0)|

[comment]: # ({/67ca5f43-5eac028e})

[comment]: # ({8c75d01d-b66eb391})
#### Funções

Funções podem ser usadas no final do JSONPath.
Múltiplas funções podem ser encadeadas se a função anterior retornar um valor que seja aceito pela função seguinte.

Funções suportadas:

|Função|Descrição|Entrada|Saída|
|-|----|--|---|
|`avg`|Valor médio dos números em um array de entrada|Array de números|Número|
|`min`|Valor mínimo dos números em um array de entrada|Array de números|Número|
|`max`|Valor máximo dos números em um array de entrada|Array de números|Número|
|`sum`|Soma dos números em um array de entrada|Array de números|Número|
|`length`|Número de elementos em um array de entrada|Array|Número|
|`first`|O primeiro elemento de um array|Array|Uma estrutura JSON (objeto, array, valor) dependendo do conteúdo do array de entrada|

Funções de agregação JSONPath aceitam valores numéricos entre aspas.
Esses valores são automaticamente convertidos de strings para tipos numéricos quando a agregação é necessária.
Entradas incompatíveis farão com que a função gere um erro.

[comment]: # ({/8c75d01d-b66eb391})

[comment]: # ({e739c583-729c09d6})
#### Valor de saída

Os JSONPaths podem ser divididos em caminhos definidos e indefinidos.
Um caminho definido pode retornar apenas nulo ou uma única correspondência.
Um caminho indefinido pode retornar várias correspondências: JSONPaths com listas de nomes/índices destacadas, fatias de array ou segmentos de expressão.
No entanto, quando uma função é usada, o JSONPath se torna definido, pois as funções sempre produzem um único valor.

Um caminho definido retorna o objeto/array/valor ao qual está se referindo.
Em contraste, um caminho indefinido retorna um array dos objetos/arrays/valores correspondentes.

::: noteimportant
A ordem das propriedades nos resultados da consulta JSONPath pode não estar alinhada com a ordem original das propriedades JSON devido a métodos internos de otimização.
Por exemplo, o JSONPath `$.books[1]["author", "title"]` pode retornar `["title", "author"]`.
Se preservar a ordem original das propriedades for essencial, métodos alternativos de pós-processamento da consulta devem ser considerados.
:::

[comment]: # ({/e739c583-729c09d6})

[comment]: # ({b5105ad4-5f0aac44})
#### Regras de formatação de caminho

Espaços em branco (espaço, caractere de tabulação) podem ser usados em segmentos de notação de colchetes e expressões, por exemplo: `$[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first( )`.

Strings devem ser delimitadas por aspas simples (`'`) ou duplas (`"`).
Dentro das strings, aspas simples ou duplas (dependendo de quais são usadas para delimitá-las) e barras invertidas (`\`) são escapadas com o caractere barra invertida (`\`).

[comment]: # ({/b5105ad4-5f0aac44})

[comment]: # ({f476ebb9-4c860844})
#### Exemplo

[comment]: # ({/f476ebb9-4c860844})

[comment]: # ({b5257e6a-93072157})
```json
{
  "books": [
    {
      "category": "reference",
      "author": "Nigel Rees",
      "title": "Sayings of the Century",
      "price": 8.95,
      "id": 1
    },
    {
      "category": "fiction",
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 12.99,
      "id": 2
    },
    {
      "category": "fiction",
      "author": "Herman Melville",
      "title": "Moby Dick",
      "isbn": "0-553-21311-3",
      "price": 8.99,
      "id": 3
    },
    {
      "category": "fiction",
      "author": "J. R. R. Tolkien",
      "title": "The Lord of the Rings",
      "isbn": "0-395-19395-8",
      "price": 22.99,
      "id": 4
    }
  ],
  "services": {
    "delivery": {
      "servicegroup": 1000,
      "description": "Entrega no dia seguinte na cidade local",
      "active": true,
      "price": 5
    },
    "bookbinding": {
      "servicegroup": 1001,
      "description": "Impressão e montagem do livro no formato A5",
      "active": true,
      "price": 154.99
    },
    "restoration": {
      "servicegroup": 1002,
      "description": "Vários métodos de restauração",
      "active": false,
      "methods": [
        {
          "description": "Limpeza química",
          "price": 46
        },
        {
          "description": "Prensagem de páginas danificadas por umidade",
          "price": 24.5
        },
        {
          "description": "Reencadernação de livro rasgado",
          "price": 99.49
        }
      ]
    }
  },
  "filters": {
    "price": 10,
    "category": "fiction",
    "no filters": "no \"filters\""
  },
  "closed message": "A loja está fechada",
  "tags": [
    "a",
    "b",
    "c",
    "d",
    "e"
  ]
}
```

|JSONPath|Tipo|Resultado|
|---|-|------|
|`$.filters.price`|definido|10|
|`$.filters.category`|definido|fiction|
|`$.filters['no filters']`|definido|no "filters"|
|`$.filters`|definido|{<br>"price": 10,<br>"category": "fiction",<br>"no filters": "no \\"filters\\""<br>}|
|`$.books[1].title`|definido|Sword of Honour|
|`$.books[-1].author`|definido|J. R. R. Tolkien|
|`$.books.length()`|definido|4|
|`$.tags[:]`|indefinido|\["a", "b", "c", "d", "e" \]|
|`$.tags[2:]`|indefinido|\["c", "d", "e" \]|
|`$.tags[:3]`|indefinido|\["a", "b", "c"\]|
|`$.tags[1:4]`|indefinido|\["b", "c", "d"\]|
|`$.tags[-2:]`|indefinido|\["d", "e"\]|
|`$.tags[:-3]`|indefinido|\["a", "b"\]|
|`$.tags[:-3].length()`|definido|2|
|`$.books[0, 2].title`|indefinido|\["Moby Dick", "Sayings of the Century"\]|
|`$.books[1]['author', "title"]`|indefinido|\["Sword of Honour", "Evelyn Waugh"\]|
|`$..id`|indefinido|\[1, 2, 3, 4\]|
|`$.services..price`|indefinido|\[154.99, 5, 46, 24.5, 99.49\]|
|`$.books[?(@.id == 4 - 0.4 * 5)].title`|indefinido|\["Sword of Honour"\]<br><br>Nota: Esta consulta mostra que operações aritméticas podem ser usadas em consultas; pode ser simplificada para `$.books[?(@.id == 2)].title`|
|`$.books[?(@.id == 2 \|\| @.id == 4)].title`|indefinido|\["Sword of Honour", "The Lord of the Rings"\]|
|`$.books[?(!(@.id == 2))].title`|indefinido|\["Sayings of the Century", "Moby Dick", "The Lord of the Rings"\]|
|`$.books[?(@.id != 2)].title`|indefinido|\["Sayings of the Century", "Moby Dick", "The Lord of the Rings"\]|
|`$.books[?(@.title =~ " of ")].title`|indefinido|\["Sayings of the Century", "Sword of Honour", "The Lord of the Rings"\]|
|`$.books[?(@.price > 12.99)].title`|indefinido|\["The Lord of the Rings"\]|
|`$.books[?(@.author > "Herman Melville")].title`|indefinido|\["Sayings of the Century", "The Lord of the Rings"\]|
|`$.books[?(@.price > $.filters.price)].title`|indefinido|\["Sword of Honour", "The Lord of the Rings"\]|
|`$.books[?(@.category == $.filters.category)].title`|indefinido|\["Sword of Honour","Moby Dick","The Lord of the Rings"\]|
|`$.books[?(@.category == "fiction" && @.price < 10)].title`|indefinido|\["Moby Dick"\]|
|`$..[?(@.id)]`|indefinido|\[<br>{<br>"price": 8.95,<br>"id": 1,<br>"category": "reference",<br>"author": "Nigel Rees",<br>"title": "Sayings of the Century"<br>},<br>{<br>"price": 12.99,<br>"id": 2,<br>"category": "fiction",<br>"author": "Evelyn Waugh",<br>"title": "Sword of Honour"<br>},<br>{<br>"price": 8.99,<br>"id": 3,<br>"category": "fiction",<br>"author": "Herman Melville",<br>"title": "Moby Dick",<br>"isbn": "0-553-21311-3"<br>},<br>{<br>"price": 22.99,<br>"id": 4,<br>"category": "fiction",<br>"author": "J. R. R. Tolkien",<br>"title": "The Lord of the Rings",<br>"isbn": "0-395-19395-8"<br>}<br>\]|
|`$.services..[?(@.price > 50)].description`|indefinido|\["Impressão e montagem do livro no formato A5", "Reencadernação de livro rasgado"\]|
|`$..id.length()`|definido|4|
|`$.books[?(@.id == 2)].title.first()`|definido|Sword of Honour|
|`$..tags.first().length()`|definido|5<br><br>Nota: `$..tags` é um caminho indefinido, então retorna um array de elementos correspondentes, ou seja, `[["a", "b", "c", "d", "e" ]]`; `first()` retorna o primeiro elemento, ou seja, `["a", "b", "c", "d", "e"]`; `length()` calcula o comprimento do elemento, ou seja,`5`.|
|`$.books[*].price.min()`|definido|8.95|
|`$..price.max()`|definido|154.99|
|`$.books[?(@.category == "fiction")].price.avg()`|definido|14.99|
|`$.books[?(@.category == $.filters.xyz)].title`|indefinido|Nota: Uma consulta sem correspondência retorna NULL para caminhos definidos e indefinidos.|
|`$.services[?(@.active=="true")].servicegroup`|indefinido|\[1001,1000\]<br><br>Nota: Constantes de texto devem ser usadas em comparações de valores booleanos.|
|`$.services[?(@.active=="false")].servicegroup`|indefinido|\[1002\]<br><br>Nota: Constantes de texto devem ser usadas em comparações de valores booleanos.|
|`$.services[?(@.servicegroup=="1002")]~.first()`|definido|restoration|

[comment]: # ({/b5257e6a-93072157})