本文档主要介绍JSON、XML、IP与Protobuf函数的语法规则，包括参数解释、函数示例等。

函数列表

类型 函数 说明
JSON json_select 根据JMES语法提取或计算JSON表达式中特定的值。
json_parse 将值解析为JSON对象。
XML xml_to_json 将xml转成JSON再做展开操作。
protobuf pb_to_json 将Protobuf数据转成JSON数据。
Gzip gzip_compress 压缩数据，返回一个数据压缩后再进行base64编码的数据对象。
gzip_decompress 对数据进行base64解码后，再对数据解压缩，返回一个包含解压数据的对象。
IP geo_parse 根据IP地址解析出所属国家省市信息。
ip_cidrmatch 判断IP地址是否属于CIDR地址块。
ip_version 判断IP地址为IPv4还是IPv6。
ip_type 判断IP地址为私有地址还是公有地址。
ip_makenet 将单个IP地址转换为CIDR地址块。
ip_to_format 将输入的CIDR地址块按照Prefixlen或者Netmask格式输出。
ip_overlaps 判断两个网段是否存在重叠。

json_select

  • 函数格式 
    json_select(值, "jmes表达式", default=None, restrict=False)
  • 参数说明
    参数名称 参数类型 是否必填 说明
    值 任意 是 传入待提取字段的JSON表达式或字段。
    jmes表达式 String 是 JMES表达式，表示提取的字段。
    default 任意 否 如果提取字段不存在，则返回此处设置的默认值。默认为None。
    restrict Bool 否 默认False。严格模式下，非标准JSON模式时，如果restrict为True则会报错。
  • 返回结果

    返回提取到的值。

  • 函数示例
    • 示例1：从content提取name的值。
      • 原始日志 
        content:  {"name": "xiaoming", "age": 10}
      • 加工规则 
        e_set("json_filter",json_select(v("content"), "name"))
      • 加工结果
        content:  {"name": "xiaoming", "age": 10}
json_filter:  xiaoming
    • 示例2：从content提取name所有的值。
      • 原始日志 
        content:  {"name": ["xiaoming", "xiaowang", "xiaoli"], "age": 10}
      • 加工规则 
        e_set("json_filter",json_select(v("content"), "name[*]"))
e_set("json_filter2",str_join("*", json_select(v('content'), "name[*]")))
      • 加工结果 
        content:  {"name": ["xiaoming", "xiaowang", "xiaoli"], "age": 10}
json_filter:  ["xiaoming", "xiaowang", "xiaoli"]
json_filter2: xiaoming*xiaowang*xiaoli
    • 示例3：从content提取name的值，返回default值。
      • 原始日志 
        content:  {"name": "xiaoming", "age": 10}
      • 加工规则 
        e_set("json_filter",json_select(v("content"), "name1.name2", default="default"))
      • 加工结果 
        content:  {"name": "xiaoming", "age": 10}
json_filter: default

json_parse

  • 函数格式 
    json_parse(值, default=None, restrict=False)
  • 参数说明
    参数名称 参数类型 是否必填 说明
    值 String 是 传入需要被解析的字段。
    default 任意 否 如果提取字段不存在，则返回此处设置的默认值。默认为None。
    restrict Bool 否 默认False。严格模式，非标准JSON模式时，如果restrict为True则会报错。
  • 返回结果

    返回转换后的JSON对象。

  • 函数示例
    • 原始日志 
      content:  {"abc": 123, "xyz": "test" }
    • 加工规则 
      e_set("json",json_parse(v("content")))
    • 加工结果 
      content:  {"abc": 123, "xyz": "test" }
json:  {"abc": 123, "xyz": "test"}

