Documentation
4 JSONPath機能
概要
このセクションでは、item 値のプリプロセスステップでサポートされる JSONPath 機能の詳細について説明します。
JSONPathは、ドットで区切られたセグメントで構成されます。
セグメントは、JSON 値の名前 * のような単純な単語と、あるいは角括弧 [ ] で囲まれたより複雑な構造体です。
セグメントを区切るドットはオプションで、省略することもできます。例えば
| Path | 説明 |
|---|---|
$.object.name | Return the object.name contents. |
$.object['name'] | Return the object.name contents. |
$.object.['name'] | Return the object.name contents. |
$["object"]['name'] | Return the object.name contents. |
$.['object'].["name"] | Return the object.name contents. |
$.object.history.length() | Return the number of object.history array elements. |
$[?(@.name == 'Object')].price.first() | Return the price field of the first object with name 'Object'. |
$[?(@.name == 'Object')].history.first().length() | Return the number of history array elements of the first object with name 'Object'. |
$[?(@.price > 10)].length() | Return the number of objects with price being greater than 10. |
Escaping special characters from LLD macro values in JSONPath も参照してください。
対応セグメント
| セグメント | 説明 |
|---|---|
<name> | オブジェクト プロパティを名前で照合します |
* | すべてのオブジェクト プロパティに一致します |
['<name>'] | オブジェクト プロパティを名前で照合します |
['<name>', '<name>', ...] | リストされた名前のいずれかでオブジェクト プロパティを照合します |
[<index>] | 配列要素をインデックスで照合します |
[<number>, <number>, ...] | リストされたインデックスのいずれかで配列要素を照合します |
[*] | すべてのオブジェクト プロパティまたは配列要素に一致します |
[<start>:<end>] | 定義された範囲で配列要素を一致させます: <start> - 一致する最初のインデックス (含む)。 指定しない場合は、最初からすべての配列要素に一致します。 負の場合は、配列の末尾からの開始オフセットを指定します。 <end> - 一致する最後のインデックス (除外)。 指定されていない場合は、すべての配列要素を最後まで一致させます。 負の場合、配列の末尾からの開始オフセットを指定します。 |
[?(<expression>)] | フィルター式を適用してオブジェクト/配列要素を一致させます |
前例を無視して一致するセグメント (切り離されたセグメント) を見つけるには、接頭辞 '..' を付ける必要があります。 たとえば、$..name または $..['name'] はすべての 'name' プロパティの値を返します。
一致した要素名は、JSONPath に~サフィックスを追加することで抽出できます。 一致したオブジェクトの名前または一致した配列項目の文字列形式のインデックスを返します。 出力形式は、他の JSONPath クエリと同じ規則に従います。明確なパスの結果は'そのまま'返され、不明確なパスの結果は配列で返されます。 ただし、明確なパスに一致する要素の名前を抽出する意味はあまりありません - それはすでに知られていいるからです。
フィルター式
フィルター式は、中置表記の算術式です。
サポートされているオペランド:
| オペランド | 説明 | 例 |
|---|---|---|
"<text>"'<text>' | テキスト定数 | 'value: \'1\'' "value: '1'" |
<number> | 科学表記法をサポートする数値定数 | 123 |
<jsonpath starting with $> | 入力ドキュメントのルート ノードから JSONPath によって参照される値。 明確なパスのみがサポートされています。 | $.object.name |
<jsonpath starting with @> | 現在のオブジェクト/要素から JSONPath によって参照される値。 明確なパスのみがサポートされています。 | @.name |
サポートされている演算子:
| 演算子 | タイプ | 説明 | 結果 |
|---|---|---|---|
- | binary | 減算 | Number. |
+ | binary | 加算 | Number. |
/ | binary | 除算 | Number. |
* | binary | 乗算 | Number. |
== | binary | 等しい | Boolean (1 or 0). |
!= | binary | 等しくない | Boolean (1 or 0). |
< | binary | 未満 | Boolean (1 or 0). |
<= | binary | 以下 | Boolean (1 or 0). |
> | binary | 超過 | Boolean (1 or 0). |
>= | binary | 以下 | Boolean (1 or 0). |
=~ | binary | 正規表現に一致 | Boolean (1 or 0). |
! | binary | ブール値のnot | Boolean (1 or 0). |
|| | binary | ブール値のor | Boolean (1 or 0). |
&& | binary | ブール値のand | Boolean (1 or 0). |
関数
関数は JSONPath の最後で使用できます。 前の関数が次の関数によって受け入れられる値を返す場合、複数の関数をチェーンできます。
サポートされている関数:
| 関数 | 説明 | 入力 | 出力 |
|---|---|---|---|
avg | 入力配列の数値の平均値 | 数値の配列 | 数値 |
min | 入力配列の数値の最小値 | 数値の配列 | 数値 |
max | 入力配列の数値の最大値 | 数値の配列 | 数値 |
sum | 入力配列の数値の合計 | 数値の配列 | 数値 |
length | 入力配列の要素数 | 配列 | 数値 |
first | 最初の配列要素 | 配列 | 入力配列の内容に応じた JSON コンストラクト (オブジェクト、配列、値) |
引用符で囲まれた数値は、JSONPath 集計関数によって受け入れられます。 これは、集計が必要な場合、値が文字列型から数値に変換されることを意味します。
入力に互換性がない場合、関数はエラーを生成します。
出力値
JSONPathsは、定型パスと不定型パスに分けることができます。
定型パスは、NULLまたは単一のマッチのみを返すことができます。不定型パスは、
複数の名前/インデックスリスト、配列スライス、 式セグメントを含む JSONPath を返します。
しかし関数が使用されると、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": "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 | タイプ | 結果 | コメント |
|---|---|---|---|
$.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 | ["Sayings of the Century", "Moby Dick"] | |
$.books[1]['author', "title"] | indefinite | ["Evelyn Waugh", "Sword of Honour"] | |
$..id | indefinite | [1, 2, 3, 4] | |
$.services..price | indefinite | [5, 154.99, 46, 24.5, 99.49] | |
$.books[?(@.id == 4 - 0.4 * 5)].title | indefinite | ["Sword of Honour"] | このクエリは、クエリで算術演算を使用できることを示しています。 もちろん、このクエリは $.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"] | |
$..[?(@.id)] | indefinite | [ { "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 | 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 | $..tags は不定パスなので、一致した要素の配列を返します - [["a", "b", "c", "d", "e" ]], first() は 最初の要素 - ["a", "b", "c", "d", "e" ] そして最後に length() はその長さ - 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 | 一致のないクエリは、明確なパスと不明確なパスに対して NULL を返します。 | |
$.services[?(@.active=="true")].servicegroup | indefinite | [1000,1001] | ブール値の比較では、テキスト定数を使用する必要があります。 |
$.services[?(@.active=="false")].servicegroup | indefinite | [1002] | ブール値の比較では、テキスト定数を使用する必要があります。 |
$.services[?(@.servicegroup=="1002")]~.first() | definite | restoration |