Esta é uma tradução da página de documentação original em inglês. Ajude-nos a torná-la melhor.

3 Funcionalidade JSONPath

Visão geral

Esta seção fornece detalhes da funcionalidade JSONPath suportado em etapas de pré-processamento de valores de item.

O JSONPath consiste de segmentos separados com pontos. Um segmento pode ser ou uma simples palavra como nome de valor JSON, * ou um caso mais complexo envolto em colchetes [ ]. O ponto de separação antes do segmento em colchete é opcional e pode ser omitido. Por exemplo:

Path (caminho) 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 campo preço (price) do primeiro objeto com nome 'Object'.
$[?(@.name == 'Object')].history.first().length() Retorna o número de elementos do array 'history' do primeiro objeto com nome 'Object'.
$[?(@.price > 10)].length() Retorna o número de objetos com preço (price) sendo maior que 10.

Veja também: Escapando caracteres especiais de valores de macro LLD no JSONPath.

Segmentos suportados

Segmento Descrição
<name> Corresponde propriedade do objeto por nome.
* Corresponde todas as propriedades do objeto.
['<name>'] Corresponde propriedade de objeto por nome.
['<name>', '<name>', ...] Corresponde propriedade do objeto por qualquer dos nomes listados.
[<index>] Corresponde elemento do array pelo índice.
[<number>, <number>, ...] Corresponde elemento do array por qualquer índice listado.
[*] Corresponde todas as propriedades do objeto ou elementos do array.
[<start>:<end>] Corresponde elementos do array pelo intervalo definido:
<start> - o primeiro índice para corresponder (inclusive). Se não especificado faz a correspondência de todos os elementos do array desde o início. Se negativo especifica o início de deslocamento a partir do fim do array.
<end> - o último índice para corresponder (exclusive). Se não especificado faz a correspondência de todos os elementos do array até o fim. Se negativo especifica o início de deslocamento a partir do fim do array.
[?(<expression>)] Corresponde elementos de objetos/array pela aplicação de expressão de filtro.

Para encontrar um segmento correspondente ignorando sua ancestralidade (segmento destacado) deve ser prefixado com '..', por exemplo $..name ou $..['name'] retorna valores de todas as propriedades 'name'.

Nomes de elemento correspondidos podem ser extraídos pela adição de um sufixo ~ ao JSONPath. Ele retorna o nome do objeto correspondido ou um índice no formato string do item de array correspondente. O formato de saída segue as mesmas regras das outras consultas JSONPath - resultados de caminho definido são retornados 'como são' e resultados de caminho não definido são retornados em array. No entanto não há muita lógica em extrair o nome de um elemento correspondente a um caminho definido - ele já é conhecido.

Expressão de filtro

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

Operandos suportados:

Operando Descrição Exemplo
"<text>"
'<text>'
Constante de texto. 'value: \'1\''
"value: '1'"
<number> Constant numérica suportando notação científica. 123
<jsonpath starting with $> Valor referenciado pelo JSONPath do nó raíz do documento de entrada; apenas caminhos (paths) definidos são suportados. $.object.name
<jsonpath starting with @> Valor referenciado pelo JSONPath do objeto/elemento atual; apenas caminhos (paths) definidos são suportados. @.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 É igual a. Booleano. (1 or 0).
!= binário Não é igual a. Booleano. (1 or 0).
< binário É menor que. Booleano. (1 or 0).
<= binário É menor ou igual a. Booleano. (1 or 0).
> binário É maior que. Booleano. (1 or 0).
>= binário É maior ou igual a. Booleano. (1 or 0).
=~ binário Corresponde expressão regular. Booleano. (1 or 0).
! unário Booleano. não (not). Booleano. (1 or 0).
\|\| binário Booleano. ou (or). Booleano. (1 or 0).
&& binário Booleano. e (and). Booleano. (1 or 0).

Funções

