Это перевод страницы документации с английского языка. Помогите нам сделать его лучше.

4 Поддержка JSONPath функционала

Обзор

В этом разделе приведены сведения о поддерживаемом JSONPath функционале в шагах предобработки значений элементов данных.

JSONPath состоит из сегментов разделенных точками. Сегмент может быть как простым словом, например имя значения JSON, *, так и более сложной конструкцией заключённой в квадратные скобки [ ]. Разделительная точка перед сегментом скобки является опциональной и её можно опустить. Например:

Путь Описание
$.object.name Возвращает содержимое object.name.
$.object['name'] Возвращает содержимое object.name.
$.object.['name'] Возвращает содержимое object.name.
$["object"]['name'] Возвращает содержимое object.name.
$.['object'].["name"] Возвращает содержимое object.name.
$.object.history.length() Возвращает количество элементов массива object.history.
$[?(@.name == 'Object')].price.first() Возвращает поле price первого объекта с именем 'Object'.
$[?(@.name == 'Object')].history.first().length() Возвращает количество элементов массива history первого объекта с именем 'Object'.
$[?(@.price > 10)].length() Возвращает количество объектов с price больше чем 10.

Смотрите также: Экранирование специальных символов из значений LLD макросов в JSONPath.

Поддерживаемые сегменты

Сегмент Описание
<имя> Соответствие свойству объекта по имени.
* Соответствие всем свойствам объекта.
['<имя>'] Соответствие свойства объекта по имени.
['<имя>', '<имя>', ...] Соответствие свойства объекта по любому из перечисленных имён.
[<индекс>] Соответствие элементу массива по его номеру.
[<число>, <число>, ...] Соответствие элементу массива по любому из перечисленных индексов.
[*] Соответствие всем свойствам объекта или элементам массива.
[<начало>:<конец>] Соответствие элементам массива по заданному диапазону:
<начало> - первый индекс соответствия (включая). Если не указан, соответствует всем элементам с самого начала. Если указан отрицательным значением, задаёт начало смещения с конца массива.
<конец> - последний индекс соответствия (включая). Если не указан, соответствует всем элементам массива до самого конца. Если указан отрицательным значением, задаёт начало смещения с конца массива.
[?(<выражение>)] Соответствие объектов / элементов массива с применением выражения фильтра.

Чтобы найти соответствующий сегмент, игнорируя его происхождение (отсоединенный сегмент), его необходимо указывать с префиксом '..', например $..name или $..['name'] вернёт все значения всех 'name' свойств.

Фильтрация выражения

Выражение фильтра является арифметическим выражением в инфиксном представлении.

Поддерживаемые операнды:

Операнд Описание Пример
"<текст>"
'<text>'
Текстовая константа. 'value: \'1\''
"value: '1'"
<число> Числовая константа, поддерживающая научное представление. 123
<jsonpath начиная с $> Значение, указанное в JSONPath с начала узла корневого входящего документа; поддерживаются только определённые пути. $.object.name
<jsonpath начиная с @> Значение, указанное в JSONPath с текущего объекта / элемента; поддерживаются только определенные пути. @.name

Поддерживаемые операторы:

Оператор Тип Описание Результат
- бинарный Вычитание. Число.
+ бинарный Сложение. Число.
/ бинарный Деление. Число.
* бинарный Умножение. Число.
== бинарный Равно. Логический (1 или 0).
!= бинарный Не равно. Логический (1 или 0).
< бинарный Меньше чем. Логический (1 или 0).
<= бинарный Меньше чем или равно. Логический (1 или 0).
> бинарный Больше чем. Логический (1 или 0).
>= бинарный Больше чем или равно. Логический (1 или 0).
=~ бинарный Соответствие регулярному выражению. Логический (1 или 0).
! унарный Логические НЕ. Логический (1 или 0).
\|\| бинарный Логическое ИЛИ. Логический (1 или 0).
&& бинарный Логическое И. Логический (1 или 0).

Функции

Функции можно использовать в конце JSONPath. Несколько функций можно включать в цепочку, если предыдущая функция возвращает значение, которое принимается следующей функцией.

Поддерживаемые функции:

Функция Описание Вход Выход
avg Среднее значение из чисел во входящем массиве. Массив чисел. Число.
min Минимальное значение из чисел во входящем массиве. Массив чисел. Число.
max Максимальное значение из чисел во входящем массиве. Массив чисел. Число.
sum Сумма чисел во входящем массиве. Массив чисел. Число.
length Количество элементов во входящем массиве. Массив. Число.
first Первый элемент массива. Массив. JSON конструктор (объект, массив, значение), в зависимости от содержимого входящего массива.