xml_to_json

  • 函数格式 
    xml_to_json(值)
  • 参数说明
    参数名称 参数类型 是否必填 说明
    值 String 是 传入需要被转换的字段。
  • 返回结果

    返回转换后的JSON数据。

  • 函数示例
    • 原始日志 
      str : <?xmlversion="1.0"?><data><countryname="Liechtenstein"><rank>1</rank><year>2008</year><gdppc>141100</gdppc><neighborname="Austria"direction="E"/><neighborname="Switzerland"direction="W"/></country><countryname="Singapore"><rank>4</rank><year>2011</year><gdppc>59900</gdppc><neighborname="Malaysia"direction="N"/></country><countryname="Panama"><rank>68</rank><year>2011</year><gdppc>13600</gdppc><neighborname="Costa Rica"direction="W"/><neighborname="Colombia"direction="E"/></country></data>
    • 加工规则 
      e_set("str_json",xml_to_json(v("str")))
    • 加工结果 
      str : <?xmlversion="1.0"?><data><countryname="Liechtenstein"><rank>1</rank><year>2008</year><gdppc>141100</gdppc><neighborname="Austria"direction="E"/><neighborname="Switzerland"direction="W"/></country><countryname="Singapore"><rank>4</rank><year>2011</year><gdppc>59900</gdppc><neighborname="Malaysia"direction="N"/></country><countryname="Panama"><rank>68</rank><year>2011</year><gdppc>13600</gdppc><neighborname="Costa Rica"direction="W"/><neighborname="Colombia"direction="E"/></country></data>
str_json : {"data": {"country": [{"@name": "Liechtenstein", "rank": "1", "year": "2008", "gdppc": "141100", "neighbor": [{"@name": "Austria", "@direction": "E"}, {"@name": "Switzerland", "@direction": "W"}]}, {"@name": "Singapore", "rank": "4", "year": "2011", "gdppc": "59900", "neighbor": {"@name": "Malaysia", "@direction": "N"}}, {"@name": "Panama", "rank": "68", "year": "2011", "gdppc": "13600", "neighbor": [{"@name": "Costa Rica", "@direction": "W"}, {"@name": "Colombia", "@direction": "E"}]}]}}

pb_to_json

  • 函数格式 
    pb_to_json(pb_data,pb_py_path_str,pb_fun_name)
  • 参数说明
    参数名称 参数类型 是否必填 说明
    pb_data String 是 传入要转换JSON的protobuf数据或字段名。
    pb_py_path_str String 是 Protobuf文件名。例如addressbook.proto文件取addressbook。
    pb_fun_name String 是 Protobuf文件中消息名。
  • 返回结果

    返回转换后的JSON数据。

  • 函数示例
    addressbook.proto文件： 
    '''addressbook.proto文件'''
syntax = "proto3";
message Person {
  string name = 1;
  int32 id = 2;
  string email = 3;
  string university = 5;
  int32 age = 6;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
  }

  repeated PhoneNumber phones = 4;
}

message AddressBook {
  repeated Person people = 1;
}
    • 原始日志 
      content: \n3\n\x05twiss\x10\x01\x1a\x0ftwiss@gkate.com"\x0f\n\x0b13099922287\x10\x01*\x04Henu0\x18\nC\n\x04Iran\x10\x02\x1a\x10Iran@alibaba.com"\x0f\n\x0b13022244455\x10\x01*\x14West Leak University0\x02
    • 加工规则 
      e_set("data_json",pb_to_json(v("content"),"addressbook","AddressBook"))
    • 加工结果 
      content: \n3\n\x05twiss\x10\x01\x1a\x0ftwiss@gkate.com"\x0f\n\x0b13099922287\x10\x01*\x04Henu0\x18\nC\n\x04Iran\x10\x02\x1a\x10Iran@alibaba.com"\x0f\n\x0b13022244455\x10\x01*\x14West Leak University0\x02
data_json : {'people': [{'name': 'twiss', 'id': 1, 'email': 'twiss@gkate.com', 'phones': [{'number': '13099922287', 'type': 1}], 'university': 'Henu', 'age': 24}, {'name': 'Iran', 'id': 2, 'email': 'Iran@alibaba.com', 'phones': [{'number': '13022244455', 'type': 1}], 'university': 'West Leak University', 'age': 2}]}

