4 Funcionalitat JSONPath

Vista general

Aquesta secció proporciona detalls sobre la funcionalitat JSONPath admesa a les passes de preprocessament del valor de l'element.

JSONPath consta de segments separats per punts. Un segment pot ésser una paraula simple com un nom de valor JSON, (*) o una construcció més complexa entre claudàtors. El període de separació abans del segment entre parèntesis és opcional i es pot ometre. Per exemple:

Camí Descripció
$.object.name Retorna el contingut d'object.name.
$.object['name'] Retorna el contingut d'object.name.| |$.object.['name']|Retorna el contingut d'object.name.
$["object"]['name'] Retorna el contingut d'object.name.| |$.['object'].["name"]|Retorna el contingut d'object.name.
$.object.history.length() Retorna el nombre d'elements de la matriu object.history.
$[?(@.name == 'Objecte')].price.first() Retorna el camp de preu del primer objecte amb el nom "Objecte".
$[?(@.name == 'Objecte')].history.first().length() Retorna el nombre d'elements a la matriu d'historial del primer objecte amb el nom "Objecte".
$[?(@.price > 10)].length() Retorna el nombre d'articles el preu dels quals és superior a 10.

Veieu també: Escapar de caràcters especials dels valors de macro LLD a JSONPath.

Segments admesos

Segment Descripció
<nom> Concorda la propietat de l'objecte pel nom.
* Coincideix amb totes les propietats de l'objecte.
['<nom>'] Concorda la propietat de l'objecte pel nom.
['<nom>', '<nom>', ...] Fa coincidir la propietat de l'objecte amb un dels noms de la llista.
[<index>] Concorda element de matriu per índex.
[<nombre>, <nombre>, ...] Fa coincidir l'element de la matriu amb un dels índexs llistats.
[*] Coincideix amb totes les propietats de l'objecte o els elements de la matriu.
[<inici>:<fi>] Concorda els elements de la matriu segons l'interval definit:
<inici> - el primer índex coincident (inclòs). Si no s'especifica, coincideix amb tots els elements de la matriu des del principi. Si és negatiu, especifica el desplaçament inicial des del final de la matriu.
<fi> - el darrer índex coincident (no inclòs). Si no s'especifica, coincideix amb tots els elements de la matriu fins al final. Si és negatiu, especifica el desplaçament inicial des del final de la matriu.
[?(<expression>)] Concorda objectes/elements de matriu aplicant una expressió de filtre.

Per trobar un segment coincident ignorant la seva ascendència (segment separat), ha d'anar prefixat amb dos punts ('..'). Per exemple, $..name o $..['name'] retornen els valors de totes les propietats name.

Els noms dels elements coincidents es poden extreure afegint un sufix barrat ~ al JSONPath. Retorna el nom de l'objecte corresponent o un índex de cadena de l'element de matriu corresponent. El format de sortida segueix les mateixes regles que altres consultes JSONPath: els resultats del camí definit es retornen 'tal qual' i els resultats del camí no definit es retornen en una matriu. Tot i així, no té sentit extreure el nom d'un element corresponent a un camí definit: ja se sap.

Expressió de filtre

L'expressió de filtre és una expressió aritmètica en notació infix.

Operands admesos:

Operand Descripció
"<text>"
'<text>'
Constant de text.

Exemple:
'value: \\'1\\''
"value: '1'"
<nombre> Constante numèrica que suporta la notació científica.

Exemple: 123
<jsonpath comença amb $> Valor al qual fa referència JSONPath des del node arrel del document d'entrada; només s'admeten els camins definits.

Exemple: $.object.name
<jsonpath comença amb @> Valor referenciat pel JSONPath des de l'objecte/element actual; només s'admeten els camins definits.

Exemple: @.name

Operadors compatibles:

Operador Tipus Descripció Resultat
- binari Resta. Nombre.
+ binari Suma. Nombre.
/ binari Divisió. Nombre.
* binari Multiplicació. Nombre.
== binari Igual. Booleà (1 o 0).
!= binari No és igual a. Booleà (1 o 0).
< binari És inferior a. Booleà (1 o 0).
<= binari És menor o igual a. Booleà (1 o 0).
> binari És més gran que. Booleà (1 o 0).
>= binari És més gran o igual que. Booleà (1 o 0).
=~ binari Coincideix amb l'expressió regular. Booleà (1 o 0).
! unitari No booleà. Booleà (1 o 0).
|| binari O booleà. Booleà (1 o 0).
&& binari I booleà. Booleà (1 o 0).

Funcions

Les funcions es poden emprar al final d'un JSONPath. Es poden encadenar diverses funcions si la funció anterior retorna un valor acceptat per la funció següent.

Funcions admeses:

Funció Descripció Entrada Sortida
avg Valor mitjà dels nombres a una matriu d'entrada Matriu de nombres Nombre
min Valor mínim dels nombres a una matriu d'entrada Matriu de nombres Nombre
max Valor màxim dels nombres a una matriu d'entrada Matriu de nombres Nombre
sum Suma de nombres d'una matriu d'entrada Matriu de nombres Nombre
length Nombre d'elements a una matriu d'entrada. Matri. Nombre
first El primer element de la matriu Matriu Una construcció JSON (objecte, matriu, valor) basada en el contingut de la matriu d'entrada

