4 Funcionalidad JSONPath

Descripción general

Esta sección describe la funcionalidad JSONPath admitida dentro de los pasos de preprocesamiento del valor del elemento.

JSONPath se compone de segmentos separados por puntos. Un segmento puede tomar la forma de una palabra simple, que representa un nombre de valor JSON, el carácter comodín (*) o una construcción más compleja encerrada entre corchetes. El punto antes de un segmento entre corchetes es opcional y se puede omitir.

Ejemplo de JSONPath Descripción
$.object.name Devuelve el contenido de object.name.
$.object['name'] Devuelve el contenido de object.name.
$.object.['name'] Devuelve el contenido de object.name.
$["objeto"]['nombre'] Devuelve el contenido de objeto.nombre.
$.['object'].["name"] Devuelve el contenido de object.name.
$.object.history.length() Devuelve el número de elementos de la matriz object.history.
$[?(@.name == 'Object')].price.first() Devuelve el valor de la propiedad price del primer objeto llamado "Object".
$[?(@.name == 'Object')].history.first().length() Devuelve el número de elementos de la matriz histórica del primer objeto llamado "Objeto".
$[?(@.price > 10)].length() Devuelve el número de objetos con un precio mayor que 10.

Consulte también: Escapar de caracteres especiales de valores de macro LLD en JSONPath.

Segmentos admitidos

Segmento Descripción
<nombre> Hacer coincidir la propiedad del objeto por nombre.
* Coincide con todas las propiedades del objeto.
['<nombre>'] Hacer coincidir la propiedad del objeto por nombre.
['<nombre>', '<nombre>', ...] Haga coincidir la propiedad del objeto con cualquiera de los nombres enumerados.
[<index>] Hacer coincidir el elemento de la matriz por índice.
[<número>, <número>, ...] Haga coincidir el elemento de la matriz con cualquiera de los índices enumerados.
[*] Coincide con todas las propiedades del objeto o elementos de la matriz.
[<start>:<end>] Haga coincidir los elementos de la matriz según el rango definido:
<start> - el primer índice que coincida (incluido); si no se especifica, coincide con todos los elementos de la matriz desde el principio; si es negativo, especifica el desplazamiento inicial desde el final de la matriz;
<end> - el último índice que coincide (excluyendo); si no se especifica, hace coincidir todos los elementos de la matriz hasta el final; si es negativo, especifica el desplazamiento inicial desde el final de la matriz.
[?(<expresión>)] Haga coincidir objetos/elementos de matriz aplicando una expresión de filtro.

Para encontrar un segmento coincidente ignorando su ascendencia (segmento separado), debe tener el prefijo dos puntos (..). Por ejemplo, $..name o $..['name'] devuelven valores de todas las propiedades de name.

Los nombres de elementos coincidentes se pueden extraer agregando un sufijo de tilde (~) al JSONPath. Devuelve el nombre del objeto coincidente o un índice en formato de cadena del elemento de matriz coincidente. El formato de salida sigue las mismas reglas que otras consultas JSONPath: los resultados de la ruta definida se devuelven "tal cual" y los resultados de la ruta indefinida se devuelven en una matriz. Sin embargo, tiene un valor mínimo extraer el nombre de un elemento que coincida con una ruta definitiva, como ya se conoce.

Filtrar expresión

La expresión de filtro es una expresión aritmética en notación infija.

Operandos soportados:

Operando Descripción
"<text>"
'<text>'
Constante de texto.

Ejemplo:
'valor: \\'1\\''
"valor: '1'"
<número> Constante numérica que respalda la notación científica.

Ejemplo: 123
<jsonpath comenzando con $> Valor al que hace referencia JSONPath desde el nodo raíz del documento de entrada; sólo se admiten rutas definidas.

Ejemplo: $.object.name
<jsonpath comenzando con @> Valor al que hace referencia JSONPath desde el objeto/elemento actual; sólo se admiten rutas definidas.

Ejemplo: @.name

Operadores soportados:

Operador Tipo Descripción Resultado
- Binario Resta Número
+ Binario Suma Número
/ Binario División Número
* Binario Multiplicación Número
== Binario Igualdad Booleano (1/0)
!= Binario Desigualdad Booleano (1/0)
< Binario Menor que Booleano (1/0)
<= Binario Menor o igual a Booleano (1/0)
> Binario Mayor que Booleano (1/0)
>= Binario Mayor o igual a Booleano (1/0)
=~ Binario Coincide con expresión regular Booleano (1/0)
! Unario Booleano NOT Booleano (1/0)
|| Binario Booleano O Booleano (1/0)
&& Binario Booleano AND Booleano (1/0)

