Sidebar

Zabbix Summit 2022
Register for Zabbix Summit 2022

3 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