# 字段值提取函数 本文介绍字段值提取函数的语法规则，包括参数解释、函数示例等。 #### 函数列表 | **类型** | **函数** | **说明** | |---|---|---| | 正则提取 | [e_regex] | 根据正则表达式提取字段的值并赋值给其他字段。支持和其他函数组合使用。 | | JSON提取 | [e_json] | 对特定字段中的JSON对象进行JSON操作，包括JSON展开、JMES提取或者JMES提取后再展开。支持和其他函数组合使用。 | | 分隔符提取 | [e_csv、e_psv、e_tsv] | 使用自定义的分隔符与预定义的字段名，从特定字段中提取多个字段。 - e_csv：默认分隔符为半角逗号（,）。 - e_psv：默认分隔符为竖线（\|）。 - e_tsv：默认分隔符为\\t。 支持和其他函数组合使用。 | | KV模式提取 | [e_kv] | 通过quote提取多个源字段中的键值对信息。支持和其他函数组合使用。 | | KV模式提取 | [e_kv_delimit] | 通过分隔符提取源字段中的键值对信息。 | #### e_regex 根据正则表达式提取字段的值并赋值给其他字段。 - **函数格式** ``` e_regex(key,正则表达式,fields_info,mode="fill-auto",pack_json=None) ``` - **参数说明** | **参数名称** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | 任意 | 是 | 源字段名。如果字段不存在，则不进行任何操作。特殊字段名的设置请参见事件类型。 | | 正则表达式 | String | 是 | 提取字段的正则表达式。 支持捕获组和非捕获组正则表达式。 非捕获有时需要使用分组，且使用前缀?:。例如\\w+@\\w+\\.\\w(?:\\.\\cn)?。关于分组不捕获请参见非捕获组。 | | fields_info | String/ List/ Dict | 否 | 匹配后目标字段名。当正则表达式参数没有配置命名捕获的名称时，必须配置该参数。 | | mode | String | 否 | 字段的覆盖模式。默认为fill-auto。关于更多字段值及含义请参见字段提取检查与覆盖模式。 | | pack_json | String | 否 | 将正则表达式的所有匹配结果打包放入pack_json指定的字段中。默认值是None，表示不打包。 | - **返回结果** 返回附带新字段值的日志。 - **函数示例** 1. 示例1：提取字段中符合表达式的值。 - 测试数据 ``` { "msg": "192.168.0.1 http://... 127.0.0.0" } ``` - 加工规则 ``` # 提取字段msg中出现的第一个IP地址。 e_regex("msg",r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}","ip") ``` - 加工结果 ``` msg: 192.168.0.1 http://... 127.0.0.0 ip: 192.168.0.1 ``` 2. 示例2：提取字段中符合表达式的多个值。 - 测试数据 ``` { "msg": "192.168.0.1 http://... 127.0.0.0" } ``` - 加工规则 ``` # 提取字段msg中出现的两个IP地址，分别赋值给server_ip和client_ip。 e_regex("msg",r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}",["server_ip","client_ip"]) ``` - 加工结果 ``` msg: 192.168.0.1 http://... 127.0.0.0 server_ip: 192.168.0.1 client_ip: 127.0.0.0 ``` 3. 示例3：通过捕获组提取符合表达式的值。 - 测试数据 ``` { "content": "start sys version: deficience, err: 2" } ``` - 加工规则 ``` # 使用正则表达式捕获content中的version和error值。 e_regex("content",r"start sys version: (\w+),\s*err: (\d+)",["version","error"]) ``` - 加工结果 ``` content: start sys version: deficience, err: 2 error: 2 version: deficience ``` 4. 示例4：通过命名捕获组提取字段值。 - 测试数据 ``` { "content": "start sys version: deficience, err: 2" } ``` - 加工规则 ``` e_regex("content",r"start sys version: (?P\w+),\s*err: (?P\d+)") ``` - 加工结果 ``` content: start sys version: deficience, err: 2 error: 2 version: deficience ``` 5. 示例5：使用正则表达式捕获字段dict中的值，并动态命名字段名和其值。 - 测试数据 ``` { "dict": "verify:123" } ``` - 加工规则 ``` e_regex("dict",r"(\w+):(\d+)",{r"k_\1": r"v_\2"}) ``` - 加工结果 ``` dict: verify:123 k_verify: v_123 ``` 6. 示例6：提取字段中符合表达式的值，并打包赋值给name字段。 - 测试数据 ``` { "msg": "192.168.0.1 http://... 127.0.0.0" } ``` - 加工规则 ``` e_regex("msg", r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}", "ip", pack_json="name") ``` - 加工结果 ``` msg:192.168.0.1 http://... 127.0.0.0 name:{"ip": "192.168.0.1"} ``` 7. 示例7：使用正则表达式提取字段dict中的值，动态命名字段名和其值，并打包赋值给name字段。 - 测试数据 ``` { "dict": "x:123, y:456, z:789" } ``` - 加工规则 ``` e_regex("dict", r"(\w+):(\d+)", {r"k_\1": r"v_\2"}, pack_json="name") ``` - 加工结果 ``` dict:x:123, y:456, z:789 name:{"k_x": "v_123", "k_y": "v_456", "k_z": "v_789"} ``` 8. 示例8：通过捕获组提取符合表达式的值，并打包赋值给name字段。 - 测试数据 ``` { "content": "start sys version: deficience, err: 2" } ``` - 加工规则 ``` e_regex( "content", r"start sys version: (\w+),\s*err: (\d+)", ["version", "error"],pack_json="name") ``` - 加工结果 ``` content:start sys version: deficience, err: 2 name:{"version": "deficience", "error": "2"} ``` - **更多参考** 支持和其他函数组合使用。 #### e_json 对特定字段中的JSON对象进行JSON操作，包括JSON展开、JMES提取或者JMES提取后再展开。 - **函数格式** ``` e_json(key, expand=None, depth=100, prefix="__", suffix="__", fmt="simple", sep=".", expand_array=true, fmt_array="{parent}_{index}", include_node=r"[\u4e00-\u9fa5\u0800-\u4e00a-zA-Z][\w\-\.]*", exclude_node="", include_path="", exclude_path="", jmes="", output="", jmes_ignore_none=false, mode='fill-auto' ) ``` - **参数说明** | **参数名称** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | String | 是 | 源字段名。如果字段不存在，则不进行任何操作。 | | expand | Boolean | 否 | 是否将字段展开。 - 没有配置jmes参数时，则默认为true，表示展开。 - 配置jmes参数时，则默认为false，表示不展开。 | | depth | Number | 否 | 字段展开的深度。取值范围为1\~2000，1表示只展开第一层，默认为100层。 | | prefix | String | 否 | 展开时添加为字段名的前缀。 | | suffix | String | 否 | 展开时添加为字段名的后缀。 | | fmt | String | 否 | 格式化方式。取值： - simple（默认值）：表示将节点名作为字段名。展示形式为{prefix}{current}{suffix}。 - full：表示将父节点与当前节点合并作为字段名。展示形式为{parent_list_str}{sep}{prefix}{current}{suffix}。分隔符是由sep参数指定，默认为.。 - parent：表示用完整的路径作为字段名。展示形式为{parent}{sep}{prefix}{current}{suffix}。分隔符是由sep参数指定，默认为.。 - root：表示将根节点与当前节点合并作为字段名。展示形式为{parent_list\[0\]}{sep}{prefix}{current}{suffix}。分隔符由sep参数指定，默认为.。 | | sep | String | 否 | 父子节点格式化的分隔符。当fmt取值为full、parent或root时需要设置。默认为.。 | | expand_array | Boolean | 否 | 是否将数组展开。默认为true表示展开数组。 | | fmt_array | String | 否 | 数组展开的格式化方式，格式为{parent_rlist\[0\]}_{index}。也可以使用最多五个占位符自定义格式化字符串：parent_list，current，sep，prefix，suffix。 | | include_node | String/ Number | 否 | 节点允许名单，表示过滤时包含的节点名称。默认只有中文、数字、字母和_.-的节点才会被自动展开。 | | exclude_node | String | 否 | 节点限制名单，表示过滤时排除的节点名称。 | | include_path | String | 否 | 节点允许名单，表示过滤时包含的节点路径。 | | exclude_path | String | 否 | 节点限制名单，表示过滤时排除的节点路径。 | | jmes | String | 否 | 将字段值转化为JSON对象并通过JMES提取特定值。 | | output | String | 否 | 通过JMES提取特定值时输出的字段名。 | | jmes_ignore_none | Boolean | 否 | 当JMES提取不到值时是否忽略。默认为true表示忽略，否则输出一个空字符串。 | | mode | String | 否 | 字段的覆盖模式。默认为fill-auto。 | - JSON展开过滤 - 如果设置了节点允许名单，则内容必须包含在节点允许名单中然后才会在结果中出现。节点允许名单正则示例：e_json("json_data_filed", ...., include_node=r'key\\d+')。 - 如果设置了节点限制名单，则内容必须包含在节点限制名单中然后才不会在结果中出现。节点限制名单正则示例：e_json("json_data_filed", ...., exclude_node=r'key\\d+')。 - 展开节点路径：正则include_path与exclude_path从路径开头匹配，匹配路径是以.分隔。 - JMES过滤 使用JMES选择、计算。 - 选择特定JSON路径下的元素属性列表：e_json(..., jmes="cve.vendors\[\*\].product",output="product") - 用逗号拼接特定JSON路径下的元素属性：e_json(..., jmes="join(',', cve.vendors\[\*\].name)",output="vendors") - 计算特定JSON路径下元素的最大属性值：e_json(..., jmes="max(words\[\*\].score)",output="hot_word") - 当特定路径不存在或为空时，返回一个空字符串：e_json(..., jmes="max(words\[\*\].score)",output="hot_word", jmes_ignore_none=false) - parent_list和parent_rlist，以如下示例说明。 测试数据： ``` { "data": { "k1": 100,"k2": {"k3": 200,"k4": {"k5": 300}}} } ``` parent_list是将父节点从左到右排列。 ``` e_json("data", fmt='{parent_list[0]}-{parent_list[1]}#{current}') ``` 得到的日志： ``` data:{ "k1": 100,"k2": {"k3": 200,"k4": {"k5": 300}}} data-k2#k3:200 data-k2#k5:300 ``` parent_rlist是将父节点从右到左排列。 ``` e_json("data", fmt='{parent_rlist[0]}-{parent_rlist[1]}#{current}') ``` 得到的日志： ``` data:{ "k1": 100,"k2": {"k3": 200,"k4": {"k5": 300}}} k2-data#k3:200 k4-k2#k5:300 ``` - 返回结果 返回附带新字段值的日志。 - 函数示例 1. 示例1：字段展开操作。 - 测试数据 ``` { "data": {"k1": 100, "k2": 200} } ``` - 加工规则 ``` e_json("data",depth=1) ``` - 加工结果 ``` data: {"k1": 100, "k2": 200} k1: 100 k2: 200 ``` 2. 示例2：给字段名添加前缀和后缀。 - 测试数据 ``` { "data": {"k1": 100, "k2": 200} } ``` - 加工规则 ``` e_json("data", prefix="data_", suffix="_end") ``` - 加工结果 ``` data: {"k1": 100, "k2": 200} data_k1_end: 100 data_k2_end: 200 ``` 3. 示例3：将字段按照不同格式展开。 - 测试数据 ``` { "data": {"k1": 100, "k2": {"k3": 200, "k4": {"k5": 300} } } } ``` - fmt=full格式 ``` e_json("data", fmt='full') ``` ``` data: {"k1": 100, "k2": {"k3": 200, "k4": {"k5": 300} } } data.k1: 100 data.k2.k3: 200 data.k2.k4.k5: 300 ``` - fmt=parent格式 ``` e_json("data", fmt='parent') ``` ``` data: {"k1": 100, "k2": {"k3": 200, "k4": {"k5": 300} } } data.k1: 100 k2.k3: 200 k4.k5: 3000 ``` - fmt=root格式 ``` e_json("data", fmt='root') ``` ``` data: {"k1": 100, "k2": {"k3": 200, "k4": {"k5": 300} } } data.k1: 100 data.k3: 200 data.k5: 300 ``` 4. 示例4：使用指定分隔符、字段名前缀和字段名后缀提取JSON - 测试数据 ``` { "data": {"k1": 100, "k2": {"k3": 200, "k4": {"k5": 300} } } } ``` - 加工规则 ``` e_json("data", fmt='parent', sep="@", prefix="__", suffix="__") ``` - 加工结果 ``` data: {"k1": 100, "k2": {"k3": 200, "k4": {"k5": 300} } } data@__k1__：100 k2@__k3__：200 k4@__k5__：300 ``` 5. 示例5：指定fmt_array参数，按照数组方式提取JSON。 - 测试数据 ``` { "people": [{"name": "xm", "gender": "boy"}, {"name": "xz", "gender": "boy"}, {"name": "xt", "gender": "girl"}] } ``` - 加工规则 ``` e_json("people", fmt='parent', fmt_array="{parent_rlist[0]}-{index}") ``` - 加工结果 ``` people: [{"name": "xm", "gender": "boy"}, {"name": "xz", "gender": "boy"}, {"name": "xt", "gender": "girl"}] people-0.name: xm people-0.gender: boy people-1.name: xz people-1.gender: boy people-2.name: xt people-2.gender: girl ``` 6. 示例6：使用JMES提取JSON对象。 - 测试数据 ``` { "data": { "people": [{"first": "James", "last": "d"},{"first": "Jacob", "last": "e"}],"foo": {"bar": "baz"}} } ``` - 加工规则 ``` e_json("data", jmes='foo', output='jmes_output0') e_json("data", jmes='foo.bar', output='jmes_output1') e_json("data", jmes='people[0].last', output='jmes_output2') e_json("data", jmes='people[*].first', output='jmes_output3') ``` - 加工结果 ``` data: { "people": [{"first": "James", "last": "d"},{"first": "Jacob", "last": "e"}],"foo": {"bar": "baz"}} jmes_output0: {"bar": "baz"} jmes_output1: baz jmes_output2: d jmes_output3: ["james", "jacob"] ``` - **更多参考** 支持和其他函数组合使用。 #### e_csv、e_psv、e_tsv 使用自定义的分隔符与预定义的字段名，从特定字段中提取多个字段。 - e_csv：默认分隔符为半角逗号（,）。 - e_psv：默认分隔符为竖线（\|）。 - e_tsv：默认分隔符为\\t。 - **函数格式** ``` e_csv(源字段名, 目标字段列表, sep=",", quote='"', restrict=true, mode="fill-auto") e_psv(源字段名, 目标字段列表, sep="|", quote='"', restrict=true, mode="fill-auto") e_tsv(源字段名, 目标字段列表, sep="\t", quote='"', restrict=true, mode="fill-auto") ``` - **参数说明** | **参数名称** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | 源字段名 | 任意 | 是 | 源字段名。如果字段不存在，则不进行任何操作。 | | 目标字段列表 | 任意 | 是 | 字段值经过分隔符分隔后的每个值对应的字段名。可以是字符串的列表，例如：\["error", "message", "result"\]。 当字段名中不包含逗号时，也可以直接用逗号作为分隔字符，例如："error, message, result"。 | | sep | String | 否 | 分隔符，只能是单个字符。 | | quote | String | 否 | 引用符，用于包裹值的字符。当值包含分隔符时需要使用。 | | restrict | Boolean | 否 | 是否采用严格模式，默认为false表示非严格模式。当分隔值的个数与目标字段列表数不一致时： - 严格模式下不进行任何操作。 - 非严格模式下对前几个可以配对的字段进行赋值。 | | mode | String | 否 | 字段的覆盖模式。默认为fill-auto。 | - **返回结果** 返回附带新字段值的日志。 - **函数示例** 以e_csv为例，e_psv和e_tsv功能类似。 - 测试数据 ``` { "content": "192.168.0.100,10/Jun/2019:11:32:16 +0800,example.aadoc.com" } ``` - 加工规则 ``` e_csv("content", "remote_addr, time_local,host") ``` - 加工结果 ``` content: 192.168.0.100,10/Jun/2019:11:32:16 +0800,example.aadoc.com remote_addr: 192.168.0.100 time_local: 10/Jun/2019:11:32:16 +0800 host: example.aadoc.com ``` - **更多参考** 支持和其他函数组合使用。 #### e_kv 通过quote提取多个源字段中的键值对信息。 - **函数格式** ``` e_kv(源字段或源字段列表, sep="=", quote='"', escape=false, prefix="", suffix="", mode="fill-auto") ``` - **参数说明** | **参数名称** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | 源字段或源字段列表 | 字符串或字符串列表 | 是 | 字段名或多个字段名的列表。 | | sep | String | 否 | 关键字与值的正则表达式的分隔符串，默认为=，不限于单个字符。 **说明** 可以使用非捕获分组，但不能使用捕获分组。 | | quote | String | 否 | 引用符，用于包裹值的字符。默认为"。 **说明** 提取的动态键值对的值一般需要quote来包括，例如：a="abc"，b="xyz"如果提取对象中不包含，则只提取如下字符集的值：中文字母数字_-.%\~。例如a=中文ab12_-.%\~\|abc b=123可以提取a: 中文ab12_-.%\~，b: 123。 | | escape | Boolean | 否 | 是否自动提取反转字符的值。默认为false表示否。例如key="abc\\"xyz"默认提取字段key的值为abc\\，设置escape=true时，提取的值为abc"xyz。 | | prefix | String | 否 | 给提取的字段名添加前缀。 | | suffix | String | 否 | 给提取的字段名添加后缀。 | | mode | String | 否 | 字段的覆盖模式。默认为fill-auto。 | - **返回结果** 返回附带新字段值的日志。 - **函数示例** 1. 示例1：使用默认分隔符=提取键值对信息。 - 测试数据 ``` { "http_refer": "https://video.developer.aadoc.com/s?q=asd&a=1&b=2" } ``` ![](https://support.huaweicloud.com/usermanual-lts/public_sys-resources/note_3.0-zh-cn.png) 如果测试数据为request_uri: a1=1\&a2=\&a3=3，a2值为空，则使用e_kv()函数无法提取出a2。您可以使用e_regex()函数进行提取，例如e_regex("request_uri",r'(\\w+)=(\[\^=\&\]\*)',{r"\\1":r"\\2"},mode="overwrite")。 - 加工规则 ``` e_kv("http_refer") ``` - 加工结果 ``` http_refer: https://video.developer.aadoc.com/s?q=asd&a=1&b=2 q: asd a: 1 b: 2 ``` 2. 示例2：给字段名增加前缀和后缀。 - 测试数据 ``` { "http_refer": "https://video.developer.aadoc.com/s?q=asd&a=1&b=2" } ``` - 加工规则 ``` e_kv( "http_refer", sep="=", quote='"', escape=false, prefix="data_", suffix="_end", mode="fill-auto", ) ``` - 加工结果 ``` http_refer: https://video.developer.aadoc.com/s?q=asd&a=1&b=2 data_q_end: asd data_a_end: 1 data_b_end: 2 ``` 3. 示例3：提取字段content2中的键值对信息，使用escape参数提取反转字符的值。 - 测试数据 ``` { "content2": "k1:\"v1\\"abc\", k2:\"v2\", k3: \"v3\"" } ``` - 加工规则 ``` e_kv("content2", sep=":", escape=true) ``` - 加工结果 ``` content2: k1:"v1\"abc", k2:"v2", k3: "v3" k1: v1"abc k2: v2 k3: v3 ``` - **更多参考** 支持和其他函数组合使用。 #### e_kv_delimit 通过分隔符提取源字段中的键值对信息。 - **函数格式** ``` e_kv_delimit(源字段或源字段列表, pair_sep=r"\s", kv_sep="=", prefix="", suffix="", mode="fill-auto") ``` - **参数说明** | **参数名称** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | 源字段或源字段列表 | 字符串或字符串列表 | 是 | 字段名或多个字段名的列表。 | | pair_sep | String | 否 | 用于分隔键值对的正则字符集，默认为\\s。例如\\s\\w、abc\\s等。 **说明** 如果您需要使用字符串对字段进行分隔，推荐您使用str_replace或regex_replace将字符串转换成字符作为分隔符，然后再使用e_kv_delimit函数对字段进行分隔。 | | kv_sep | String | 否 | 用于分隔键值对的正则字符串，默认为=，不限于单个字符。 可以使用非捕获分组，但不能使用捕获分组。 | | prefix | String | 否 | 给提取的字段名添加前缀。 | | suffix | String | 否 | 给提取的字段名添加后缀。 | | mode | String | 否 | 字段的覆盖模式。默认为fill-auto。 | - **返回结果** 返回附带新字段值的日志。 - **函数示例** 1. 示例1：使用默认分隔符=提取键值对信息。 - 测试数据 ``` { "data": "i=c1 k1=v1 k2=v2 k3=v3" } ``` ![](https://support.huaweicloud.com/usermanual-lts/public_sys-resources/note_3.0-zh-cn.png) 如果测试数据为request_uri: a1=1\&a2=\&a3=3，a2值为空，则使用e_kv_delimit()函数无法提取出a2。您可以使用e_regex()函数进行提取，例如e_regex("request_uri",r'(\\w+)=(\[\^=\&\]\*)',{r"\\1":r"\\2"}, mode="overwrite")。 - 加工规则 ``` e_kv_delimit("data") ``` - 加工结果 ``` data: i=c1 k1=v1 k2=v2 k3=v3 i: c1 k2: v2 k1: v1 k3: v3 ``` 2. 示例2：使用分隔符\&?提取键值对信息。 - 测试数据 ``` { "data": "k1=v1&k2=v2?k3=v3" } ``` - 加工规则 ``` e_kv_delimit("data",pair_sep=r"&?") ``` - 加工结果 ``` data: k1=v1&k2=v2?k3=v3 k2: v2 k1: v1 k3: v3 ``` 3. 示例3：使用正则表达式提取键值对信息。 - 测试数据 ``` { "data": "k1=v1 k2:v2 k3=v3" } ``` - 加工规则 ``` e_kv_delimit("data", kv_sep=r"(?:=|:)") ``` - 加工结果 ``` data: k1=v1 k2:v2 k3=v3 k2: v2 k1: v1 k3: v3 ```