Documentation
Table of Contents
4 Funcionalidade JSONPath
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.
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: <start> - o primeiro índice a ser correspondido (inclusivo); 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; <end> - o último índice a ser correspondido (exclusivo); 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.
Expressão de filtro
A expressão de filtro é uma expressão aritmética em notação infixa.
Operandos suportados:
| Operando | Descrição |
|---|---|
"<texto>"'<texto>' | Constante de texto. Exemplo: 'value: \\'1\\''"value: '1'" |
<número> | Constante numérica com suporte à notação científica. 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. Exemplo: $.object.name |
<jsonpath começando com @> | Valor referenciado pelo JSONPath a partir do objeto/elemento atual; apenas caminhos definidos são suportados. 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) |
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 construção 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.
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 retornam um único valor.
Um caminho definido retorna o objeto/array/valor ao qual faz referência. Em contraste, um caminho indefinido retorna um array dos objetos/arrays/valores correspondentes.
A ordem das propriedades nos resultados da consulta JSONPath pode não corresponder à ordem original das propriedades do JSON devido a métodos internos de otimização. Por exemplo, o JSONPath $.books[1]["author", "title"] pode retornar ["title", "author"]. Se for essencial preservar a ordem original das propriedades, métodos alternativos de pós-processamento da consulta devem ser considerados.
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 (\).
Exemplo
{ "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 | { "price": 10, "category": "fiction", "no filters": "no \"filters\"" } |
$.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"] 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 | [ { "price": 8.95, "id": 1, "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century" }, { "price": 12.99, "id": 2, "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour" }, { "price": 8.99, "id": 3, "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3" }, { "price": 22.99, "id": 4, "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8" } ] |
$.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 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] Nota: Constantes de texto devem ser usadas em comparações de valores booleanos. |
$.services[?(@.active=="false")].servicegroup | indefinido | [1002] Nota: Constantes de texto devem ser usadas em comparações de valores booleanos. |
$.services[?(@.servicegroup=="1002")]~.first() | definido | restoration |