IP解析函數的文法規則 - Simple Log Service

本文介紹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
否
表示將不合法的長整型資料轉成Null 字元串，支援自訂。
返回結果
返回有效長整型轉換成功後的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

函數格式

參數說明

返回結果

函數樣本