本文介绍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判断两个网段是否存在重叠。
ip2long将字符串格式的IP地址转换成长整型数据。
long2ip将长整型数据转换成字符串格式的IP地址。

geo_parse

根据IP地址解析出所属国家、省份和市信息。
  • 函数格式

    geo_parse(ip, ip_db="SLS-GeoIP", keep_fields=None, provider="ipip", ip_sep=None)
  • 参数说明

    参数名称参数类型是否必填说明
    ipStringIP地址,表示解析该IP地址所属国家、省分和市信息。如果包含多个IP地址,可通过ip_sep参数指定分割符。
    ip_dbString解析IP地址所属国家、省份和市信息所使用的IP地址库。
    • SLS-GeoIP:SLS内置IP库,取值为SLS-GeoIP,默认使用该选项。为保证精确度,SLS内置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
    keep_fieldsTuple返回结果中包含的key信息。
    • 当通过SLS内置IP库解析时,默认返回信息如下:
      • city:城市名称。
      • province:省份名称。
      • country:国家名称。
      • city_en:城市的行政区划代码或者英文名称。
      • province_en:省份的行政区划代码或者英文名称。
      • country_en:国家或地区的代码或者英文名称。
      • isp:所属网络运营商名称。
      • lat:IP地址所在位置的纬度。
      • lon:IP地址所在位置的经度。
    • 当通过自选IP库解析时,默认返回信息如下:
      • city:城市名称。
      • province:省份名称。
      • country:国家名称。

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

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

    providerString仅当ip_db取值为自选IP库时,该参数有效。取值如下:
    • ipip:默认值。使用ipdb库提供的二进制IP地址库,下载地址为ipip
    • ip2location:使用全球IP二进制解析库,下载地址为ip2location。仅支持二进制包。
    ip_sepStringIP地址分隔符,用于将包含多个IP地址的字符串分割为多个IP地址,解析结果通过JSON格式返回。默认值为None,表示不进行分隔。
  • 返回结果

    返回字典形式数据,包含如下内容:
    {
      "city": "...",
      "province":"...",
      "country": "..."
    }
  • 函数示例

    • 示例1:使用SLS内置IP库查询。
      • 原始日志
        ip : 203.0.113.1
      • 加工规则
        e_set("geo", geo_parse(v("ip")))
      • 加工结果
        ip : 203.0.113.1
        geo: {"city":"杭州","province":"浙江省","country":"中国","isp":"移动","lat":30.16,"lon":120.12}
    • 示例2:使用SLS内置IP库查询,解析包含多个IP地址的日志字段,并返回每个IP地址所属的国家、省份和市信息。
      • 原始日志
        ip : 203.0.113.4, 192.0.2.2, 198.51.100.2
      • 加工规则
        e_set("geo", geo_parse(v("ip"), ip_sep=","))
      • 加工结果
        ip : 203.0.113.4, 192.0.2.2, 198.51.100.2
        geo : {"203.0.113.4": {"country_en": "CN", "province_en": "330000", "city_en": "330200", "country": "中国", "province": "浙江省", "city": "宁波市", "isp": "电信", "lat": 29.8782, "lon": 121.549}, "192.0.2.2": {"country_en": "CN", "province_en": "320000", "city_en": "321300", "country": "中国", "province": "江苏省", "city": "宿迁市", "isp": "电信", "lat": 33.9492, "lon": 118.296}, "198.51.100.2": {"country_en": "CN", "province_en": "330000", "city_en": "330500", "country": "中国", "province": "浙江省", "city": "湖州市", "isp": "电信", "lat": 30.8703, "lon": 120.093}}
    • 示例3:使用自选IP库查询。
      • 原始日志
        ip : 203.0.113.1
      • 加工规则
        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 : 203.0.113.1
        geo : {"city": "杭州", "province":"浙江省","country": "中国"}
    • 示例4: 使用自选IP库查询,选择输出关键key字段信息并且重命名key字段名称。
      • 原始日志
        ip : 203.0.113.1
      • 加工规则
        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 : 203.0.113.1
        geo : { "state": "中国","pro": "浙江省","cty": "杭州"}
    • 示例5:使用自选IP库查询,选择输出关键key字段信息。
      • 原始日志
        ip : 203.0.113.1
      • 加工规则
        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 : 203.0.113.1
        geo : { "country": "中国","province": "浙江省"}
    • 示例6:使用自选IP库查询,使用ip2location全球IP解析库输出关键key字段信息 。
      • 原始日志
        ip : 203.0.113.2
      • 加工规则
        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_secret", bucket='log-etl-staging', file='your ip2location bin file', format='binary', change_detect_interval=20),provider="ip2location"))
      • 加工结果
        ip : 203.0.113.2
        geo : {"city":"Dearborn","province":"Michigan","country":"United States"}
      数据加工使用的是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                               
      更多信息,请参见ip2location Python SDK
    • 示例7:使用自选IP库查询,解析包含多个IP地址的日志字段,并返回每个IP地址所属的国家省市信息。
      • 原始日志
        ip : 203.0.113.3, 192.0.2.1, 198.51.100.1
      • 加工规则
        e_set("geo", geo_parse(v("ip"), ip_db=res_oss_file(endpoint='http://oss-cn-hangzhou.aliyuncs.com',
                                                                       ak_id="ak_id",
                                                                       ak_key="ak_secret",
                                                                       bucket='log-etl-staging',
                                                                       file='calendar.csv/IP2LOCATION-LITE-DB3.BIN',
                                                                       format='binary', change_detect_interval=20),
                                        provider="ip2location", ip_sep=","))
      • 加工结果
        ip : 203.0.113.3, 192.0.2.1, 198.51.100.1
        geo : {"203.0.113.3": {"city": "Dearborn", "province": "Michigan", "country": "United States"}, "192.0.2.1": {"city": "Hangzhou", "province": "Zhejiang", "country": "China"}, "198.51.100.1": {"city": "Hangzhou", "province": "Zhejiang", "country": "China"}}