Функциями агрегации JSONPath принимаются числовые значения в кавычках. Это означает что значения преобразуются со строкового типа в числовой, если требуется агрегирование.

Несовместимые входящие данные повлекут ошибку в функции.

Результирующее значение

JSONPaths можно разделить на определённые и неопределённые пути. Определённый путь может вернуть только null или одно совпадение. Неопределённый путь может вернуть несколько совпадений, в основном JSONPaths с отсоединенными несколькими именами / списком индексов, фрагментом массива или сегментами выражения. Однако, когда используется функция, JSONPath становится определённым, так как функции всегда имеют одиночное результирующее значение.

Определённый путь возвращает объект/массив/значение, на которое он ссылается, тогда как неопределённый путь возвращает массив соответствующих объектов/массивов/значений.

Пробелы

Пробелы (пробелы как таковые, символы табуляции) можно свободно использовать в сегментах с представлением в виде квадратных скобок и в выражениях, например, $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first( ).

Строки

Строки должны быть заключены в одинарные ' или двойные " кавычки. Внутри строк одинарные или двойные кавычки (в зависимости от того какие кавычки используются внутри строк) и обратные косые черты \ экранируются при помощи символа \ косой черты.

Примеры

Входящие данные
{
         "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 Тип Результат Комментарии
$.filters.price определённый 10
$.filters.category определённый fiction
$.filters['no filters'] определённый no "filters"
$.filters определённый {
"price": 10,
"category": "fiction",
"no filters": "no \"filters\""
}
$.books[1].title определённый Sword of Honour
$.books[-1].author определённый J. R. R. Tolkien
$.books.length() определённый 4
$.tags[:] неопределённый ["a", "b", "c", "d", "e" ]
$.tags[2:] неопределённый ["c", "d", "e" ]
$.tags[:3] неопределённый ["a", "b", "c"]
$.tags[1:4] неопределённый ["b", "c", "d"]
$.tags[-2:] неопределённый ["d", "e"]
$.tags[:-3] неопределённый ["a", "b"]
$.tags[:-3].length() определённый 2
$.books[0, 2].title неопределённый ["Sayings of the Century", "Moby Dick"]
$.books[1]['author', "title"] неопределённый ["Evelyn Waugh", "Sword of Honour"]
$..id неопределённый [1, 2, 3, 4]
$.services..price неопределённый [5, 154.99, 46, 24.5, 99.49]
$.books[?(@.id == 4 - 0.4 * 5)].title неопределённый ["Sword of Honour"] Этот запрос показывает, что в запросах можно использовать математические операции. Конечно, этот запрос можно упростить до $.books[?(@.id == 2)].title
$.books[?(@.id == 2 \|\| @.id == 4)].title неопределённый ["Sword of Honour", "The Lord of the Rings"]
$.books[?(!(@.id == 2))].title неопределённый ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
$.books[?(@.id != 2)].title неопределённый ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
$.books[?(@.title =~ " of ")].title неопределённый ["Sayings of the Century", "Sword of Honour", "The Lord of the Rings"]
$.books[?(@.price > 12.99)].title неопределённый ["The Lord of the Rings"]
$.books[?(@.author > "Herman Melville")].title неопределённый ["Sayings of the Century", "The Lord of the Rings"]
$.books[?(@.price > $.filters.price)].title неопределённый ["Sword of Honour", "The Lord of the Rings"]
$.books[?(@.category == $.filters.category)].title неопределённый ["Sword of Honour","Moby Dick","The Lord of the Rings"]
$..[?(@.id)] неопределённый [
{
"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 неопределённый '["Printing and assembling book in A5 format", "Rebinding torn book"]
$..id.length() определённый 4
$.books[?(@.id == 2)].title.first() определённый Sword of Honour
$..tags.first().length() определённый 5 $..tags - неопределённый путь, поэтому он вернёт массив соответствующих элементов - [["a", "b", "c", "d", "e" ]], first() вернёт первый элемент - ["a", "b", "c", "d", "e" ] и, наконец, length() вычислит свой размер - 5.
$.books[*].price.min() определённый 8.95
$..price.max() определённый 154.99
$.books[?(@.category == "fiction")].price.avg() определённый 14.99
$.books[?(@.category == $.filters.xyz)].title неопределённый Запрос без совпадения вернёт NULL по определённому и неопределённому путям.
$.services[?(@.active=="true")].servicegroup неопределённый [1000,1001] В сравнениях логических значений необходимо использовать текстовые константы.
$.services[?(@.active=="false")].servicegroup неопределённый [1002] В сравнениях логических значений необходимо использовать текстовые константы.