Els valors numèrics entre cometes són admesos per les funcions agregades JSONPath. Això vol dir que els valors es converteixen del tipus de cadena a numèric si cal l'agregació. Una entrada incompatible farà que la funció generi un error.

Valor de retorn

Els camins JSON es poden dividir en camins definits i no definits. Un camí definit només pot retornar una coincidència nul·la o única. Un camí no definit pot retornar diverses coincidències: JSONPaths amb diverses llistes de nom/índex, fragments de matriu o segments d'expressió separats. Tanmateix, quan s'empra una funció, el JSONPath s'estableix, ja que les funcions sempre generen un valor únic.

Un camí definit retorna l'objecte/matriu/valor al qual fa referència. En canvi, el camí no definit retorna una matriu dels objectes/matrius/valors corresponents.

És possible que l'ordre de la propietat dels resultats de la consulta JSONPath no s'alinei amb l'ordre de la propietat JSON original a causa dels mètodes d'optimització interns. Per exemple, el JSONPath $.books[1]["author", "title"] pot retornar ["title", "author"]. Si conservar l'ordre de propietat original és essencial, s'han de considerar mètodes alternatius de processament posterior a la consulta.

Regles de format del camí

Els espais en blanc (espai, caràcter de tabulació) es poden emprar en segments i expressions de notació de claudàtors, per exemple: $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first ( ).

Les cadenes s'han de tancar amb cometes simples (') o dobles ("). Dins de les cadenes, les cometes simples o dobles (segons quines s'utilitzin per tancar-la) i les barres invertides (\) s'escapen amb el caràcter de barra invertida (\).

Exemple

{
         "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": "Chemical 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 Tipus Resultat
$.filters.price definit 10
$.filters.category definit ficció
$.filters['no filters'] definit no "filters"
$.filters definit {
"price": 10,
"category": "ficció",
"no filters": "no \"filters\""
}
$.books[1].title definit Sword of Honour
$.books[-1].author definit J. R. R. Tolkien
$.books.length() definit 4
$.tags[:] indefinit ["a", "b", "c", "d", "e" ]
$.tags[2:] indefinit ["c", "d", "e" ]
$.tags[:3] indefinit ["a", "b", "c"]
$.tags[1:4] indefinit ["b", "c", "d"]
$.tags[-2:] indefinit ["d", "e"]
$.tags[:-3] indefinit ["a", "b"]
$.tags[:-3].length() definit 2
$.books[0, 2].title indefinit ["Moby Dick", "Sayings of the Century"]
$.books[1]['author', "title"] indefinit ["Sword of Honour", "Evelyn Waugh"]
$..id indefinit [1, 2, 3, 4]
$.services..price indefinit [5, 154.99, 46, 24.5, 99.49]
$.books[?(@.id == 4 - 0.4 * 5)].title indefinit ["Sword of Honour"]

Nota: Aquesta cerca ensenya que les operacions aritmètiques es poden emprar a les consultes. Evidentment, aquesta consulta es pot simplificar com a $.books[?(@.id == 2)].title
$.books[?(@.id == 2 \|\| @.id == 4)].title indefinit ["Sword of Honour", "The Lord of the Rings"]
$.books[?(!(@.id == 2))].title indefinit ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
$.books[?(@.id != 2)].title indefinit ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
$.books[?(@.title =~ " of ")].title indefinit ["Sayings of the Century", "Sword of Honour", "The Lord of the Rings"]
$.books[?(@.price > 12.99)].title indefinit ["The Lord of the Rings"]
$.books[?(@.author > "Herman Melville")].title indefinit ["Sayings of the Century", "The Lord of the Rings"]
$.books[?(@.price > $.filters.price)].title indefinit ["Sword of Honour", "The Lord of the Rings"]
$.books[?(@.category == $.filters.category)].title indefinit ["Sword of Honour","Moby Dick","The Lord of the Rings"]
$.books[?(@.category == "ficció" && @.price < 10)].title indefinit ["Moby Dick"]
$..[?(@.id)] indefinit [
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95,
"id": 1
},
{
"category": "ficció",
"author": "Evelyn Waugh",
"title": "Sword of Honour",
"price": 12.99,
"id": 2
},
{
"category": "ficció",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99,
"id": 3
},
{
"category": "ficció",
"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 indefinit '["Printing and assembling book in A5 format", "Rebinding torn book"]
$..id.length() definit 4
$.books[?(@.id == 2)].title.first() definit Sword of Honour
$..tags.first().length() definit 5

Nota: $..etiquetes és un camí indefinit, pel que retornarà una matriu d'elements trobats, com ara [["a", "b", "c", "d", "e" ]]; first() retorna el primer element, com ara ["a", "b", "c", "d", "e" ]; length() calcula la seva allargada - 5.
$.books[*].price.min() definit 8.95
$..price.max() definit 154.99
$.books[?(@.category == "ficció")].price.avg() definit 14.99
$.books[?(@.category == $.filters.xyz)].title indefinit

Nota: Una consulta sense trobar res retornarà NULL per camins definits i indefinits.
$.services[?(@.active=="true")].servicegroup indefinit [1001,1000]

Nota: Les constants de text s'han d'emprar a les comparacions de valors booleans.
$.services[?(@.active=="false")].servicegroup indefinit [1002]

Nota: Les constants de text s'han d'emprar a les comparacions de valors booleans.
$.services[?(@.servicegroup=="1002")]~.first() definit restauració