ip_cidrmatch

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

  • 函数格式

    ip_cidrmatch(cidr_subnet, ip, default="")
  • 参数说明

    参数名称参数类型是否必填说明
    cidr_subnetString输入CIDR地址块,例如:192.168.1.0/24。
    ipString输入IP地址。
    defaultString设置default值(可为空),如果IP地址与CIDR地址块无法匹配时,返回该值。
  • 返回结果

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

  • 函数示例

    • 示例1:IP地址(IPv4)与CIDR地址块匹配,返回true。
      • 原始日志
        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地址块不匹配,返回false。
      • 原始日志
        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地址块无法匹配,返回unknown。
      • 原始日志
        cidr_subnet: 192.168.1.0/24
        ip: a
      • 加工规则
        e_set("is_belong",ip_cidrmatch(v("cidr_subnet"),v("ip"),default="unknown"))
      • 加工结果
        cidr_subnet: 192.168.1.0/24
        ip: a
        is_belong: unknown

ip_version

判断IP地址为IPv4还是IPv6。若是IPv4类型IP地址,则返回IPv4,若是IPv6类型IP地址,则返回IPv6。

  • 函数格式

    ip_version(ip, default="")
  • 参数说明

    参数名称参数类型是否必填说明
    ipString输入IP地址。
    defaultString设置default值(可为空),无法判断IP地址版本时,返回该值。
  • 返回结果

    返回IPv4或者IPv6。

  • 函数示例

    • 示例1:判断IPv4地址的版本,返回IPv4。
      • 原始日志
        ip: 192.168.1.100
      • 加工规则
        e_set("version",ip_version(v("ip")))
      • 加工结果
        ip: 192.168.1.100
        version: IPv4
    • 示例2:判断IPv6地址的版本,返回IPv6。
      • 原始日志
        ip: ::1
      • 加工规则
        e_set("version",ip_version(v("ip")))
      • 加工结果
        ip: ::1
        version: IPv6

ip_type