geo_parse

  • 函数格式 
    geo_parse("ip",ip_db,keep_fields=None,provider="ipip")
  • 参数说明
    参数名称 参数类型 是否必填 说明
    ip IP字符串 是 IP字符串。
    ip_db IP库内容 是 唯一IP库，当前使用res_oss_file(endpoint, ak_id, ak_key, bucket, file, format='text', change_detect_interval=0,fetch_interval=2,refresh_retry_max=60,encoding='utf8',error='ignore')，参数定义请参见res_oss_file，该函数获取IP库使用的形式为format='binary'。
    keep_fields 元组 否 返回的字典中包含的key信息。默认信息如下：
    • city：表示城市名称。
    • region：表示省份名称。
    • country：表示国家名称。

    例如keep_fields=("city","country")表示仅输出city和country字段信息。

    此外keep_fields也支持重命名。例如(("city","cty"),("country","state"))表示以cty和state形式输出。

    provider 字符串 否 取值如下：
    • ipip：默认值。用来解析ipdb库提供的二进制IP地址库，下载地址为ipip。
    • ip2location：用来解析ip2location提供的全球IP二进制解析库，下载地址为ip2location。仅支持二进制包。
  • 返回结果
    返回字典形式数据，包含如下内容： 
    {
  "city": "...",
  "province":"...",
  "country": "..."
}
  • 函数示例
    • 示例1
      • 原始日志 
        ip : 1.2.3.4
      • 加工规则 
        e_set("geo",geo_parse(v("ip"), ip_db=res_oss_file(endpoint='http://oss-cn-hangzhou.aliyuncs.com',
                                                 ak_id='your ak_id',
                                                 ak_key='your ak_key',
                                                 bucket='your bucket', file='ipipfree.ipdb',
                                                               format='binary',change_detect_interval=20)))
      • 加工结果 
        ip : 1.2.3.4
geo :{'city': '杭州', 'province':'浙江省','country': '中国'}
    • 示例2：选择输出域并且重命名。
      • 原始日志 
        ip : 1.2.3.4
      • 加工规则 
        e_set("geo",geo_parse(v("ip"), ip_db=res_oss_file(endpoint='http://oss-cn-hangzhou.aliyuncs.com',
                                                 ak_id='your ak_id',
                                                 ak_key='your ak_key',
                                                 bucket='your bucket', file='ipipfree.ipdb',
                                                               format='binary',change_detect_interval=20),keep_fields=(("city","cty"),("country","state"),("province","pro"))))
      • 加工结果 
        ip : 1.2.3.4
geo :{ "state": "中国","pro": "浙江省","cty": "杭州"}
    • 示例3：选择输出域。
      • 原始日志 
        ip : 1.2.3.4
      • 加工规则 
        e_set("geo",geo_parse(v("ip"), ip_db=res_oss_file(endpoint='http://oss-cn-hangzhou.aliyuncs.com',
                                                 ak_id='your ak_id',
                                                 ak_key='your ak_key',
                                                 bucket='your bucket', file='ipipfree.ipdb',
                                                               format='binary',change_detect_interval=20),keep_fields=("country","province")))
      • 加工结果 
        ip : 1.2.3.4
geo :{ "country": "中国","province": "浙江省"}
    • 示例4：使用ip2location全球IP解析库。
      • 原始日志 
        ip:19.0.0.0
      • 加工规则 
        e_set("geo", geo_parse(v("ip"), ip_db=res_oss_file(endpoint='http://oss-cn-hangzhou.aliyuncs.com',ak_id="your ak_id", ak_key="your ak_serect", bucket='log-etl-staging', file='your ip2location bin file', format='binary', change_detect_interval=20),provider="ip2location"))
      • 加工结果 
        ip:19.0.0.0
geo: {"city":"Dearborn","province":"Michigan","country":"United States"}
      数据加工使用的是ip2location的开源python sdk，详情请参见ip2location python sdk。ip2location python sdk支持解析的字段如下所示，数据加工同步支持解析如下所有字段。如果您在使用过程中发现无法解析出目标字段，请检查使用的ip2location解析库是否包含目标字段。
      country_short
