IP解析函数的语法规则_日志服务(SLS)-阿里云帮助中心

本文介绍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)

参数说明

参数名称	参数类型	是否必填	说明
ip	String	是	IP地址，表示解析该IP地址所属国家、省分和市信息。如果包含多个IP地址，可通过ip_sep参数指定分割符。
ip_db	String	是	解析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_fields	Tuple	否	返回结果中包含的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")`表示仅输出`city`和`country`字段信息。此外`keep_fields`也支持重命名。例如`(("city","cty"),("country","state"))`表示以`cty`和`state`形式输出。
provider	String	否	仅当ip_db取值为自选IP库时，该参数有效。取值如下： ipip：默认值。使用ipdb库提供的二进制IP地址库，下载地址为ipip。 ip2location：使用全球IP二进制解析库，下载地址为ip2location。仅支持二进制包。
ip_sep	String	否	IP地址分隔符，用于将包含多个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_subnet	String	是	输入CIDR地址块，例如：192.168.1.0/24。
ip	String	是	输入IP地址。
default	String	否	设置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="")
```
参数说明
参数名称
参数类型
是否必填
说明
ip
String
是
输入IP地址。
default
String
否
设置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="")
```
参数说明
参数名称
参数类型
是否必填
说明
ip
String
是
输入IP地址。
default
String
否
设置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="")

参数说明

参数名称	参数类型	是否必填	说明
ip	String	是	输入IP地址。
subnet_mask	String	是	输入子网掩码，例如：255.255.255.0。说明如果ip中输入的是IP网段，则子网掩码可以为空。
default	String	否	设置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_subnet	String	是	输入CIDR地址块，例如：192.168.1.0/24
want_prefix_len	Int	否	设置返回格式，默认为0。 0：无格式返回。 1：按照prefix格式返回。 2：按照netmask格式返回。 3：按照IP网段格式返回。
default	String	否	设置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_subnet	String	是	输入CIDR地址块1。
cidr_subnet2	String	是	输入CIDR地址块2。
default	String	否	设置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)
```
参数说明
参数名称
参数类型
是否必填
说明
value
String
是
填入需要被转换的值。
default
String
否
某个不合法的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="")
```
参数说明
参数名称
参数类型
是否必填
说明
value
String
是
填入需要被转换的值。
default
String
否
表示将不合法的长整型数据转成空字符串，支持自定义。
返回结果
返回有效长整型转换成功后的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
```

函数列表

geo_parse

函数格式

参数说明

返回结果

函数示例

ip_cidrmatch

函数格式

参数说明

返回结果

函数示例

ip_version

函数格式

参数说明

返回结果

函数示例

ip_type

函数格式

参数说明

返回结果

函数示例

ip_makenet

函数格式

参数说明

返回结果

函数示例

ip_to_format

函数格式

参数说明

返回结果

函数示例

ip_overlaps

函数格式

参数说明

返回结果

函数示例

ip2long

函数格式

参数说明

返回结果

函数示例

long2ip

函数格式

参数说明

返回结果

函数示例