Funções podem ser usadas no fim do JSONPath. Múltiplas funções podem ser amarradas se a função precedente retorna valor que é aceito pela função seguinte.

Funções suportadas:

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

Valores numéricos quotados são aceitos pelas funções agregadas JSONPath. Isto significa que os valores são convertidos do tipo string para numérico se agregação é necessária.

Uma entrada incompatível causará geração de erro pela função.

Valor de saída

Os JSONPaths podem ser divididos em caminhos definidos e indefinidos. Um caminho definido pode retornar apenas null ou uma simples correspondência. Um caminho indefinido pode retornar múltiplas correspondências, basicamente JSONPaths com múltiplas listas de nome/índice, parte de array ou segmentos de expressão destacados. No entanto, quando uma função é usada o JSONPath se torna definido, pois as funções sempre entregam valores únicos.

Um caminho definido retorna o objeto/array/valor que ele está referenciando, enquanto um caminho indefinido retorna um array dos objetos/arrays/valores correspondidos.

Espaço em branco

O espaço em branco (espaço, caracteres de tabulação) pode ser usado livremente em segmentos e expressões com notação em colchetes, por exemplo, $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first( ).

Strings

As strings devem ser quotadas (envoltas) com aspas simples ' ou duplas ". Dentro das strings, as aspas simples ou duplas (dependendo de quais são usadas para quotá-la) e contrabarras \ são escapadas com o caracter contrabarra \.

Exemplos

Dado de entrada
{
         "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": "Next day delivery in local town",
             "active": true,
             "price": 5
           },
           "bookbinding": {
             "servicegroup": 1001,
             "description": "Printing and assembling book in A5 format",
             "active": true,
             "price": 154.99
           },
           "restoration": {
             "servicegroup": 1002,
             "description": "Various restoration methods",
             "active": false,
             "methods": [
               {
                 "description": "Checmical cleaning",
                 "price": 46
               },
               {
                 "description": "Pressing pages damaged by moisture",
                 "price": 24.5
               },
               {
                 "description": "Rebinding torn book",
                 "price": 99.49
               }
             ]
           }
         },
         "filters": {
           "price": 10,
           "category": "fiction",
           "no filters": "no \"filters\""
         },
         "closed message": "Store is closed",
         "tags": [
           "a",
           "b",
           "c",
           "d",
           "e"
         ]
       }
JSONPath Tipo Resultado Comentários
$.filters.price definido 10
$.filters.category definido fiction
$.filters['no filters'] definido no "filters" (sem filtros)
$.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 ["Sayings of the Century", "Moby Dick"]
$.books[1]['author', "title"] indefinido ["Evelyn Waugh", "Sword of Honour"]
$..id indefinido [1, 2, 3, 4]
$.services..price indefinido [5, 154.99, 46, 24.5, 99.49]
$.books[?(@.id == 4 - 0.4 * 5)].title indefinido ["Sword of Honour"] Esta consulta mostra que operações aritméticas podem ser usadas em consultas. É claro que esta consulta 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"]
$..[?(@.id)] indefinido [
{
"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..[?(@.price > 50)].description indefinido '["Printing and assembling book in A5 format", "Rebinding torn book"]
$..id.length() definido 4
$.books[?(@.id == 2)].title.first() definido Sword of Honour
$..tags.first().length() definido 5 $..tags é um caminho indefinido, então ele retorna um array de elementos correspondidos - [["a", "b", "c", "d", "e" ]], first() retorna o primeiro elemento - ["a", "b", "c", "d", "e" ] e finalmente length() calcula seu comprimento - 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 Uma consulta sem correspondência retorna NULL para caminhos definido e indefinido.
$.services[?(@.active=="true")].servicegroup indefinido [1000,1001] Constantes de texto devem ser usadas em comparações de valor booleano.
$.services[?(@.active=="false")].servicegroup indefinido [1002] Constantes de texto devem ser usadas em comparações de valor booleano.
$.services[?(@.servicegroup=="1002")]~.first() definido restoration