country_long /  数据加工使用country字段替代
region  / 数据加工使用province字段替代
city
isp
latitude
longitude
domain
zipcode
timezone
netspeed
idd_code
area_code
weather_code
weather_name
mcc
mnc
mobile_brand
elevation
usage_type

gzip_compress

压缩数据，返回一个数据压缩后再进行base64编码的数据对象。

  • 函数格式 
    gzip_compress(v("data"),compresslevel=6,to_format="base64",encoding="utf-8'")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    data 任意 是 输入需要压缩的数据。
    compresslevel Int 否 用于控制压缩等级，可配置为0~9的整数。默认值为6。
    • 1：压缩速度最快但压缩比例最小。
    • 9：压缩速度最慢但压缩比例最大。
    • 0：不压缩。
    to_format String 否 经过压缩后的数据进行base64编码，目前只支持进行base64编码。
    encoding String 否 编码格式，默认为utf-8，其他编码格式请参见标准编码格式。
  • 返回结果

    返回压缩数据的base64编码后的对象。

  • 函数示例
    • 原始日志 
      content: I always look forward to my holidays whether I travel or stay at home.
    • 加工规则 
      e_set("base64_encode_gzip_compress",gzip_compress(v("content"),to_format="base64"))
    • 加工结果 
      content: I always look forward to my holidays whether I travel or stay at home.
base64_encode_gzip_compress: H4sIAA8JXl4C/xXK0QmAMAwFwFXeBO7RMQKNREx5kAZDtle/7wbES3rDyRsnoyQmklgNo1/ztzJN08BAhjzqYGCnNCS/tPR4AcgrnWVGAAAA

gzip_decompress

对数据进行base64解码后，再对数据解压缩，返回一个包含解压数据的对象。

  • 函数格式 
    gzip_decompress(v("data"),from_format="base64",encoding="utf-8'")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    data 任意 是 输入需要解压的数据。
    from_format String 否 输入已进行base64解码的数据，目前只支持base64解码后的数据。
    encoding String 否 编码格式，默认utf-8，其他编码格式请参见标准编码格式。
  • 返回结果

    返回数据解压后的对象。

  • 函数格式
    • 原始日志 
      content: H4sIAA8JXl4C/xXK0QmAMAwFwFXeBO7RMQKNREx5kAZDtle/7wbES3rDyRsnoyQmklgNo1/ztzJN08BAhjzqYGCnNCS/tPR4AcgrnWVGAAAA
    • 加工规则 
      e_set("gzip_decompress",gzip_decompress(v("content"),from_fmat="base64"))
    • 加工结果 
      content: H4sIAA8JXl4C/xXK0QmAMAwFwFXeBO7RMQKNREx5kAZDtle/7wbES3rDyRsnoyQmklgNo1/ztzJN08BAhjzqYGCnNCS/tPR4AcgrnWVGAAAA
gzip_decompress: I always look forward to my holidays whether I travel or stay at home.

ip_cidrmatch

根据IP地址是否与CIDR子网匹配返回布尔值。使用此函数来确定IP地址是否属于CIDR地址块。当IP地址属于CIDR地址块时，返回TRUE。此函数支持IPv4和IPv6。

  • 函数格式 
    ip_cidrmatch("CIDR地址块","IP地址",default="")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    CIDR地址块 String 是 输入CIDR地址块，如：123.132.32.0/25。
    IP地址 String 是 输入IP地址。
    default 任意 否 设置default的值（可为空），如果IP地址与CIDR地址块不匹配时，返回该值。
  • 返回结果

    如果IP地址与CIDR地址块匹配，返回True，否则返回False。

  • 函数示例
    • 示例1：IP地址（IPv4）与CIDR地址块匹配
      • 原始日志 
        cidr_subnet: 192.168.1.0/24
Ip: 192.168.1.100
      • 加工规则 
        e_set("is_belong",ip_cidrmatch(v("cidr_subnet"),v("ip")))
      • 加工结果 
        cidr_subnet: 192.168.1.0/24
ip: 192.168.1.100
is_belong: true
    • 示例2：IP地址（IPv4）与CIDR地址块不匹配
      • 原始日志 
        cidr_subnet: 192.168.1.0/24