Funciones

Las funciones se pueden utilizar al final de JSONPath. Se pueden encadenar varias funciones si la función anterior devuelve un valor aceptado por la siguiente función.

Funciones soportadas:

Función Descripción Entrada Salida
avg Valor promedio de números en una matriz de entrada Matriz de números Número
min Valor mínimo de números en una matriz de entrada Matriz de números Número
max Valor máximo de números en una matriz de entrada Matriz de números Número
sum Suma de números en una matriz de entrada Matriz de números Número
longitud Número de elementos en una matriz de entrada Matriz Número
first El primer elemento de una matriz Matriz Una construcción JSON (objeto, matriz, valor) que depende del contenido de la matriz de entrada

Las funciones agregadas JSONPath aceptan valores numéricos entre comillas. Estos valores se convierten automáticamente de cadenas a tipos numéricos cuando es necesario agregarlos. La entrada incompatible hará que la función genere un error.

Valor de salida

JSONPaths se puede dividir en rutas definidas e indefinidas. Una ruta definida puede devolver sólo un valor nulo o una única coincidencia. Una ruta indefinida puede devolver múltiples coincidencias: JSONPaths con múltiples listas de nombres/índices separadas, sectores de matriz o segmentos de expresión. Sin embargo, cuando se utiliza una función, JSONPath se vuelve definitivo, ya que las funciones siempre generan un valor único.

Una ruta definida devuelve el objeto/matriz/valor al que hace referencia. Por el contrario, una ruta indefinida devuelve una matriz de objetos/matrices/valores coincidentes.

::: nota importante Es posible que el orden de las propiedades en los resultados de la consulta JSONPath no se alinee con el orden de las propiedades JSON originales debido a métodos de optimización internos. Por ejemplo, JSONPath $.books[1]["autor", "título"] puede devolver ["título", "autor"]. Si es esencial preservar el orden de propiedad original, se deben considerar métodos alternativos de procesamiento posterior a la consulta. :::

Reglas de formato de ruta

Los espacios en blanco (espacio, carácter de tabulación) se pueden utilizar en expresiones y segmentos de notación entre corchetes, por ejemplo: $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first ( ).

Las cadenas deben estar entre comillas simples (') o dobles ("). Dentro de las cadenas, las comillas simples o dobles (dependiendo de cuál se use para encerrarlas) y las barras invertidas (\) se escapan con el carácter de barra invertida (\).

Ejemplo

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

Note: This query shows that arithmetical operations can be used in queries; it can be simplified to $.books[?(@.id == 2)].title
$.books[?(@.id == 2 \|\| @.id == 4)].title indefinite ["Sword of Honour", "The Lord of the Rings"]
$.books[?(!(@.id == 2))].title indefinite ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
$.books[?(@.id != 2)].title indefinite ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
$.books[?(@.title =~ " of ")].title indefinite ["Sayings of the Century", "Sword of Honour", "The Lord of the Rings"]
$.books[?(@.price > 12.99)].title indefinite ["The Lord of the Rings"]
$.books[?(@.author > "Herman Melville")].title indefinite ["Sayings of the Century", "The Lord of the Rings"]
$.books[?(@.price > $.filters.price)].title indefinite ["Sword of Honour", "The Lord of the Rings"]
$.books[?(@.category == $.filters.category)].title indefinite ["Sword of Honour","Moby Dick","The Lord of the Rings"]
$.books[?(@.category == "fiction" && @.price < 10)].title indefinite ["Moby Dick"]
$..[?(@.id)] indefinite [
{
"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 indefinite ["Printing and assembling book in A5 format", "Rebinding torn book"]
$..id.length() definite 4
$.books[?(@.id == 2)].title.first() definite Sword of Honour
$..tags.first().length() definite 5

Note: $..tags is an indefinite path, so it returns an array of matched elements, i.e., [["a", "b", "c", "d", "e" ]]; first() returns the first element, i.e., ["a", "b", "c", "d", "e"]; length() calculates the length of the element, i.e.,5.
$.books[*].price.min() definite 8.95
$..price.max() definite 154.99
$.books[?(@.category == "fiction")].price.avg() definite 14.99
$.books[?(@.category == $.filters.xyz)].title indefinite Note: A query without match returns NULL for definite and indefinite paths.
$.services[?(@.active=="true")].servicegroup indefinite [1001,1000]

Note: Text constants must be used in boolean value comparisons.
$.services[?(@.active=="false")].servicegroup indefinite [1002]

Note: Text constants must be used in boolean value comparisons.
$.services[?(@.servicegroup=="1002")]~.first() definite restoration