4 JSONPath 功能

概述

本节概述了在监控项值预处理步骤中支持的 JSONPath 功能。

JSONPath 由点分隔的段组成。
一段可以是简单单词，表示一个 JSON 值名称，通配符字符（*），或者用方括号括起来的更复杂结构。
在方括号段前面的点是可选的，可以省略。

JSONPath 示例	描述
`$.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` array 元素的数量。
`$[?(@.name == 'Object')].price.first()`	从名为 "object" 的第一个 object 中返回 `price` 属性的值。
`$[?(@.name == 'Object')].history.first().length()`	从名为 "object" 的第一个 object 中返回历史 array 元素的数量。
`$[?(@.price > 10)].length()`	返回价格大于 10 的 objects 数量。

另请参阅：Escaping special characters from LLD macro values in JSONPath。

支持的片段

Segment	描述
`<name>`	按名称匹配 object 属性。
`*`	匹配所有 object 属性。
`['<name>']`	按名称匹配 object 属性。
`['<name>', '<name>', ...]`	按照列出的任意名称匹配 object 属性。
`[<index>]`	按索引匹配 array 元素。
`[<number>, <number>, ...]`	按照列出的任意索引匹配 array 元素。
`[*]`	匹配所有 object 属性或 array 元素。
`[<start>:<end>]`	按定义的范围匹配 array 元素： <start> - 要匹配的第一个索引（包含）；如果未指定，则从开头匹配所有 array 元素；如果为负数，则从 array 末尾开始指定偏移量； <end> - 要匹配的最后一个索引（不包含）；如果未指定，则匹配所有到末尾的 array 元素；如果为负数，则从 array 末尾开始指定偏移量。
`[?(<expression>)]`	通过应用过滤表达式匹配 objects/array 元素。

要查找忽略其祖先关系的匹配段（分离段），必须在其前加上两个点（..）。例如，$..name 或 $..['name'] 返回所有 name 属性的值。

通过在 JSONPath 后添加波浪号（~）后缀，可以提取匹配的元素名称。它返回匹配的 object 的名称，或匹配的 array 监控项的索引（以 string 格式）。输出格式遵循与其他 JSONPath queries 相同的规则 - 确定性路径结果按原样返回，而不确定性路径结果则以 array 形式返回。然而，提取符合确定性路径的元素名称几乎没有实际价值，因为该名称已经是已知的。

过滤表达式

过滤表达式是使用中缀表示法的算术表达式。

支持的操作数：

操作数	描述
`"<text>"` `'<text>'`	文本常量。示例： `'value: \\'1\\''` `"value: '1'"`
`<number>`	支持科学计数法的数值常量。示例： `123`
`<jsonpath starting with $>`	从输入文档根节点引用的JSONPath值；仅支持确定路径。示例： `$.object.name`
`<jsonpath starting with @>`	从当前 object/元素引用的JSONPath值；仅支持确定路径。示例： `@.name`

支持的操作符：

操作符	类型	描述	结果
`-`	Binary	减法	数字
`+`	Binary	加法	数字
`/`	Binary	除法	数字
`*`	Binary	乘法	数字
`==`	Binary	等于	boolean (1/0)
`!=`	Binary	不等于	boolean (1/0)
`<`	Binary	小于	boolean (1/0)
`<=`	Binary	小于等于	boolean (1/0)
`>`	Binary	大于	boolean (1/0)
`>=`	Binary	大于等于	boolean (1/0)
`=~`	Binary	匹配正则表达式	boolean (1/0)
`!`	Unary	boolean 非	boolean (1/0)
`\|\|`	Binary	boolean 或	boolean (1/0)
`&&`	Binary	boolean 与	boolean (1/0)

函数

函数可以用于JSONPath的末尾。如果前一个函数返回的值被后一个函数所接受，则可以将多个函数链接在一起。

支持的函数：

函数	描述	输入	输出
`avg`	输入array中数字的平均值	数字的array	数字
`min`	输入array中数字的最小值	数字的array	数字
`max`	输入array中数字的最大值	数字的array	数字
`sum`	输入array中数字的总和	数字的array	数字
`length`	输入array中的元素数量	array	数字
`first`	array的第一个元素	array	JSON结构（object、array、值），具体取决于输入array的内容

