Table of Contents
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 | |