Ip: 10.10.1.100
      • 加工规则 
        e_set("is_belong",ip_cidrmatch(v("cidr_subnet"),v("ip")))
      • 加工结果 
        cidr_subnet: 192.168.1.0/24
ip: 10.10.1.100
is_belong: false
    • 示例3：IP地址与CIDR地址块无法匹配
      • 原始日志 
        cidr_subnet: -11
Ip: 10.10.1.100
      • 加工规则 
        e_set("is_belong",ip_cidrmatch(v("cidr_subnet"),v("ip"),default="unknown"))
      • 加工结果 
        cidr_subnet: -11
ip: 10.10.1.100
is_belong: unknown

ip_version

判断IP地址为IPv4还是IPv6。

  • 函数格式 
    ip_version("IP地址",default="")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    IP地址 String 是 输入IP地址。
    default 任意 否 设置default的值（可为空），无法判断IP地址版本时，返回该值。
  • 返回结果

    返回IPv6或者IPv4。

  • 函数示例
    • 示例1：IPv4版本
      • 原始日志 
        Ip: 192.168.1.100
      • 加工规则 
        e_set("version",ip_version(v("ip")))
      • 加工结果 
        ip: 192.168.1.100
version: IPv4
    • 示例2：IPv6版本
      • 原始日志 
        Ip: ::1
      • 加工规则 
        e_set("version",ip_version(v("ip")))
      • 加工结果 
        ip: ::1
version: IPv6

ip_type

判断IP地址是私有地址还是公有地址。

  • 函数格式 
    ip_type("IP地址",default="")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    IP地址 String 是 输入IP地址。
    default 任意 否 设置default的值（可为空），无法判断IP地址类型时，返回该值。
  • 返回结果

    返回IP类型的描述：private、reserved、loopback、public、unknown等。

  • 函数示例
    • 示例1：
      • 原始日志 
        Ip: 127.0.0.1
      • 加工规则 
        e_set("type",ip_type(v("ip")))
      • 加工结果 
        ip: 127.0.0.1
type: loopback
    • 示例2：
      • 原始日志 
        Ip: 192.168.1.1
      • 加工规则 
        e_set("type",ip_type(v("ip")))
      • 加工结果 
        ip: 192.168.1.1
type: private
    • 示例3：
      • 原始日志 
        Ip: 195.185.1.2
      • 加工规则 
        e_set("type",ip_type(v("ip")))
      • 加工结果 
        ip: 195.185.1.2
type: public
    • 示例4：IPv6 LOOKBACK类型
      • 原始日志 
        Ip: ::1
      • 加工规则 
        e_set("type",ip_type(v("ip")))
      • 加工结果 
        ip: ::1
type: loopback
    • 示例5：allocated ripe ncc类型
      • 原始日志 
        Ip: 2001:0658:022a:cafe:0200::1
      • 加工规则 
        e_set("type",ip_type(v("ip")))
      • 加工结果 
        ip: 2001:0658:022a:cafe:0200::1
type: allocated ripe ncc

ip_makenet

将单个IP地址转换为CIDR地址块。

  • 函数格式 
    ip_makenet("IP地址","子网掩码",default="")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    IP地址 String 是 输入IP地址。
    子网掩码 String 是 输入子网掩码，例如：255.255.255.0。
    说明 如果IP地址中输入的是IP网段，则子网掩码可以为空。
    default 任意 否 设置default的值（可为空），无法将IP地址转成CIDR地址块时，返回该值。
  • 返回结果

    返回CIDR地址块。

  • 函数示例：
    • 示例1：
      • 原始日志 
        Ip: 192.168.1.0
      • 加工规则 
        e_set("makenet",ip_makenet(v("ip"),"255.255.255.0"))
      • 加工结果 
        ip: 192.168.1.0
makenet: 192.168.1.0/24
    • 示例2：IP地址范围（1）
      • 原始日志 
        Ip: 192.168.1.0-192.168.1.255
      • 加工规则 
        e_set("makenet",ip_makenet(v("ip")))
      • 加工结果 
        ip: 192.168.1.0-192.168.1.255