JSONPath聚合函数接受带引号的数值。在需要聚合时，这些值会自动从字符串转换为数值类型。不兼容的输入将导致函数generate返回错误。

输出值

JSONPaths 可以分为确定路径和不确定路径。明确的路径只能返回空值或单个匹配项。不定路径可能会返回多个匹配项：带有分离的多个名称/索引列表、array 片段或表达式段的 JSON 路径。然而，当使用函数时，JSONPath 变得明确，因为函数始终输出单个值。

一个确定的路径返回它所引用的object/array/value。相反，无限路径会返回匹配的 array 的 objects/数组/值的集合。

::: noteimportant 由于内部优化方法，JSONPath query 结果中的属性顺序可能与原始 JSON 属性顺序不一致。例如，JSONPath $.books[1]["author", "title"] 可能返回 ["title", "author"]。如果保持原始属性顺序至关重要，则应考虑替代的后期query处理方法。仅返回OutputFormat格式要求结果

路径格式规则

空格和制表符可用于方括号表示法的段和表达式中，例如：$[ '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	小说
`$.filters['no filters']`	definite	无 "filters"
`$.filters`	definite	{ "price": 10, "category": "fiction", "no filters": "no \"filters\"" }
`$.books[1].title`	definite	荣誉之剑
`$.books[-1].author`	definite	J. R. R. 托尔金
`$.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	["白鲸记", "世纪名言"]
`$.books[1]['author', "title"]`	indefinite	["荣誉之剑", "伊夫林·沃"]
`$..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	["荣誉之剑"] 注意：此 query 表明可以在 queries 中使用算术运算；它可以简化为 `$.books[?(@.id == 2)].title`
`$.books[?(@.id == 2 \\|\\| @.id == 4)].title`	indefinite	["荣誉之剑", "指环王"]
`$.books[?(!(@.id == 2))].title`	indefinite	["世纪名言", "白鲸记", "指环王"]
`$.books[?(@.id != 2)].title`	indefinite	["世纪名言", "白鲸记", "指环王"]
`$.books[?(@.title =~ " of ")].title`	indefinite	["世纪名言", "荣誉之剑", "指环王"]
`$.books[?(@.price > 12.99)].title`	indefinite	["指环王"]
`$.books[?(@.author > "Herman Melville")].title`	indefinite	["世纪名言", "指环王"]
`$.books[?(@.price > $.filters.price)].title`	indefinite	["荣誉之剑", "指环王"]
`$.books[?(@.category == $.filters.category)].title`	indefinite	["荣誉之剑", "白鲸记", "指环王"]
`$.books[?(@.category == "fiction" && @.price < 10)].title`	indefinite	["白鲸记"]
`$..[?(@.id)]`	indefinite	[ { "price": 8.95, "id": 1, "category": "reference", "author": "Nigel Rees", "title": "世纪名言" }, { "price": 12.99, "id": 2, "category": "fiction", "author": "Evelyn Waugh", "title": "荣誉之剑" }, { "price": 8.99, "id": 3, "category": "fiction", "author": "Herman Melville", "title": "白鲸记", "isbn": "0-553-21311-3" }, { "price": 22.99, "id": 4, "category": "fiction", "author": "J. R. R. Tolkien", "title": "指环王", "isbn": "0-395-19395-8" } ]
`$.services..[?(@.price > 50)].description`	indefinite	["A5格式印刷和装订书籍", "重新装订破损书籍"]
`$..id.length()`	definite	4
`$.books[?(@.id == 2)].title.first()`	definite	荣誉之剑
`$..tags.first().length()`	definite	5 注意：`$..tags` 是一个不定路径，因此它返回匹配元素的 array，即 `[["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	注意：没有匹配项的 query 对于确定和不确定路径返回 NULL。
`$.services[?(@.active=="true")].servicegroup`	indefinite	[1001,1000] 注意：文本常量必须用于 boolean 值比较。
`$.services[?(@.active=="false")].servicegroup`	indefinite	[1002] 注意：文本常量必须用于 boolean 值比较。
`$.services[?(@.servicegroup=="1002")]~.first()`	definite	修复

Documentation

4 JSONPath 功能

概述

支持的片段

过滤表达式

函数

输出值

路径格式规则

示例