判断IP地址是私有地址还是公有地址,返回IP类型包括private、reserved、loopback、public和allocated ripe ncc等。

  • 函数格式

    ip_type(ip, default="")
  • 参数说明

    参数名称参数类型是否必填说明
    ipString输入IP地址。
    defaultString设置default值(可为空),无法判断IP地址类型时,返回该值。
  • 返回结果

    返回IP类型包括private、reserved、loopback、public和allocated ripe ncc等。

  • 函数示例

    • 示例1: 判断IP地址,返回loopback。
      • 原始日志
        ip: 127.0.0.1
      • 加工规则
        e_set("type",ip_type(v("ip")))
      • 加工结果
        ip: 127.0.0.1
        type: loopback
    • 示例2: 判断IP地址,返回private。
      • 原始日志
        ip: 47.100.XX.XX
      • 加工规则
        e_set("type",ip_type(v("ip")))
      • 加工结果
        ip: 47.100.XX.XX
        type: private
    • 示例3: 判断IP地址,返回public。
      • 原始日志
        ip: 47.100.XX.XX
      • 加工规则
        e_set("type",ip_type(v("ip")))
      • 加工结果
        ip: 47.100.XX.XX
        type: public
    • 示例4: 判断IPv6地址,返回loopback。
      • 原始日志
        ip: ::1
      • 加工规则
        e_set("type",ip_type(v("ip")))
      • 加工结果
        ip: ::1
        type: loopback
    • 示例5:判断IPv6地址,返回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, subnet_mask=None, default="")
  • 参数说明

    参数名称参数类型是否必填说明
    ipString输入IP地址。
    subnet_maskString输入子网掩码,例如:255.255.255.0。
    说明 如果ip中输入的是IP网段,则子网掩码可以为空。
    defaultString设置default的值(可为空),无法将IP地址转成CIDR地址块时,返回该值。
  • 返回结果

    返回CIDR地址块。

  • 函数示例

    • 示例1: 将IP地址转换为CIDR地址块。
      • 原始日志
        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地址范围转换为CIDR地址块。
      • 原始日志
        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地址范围转换为CIDR地址块。
      • 原始日志
        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_subnet, want_prefix_len=0, default="")
  • 参数说明

    参数名称参数类型是否必填说明
    cidr_subnetString输入CIDR地址块,例如:192.168.1.0/24
    want_prefix_lenInt设置返回格式,默认为0。
    • 0:无格式返回。
    • 1:按照prefix格式返回。
    • 2:按照netmask格式返回。
    • 3:按照IP网段格式返回。
    defaultString设置default的值(可为空),无法将输入的CIDR地址块按照格式输出时,返回该值。
  • 返回结果

    返回特定格式的IP地址。

  • 函数示例

    • 示例1: 将输入的CIDR地址块直接输出。
      • 原始日志
        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: 将输入的CIDR地址块按照prefix格式输出。
      • 原始日志
         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: 将输入的CIDR地址块按照netmask格式输出。
      • 原始日志
        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: 将输入的CIDR地址块按照IP地址网段格式输出。
      • 原始日志
        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_subnet, cidr_subnet2, default="")
  • 参数说明

    参数名称参数类型是否必填说明
    cidr_subnetString输入CIDR地址块1。
    cidr_subnet2String输入CIDR地址块2。
    defaultString设置default的值(可为空),无法判断两个CIDR地址块是否重叠时,返回该值。
  • 返回结果

    • 如果两个CIDR地址块不重叠,则返回0。
    • 如果两个CIDR地址块重叠在结束位置,则返回1。
    • 如果两个CIDR地址块重叠在开始位置,则返回-1。
  • 函数示例

    • 示例1:两个CIDR地址块不重叠。
      • 原始日志
        cidr1: 192.168.0.0/23
        cidr2: 192.168.2.0/24
      • 加工规则
        e_set("overlaps",ip_overlaps(v("cidr1"),v("cidr2")))
      • 加工结果
        cidr1: 192.168.0.0/23
        cidr2: 192.168.2.0/24
        overlaps: 0
    • 示例2:两个CIDR地址块在开始位置重叠。
      • 原始日志
        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:两个CIDR地址块在结束位置重叠。
      • 原始日志
        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

ip2long

使用ip2long函数将字符串格式的IP地址转换成长整型数据。
  • 函数格式

    ip2long(value,default=0)
  • 参数说明

    参数名称参数类型是否必填说明
    valueString填入需要被转换的值。
    defaultString某个不合法的IP地址被转换成的值。支持自定义,例如:0。
  • 返回结果

    返回有效IP转换成功后的长整型数据。

  • 函数示例

    • 示例1:默认情况
      • 原始日志
        ip: 192.168.0.100
      • 加工规则
        e_set("long_ip",ip2long(v("ip")))
      • 加工结果
        ip: 192.168.0.100
        long_ip: 167772160
    • 示例2:非法IP情况
      • 原始日志
        ip: 47.100.XX.XX
      • 加工规则
        e_set("long_ip",ip2long(v("ip"), "ignore"))
      • 加工结果
        ip:47.100.XX.XX
        long_ip:ignore

long2ip

使用long2ip函数将长整型数据转换成字符串格式的IP地址。
  • 函数格式

    long2ip(value,default="")
  • 参数说明

    参数名称参数类型是否必填说明
    valueString填入需要被转换的值。
    defaultString表示将不合法的长整型数据转成空字符串,支持自定义。
  • 返回结果

    返回有效长整型转换成功后的IP地址。

  • 函数示例

    • 示例1:默认情况
      • 原始日志
        long: 167772160
      • 加工规则
        e_set("ip",long2ip(v("long")))
      • 加工结果
        long: 167772160
        ip: 192.168.0.100
    • 示例2:长整型转换IP地址失败情况
      • 原始日志
        long: 4294967296
      • 加工规则
        e_set("ip",long2ip(v("long")))
      • 加工结果
        long: 4294967296
        ip: 
    • 示例3:长整型转换IP地址失败时自定义的错误处理。
      • 原始日志
        long: 4294967296
      • 加工规则
        e_set("ip",long2ip(v("long"),default="xxx"))
      • 加工结果
        long: 4294967296
        ip: xxx