makenet: 192.168.1.0/24
    • 示例3：IP地址范围（2）
      • 原始日志 
        Ip: 192.168.1.0/255.255.255.0
      • 加工规则 
        e_set("makenet",ip_makenet(v("ip")))
      • 加工结果 
        ip: 192.168.1.0/255.255.255.0
makenet: 192.168.1.0/24

ip_to_format

将输入的CIDR地址块按照Prefixlen或者Netmask格式输出。

  • 函数格式 
    ip_to_format("CIDR地址块",格式码,default="")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    CIDR地址块 String 是 输入CIDR地址块，例如：192.168.1.0/24
    格式码 Int 否 设置返回格式，默认为0。
    • 0：表示无格式返回。
    • 1：按照prefix格式返回。
    • 2：按照netmask格式返回。
    • 3：按照IP网段格式返回。
    default 任意 否 设置default的值（可为空），无法将输入的CIDR地址块按照格式输出时，返回该值。
  • 返回结果

    返回特定格式的IP地址。

  • 函数示例
    • 示例1：
      • 原始日志 
        Ip: 192.168.1.0/24
      • 加工规则 
        e_set("strNormal",ip_to_format(v("ip"),0))
      • 加工结果 
        ip: 192.168.1.0/24
strNormal: 192.168.1.0/24
    • 示例2：
      • 原始日志 
         Ip: 192.168.1.0/24
      • 加工规则 
        e_set("strNormal",ip_to_format(v("ip"),1))
      • 加工结果 
        ip: 192.168.1.0/24
strNormal: 192.168.1.0/24
    • 示例3：
      • 原始日志 
        Ip: 192.168.1.0/24
      • 加工规则 
        e_set("strNormal",ip_to_format(v("ip"),2))
      • 加工结果 
        ip: 192.168.1.0/24
strNormal: 192.168.1.0/255.255.255.0
    • 示例4：
      • 原始日志 
        Ip: 192.168.1.0/24
      • 加工规则 
        e_set("strNormal",ip_to_format(v("ip"),3))
      • 加工结果 
        ip: 192.168.1.0/24
strNormal: 192.168.1.0-192.168.1.255

ip_overlaps

判断两个网段是否存在重叠。

  • 函数格式 
    ip_overlaps("CIDR地址块1","CIDR地址块2",default="")
  • 参数说明
    参数名称 字段属性 是否必填 说明
    CIDR地址块1 String 是 输入CIDR地址块1。
    CIDR地址块2 String 是 输入CIDR地址块2。
    default 任意 否 设置default的值（可为空），无法判断两个CIDR地址块是否重叠时，返回该值。
  • 返回结果
    • 如果两个CIDR地址块不重叠，则返回0。
    • 如果两个CIDR地址块重叠在结束位置，则返回1。
    • 如果两个CIDR地址块重叠在开始位置，则返回-1。
  • 函数示例
    • 示例1：不存在重叠
      • 原始日志 
        cidr1: 192.168.0.0/23
cidr2: 192.168.2.0/24
      • 加工规则 
        e_set("overlaps",ip_overlaps(v("cidr1"),v("cidr2")))
      • 加工结果 
        idr1: 192.168.0.0/23
cidr2: 192.168.2.0/24
overlaps: 0
    • 示例2：在开始位置重叠
      • 原始日志 
        cidr1: 192.168.1.0/24
cidr2: 192.168.0.0/23
      • 加工规则 
        e_set("overlaps",ip_overlaps(v("cidr1"),v("cidr2")))
      • 加工结果 
        cidr1: 192.168.1.0/24
cidr2: 192.168.0.0/23
overlaps: -1
    • 示例3：在结束位置重叠
      • 原始日志 
        cidr1: 192.168.0.0/23
cidr2: 192.168.1.0/24
      • 加工规则 
        e_set("overlaps",ip_overlaps(v("cidr1"),v("cidr2")))
      • 加工结果 
        cidr1: 192.168.0.0/23
cidr2: 192.168.1.0/24
overlaps: 1