标准 SQL 中的网络函数

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

说明

将 IPv4 或 IPv6 地址从文本 (STRING) 格式转换为网络字节顺序的二进制 (BYTES) 格式。

此函数支持以下 addr_str 格式：

  • IPv4：点分四组格式。例如 10.1.2.3。
  • IPv6：冒号分隔格式。例如，1234:5678:90ab:cdef:1234:5678:90ab:cdef。如需查看更多示例，请参阅 IP 版本 6 寻址架构。

此函数不支持 CIDR 表示法，例如 10.1.2.3/32。

如果此函数收到一个 NULL 输入，则会返回 NULL。如果输入视为无效，则发生 OUT_OF_RANGE 错误。

返回数据类型

BYTES

示例

SELECT
  addr_str, FORMAT("%T", NET.IP_FROM_STRING(addr_str)) AS ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128'
]) AS addr_str;
addr_str ip_from_string
48.49.50.51 b"0123"
::1 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445 b"0123456789@ABCDE"
::ffff:192.0.2.128 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"

NET.SAFE_IP_FROM_STRING

NET.SAFE_IP_FROM_STRING(addr_str)

说明

类似于 NET.IP_FROM_STRING，但在输入无效的情况下会返回 NULL，而不是抛出错误。

返回数据类型

BYTES

示例

SELECT
  addr_str,
  FORMAT("%T", NET.SAFE_IP_FROM_STRING(addr_str)) AS safe_ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128',
  '48.49.50.51/32',
  '48.49.50',
  '::wxyz'
]) AS addr_str;
addr_str safe_ip_from_string
48.49.50.51 b"0123"
::1 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445 b"0123456789@ABCDE"
::ffff:192.0.2.128 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
48.49.50.51/32 NULL
48.49.50 NULL
::wxyz NULL

NET.IP_TO_STRING

NET.IP_TO_STRING(addr_bin)

说明 将 IPv4 或 IPv6 地址从文本 (STRING) 格式转换为网络字节顺序的二进制 (BYTES) 格式。

如果输入为 4 个字节，则此函数返回 STRING 形式的 IPv4 地址。如果输入为 16 个字节，则返回 STRING 形式的 IPv6 地址。

如果此函数收到一个 NULL 输入，则会返回 NULL。如果输入的长度并非 4 或 16，则发生 OUT_OF_RANGE 错误。

返回数据类型

STRING

示例

SELECT FORMAT("%T", x) AS addr_bin, NET.IP_TO_STRING(x) AS ip_to_string
FROM UNNEST([
  b"0123",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01",
  b"0123456789@ABCDE",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
]) AS x;
addr_bin ip_to_string
b"0123" 48.49.50.51
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01" ::1
b"0123456789@ABCDE" 3031:3233:3435:3637:3839:4041:4243:4445
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80" ::ffff:192.0.2.128

NET.IP_NET_MASK

NET.IP_NET_MASK(num_output_bytes, prefix_length)

说明

返回一个网路掩码：长度等于 num_output_bytes 的一个字节序列，其中第一个 prefix_length 位设置为 1，其他位设置为 0。num_output_bytes 和 prefix_length 为 INT64 类型。如果 num_output_bytes 不是 4（对于 IPv4）或 16（对于 IPv6），则此函数会引发错误。如果 prefix_length 为负或者大于 8 * num_output_bytes，此函数也会引发错误。

返回数据类型

BYTES

示例

SELECT x, y, FORMAT("%T", NET.IP_NET_MASK(x, y)) AS ip_net_mask
FROM UNNEST([
  STRUCT(4 as x, 0 as y),
  (4, 20),
  (4, 32),
  (16, 0),
  (16, 1),
  (16, 128)
]);
x y ip_net_mask
4 0 b"\x00\x00\x00\x00"
4 20 b"\xff\xff\xf0\x00"
4 32 b"\xff\xff\xff\xff"
16 0 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16 1 b"\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16 128 b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"

NET.IP_TRUNC

NET.IP_TRUNC(addr_bin, prefix_length)

说明 获取 addr_bin（以网络字节顺序排列的二进制 (BYTES) 格式的 IPv4 或 IPv6 地址），并返回相同格式的子网地址。结果具有与 addr_bin 相同的长度，其中第一个 prefix_length 位等于 addr_bin 中的位，其余位是 0。

如果 LENGTH(addr_bin) 不是 4 或 16，或者 prefix_len 为负或者大于 LENGTH(addr_bin) * 8，此函数会引发错误。

返回数据类型

BYTES

示例

SELECT
  FORMAT("%T", x) as addr_bin, prefix_length,
  FORMAT("%T", NET.IP_TRUNC(x, prefix_length)) AS ip_trunc
FROM UNNEST([
  STRUCT(b"\xAA\xBB\xCC\xDD" as x, 0 as prefix_length),
  (b"\xAA\xBB\xCC\xDD", 11), (b"\xAA\xBB\xCC\xDD", 12),
  (b"\xAA\xBB\xCC\xDD", 24), (b"\xAA\xBB\xCC\xDD", 32),
  (b'0123456789@ABCDE', 80)
]);
addr_bin prefix_length ip_trunc
b"\xaa\xbb\xcc\xdd" 0 b"\x00\x00\x00\x00"
b"\xaa\xbb\xcc\xdd" 11 b"\xaa\xa0\x00\x00"
b"\xaa\xbb\xcc\xdd" 12 b"\xaa\xb0\x00\x00"
b"\xaa\xbb\xcc\xdd" 24 b"\xaa\xbb\xcc\x00"
b"\xaa\xbb\xcc\xdd" 32 b"\xaa\xbb\xcc\xdd"
b"0123456789@ABCDE" 80 b"0123456789\x00\x00\x00\x00\x00\x00"

NET.IPV4_FROM_INT64

NET.IPV4_FROM_INT64(integer_value)

说明

将 IPv4 地址从整数格式转换为网络字节顺序的二进制 (BYTES) 格式。在整数输入中，无论主机或客户端采用何种架构，IP 地址的最低有效位都存储为整数最低有效位。例如，1 表示 0.0.0.1，0x1FF 表示 0.0.1.255。

此函数会检查是否所有最高有效 32 位均为 0，或者是否所有最高有效 33 位均为 1（从 32 位整数进行有符号扩展）。换句话说，输入应该在 [-0x80000000, 0xFFFFFFFF] 范围内；否则，此函数会引发错误。

此函数不支持 IPv6。

返回数据类型

BYTES

示例

SELECT x, x_hex, FORMAT("%T", NET.IPV4_FROM_INT64(x)) AS ipv4_from_int64
FROM (
  SELECT CAST(x_hex AS INT64) x, x_hex
  FROM UNNEST(["0x0", "0xABCDEF", "0xFFFFFFFF", "-0x1", "-0x2"]) AS x_hex
);
x x_hex ipv4_from_int64
0 0x0 b"\x00\x00\x00\x00"
11259375 0xABCDEF b"\x00\xab\xcd\xef"
4294967295 0xFFFFFFFF b"\xff\xff\xff\xff"
-1 -0x1 b"\xff\xff\xff\xff"
-2 -0x2 b"\xff\xff\xff\xfe"

NET.IPV4_TO_INT64

NET.IPV4_TO_INT64(addr_bin)

说明

将 IPv4 地址从网络字节顺序的二进制 (BYTES) 格式转换为整数格式。在整数输出中，无论主机或客户端采用何种架构，IP 地址的最低有效位都存储为整数最低有效位。例如，1 表示 0.0.0.1，0x1FF 表示 0.0.1.255。输出范围为 [0, 0xFFFFFFFF]。

如果输入长度不是 4，则此函数会引发错误。

此函数不支持 IPv6。

返回数据类型

INT64

示例

SELECT
  FORMAT("%T", x) AS addr_bin,
  FORMAT("0x%X", NET.IPV4_TO_INT64(x)) AS ipv4_to_int64
FROM
UNNEST([b"\x00\x00\x00\x00", b"\x00\xab\xcd\xef", b"\xff\xff\xff\xff"]) AS x;
addr_bin ipv4_to_int64
b"\x00\x00\x00\x00" 0x0
b"\x00\xab\xcd\xef" 0xABCDEF
b"\xff\xff\xff\xff" 0xFFFFFFFF

NET.HOST

NET.HOST(url)

说明

获取一个 STRING 格式的网址，并返回 STRING 格式的主机。为获得最佳结果，网址值应符合 RFC 3986 定义的格式。如果网址值不符合 RFC 3986 格式，此函数会尽最大努力解析输入并返回相关结果。如果函数无法解析输入，则返回 NULL。

注意：此函数不执行任何标准化。

返回数据类型

STRING

示例

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
输入 说明 主机 后缀 域名
"" 输入无效 NULL NULL NULL
"http://abc.xyz" 标准网址 "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 具有相对架构、端口、路径和查询的标准网址，但没有公开后缀 "a.b" NULL NULL
"https://[::1]:80" 采用 IPv6 主机的标准网址 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 采用国际化域名的标准网址 "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 带有空格、大写字母但没有架构的非标准网址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI 而非网址 - 不支持 "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

说明

获取一个 STRING 格式的网址，并返回 STRING 格式的公共后缀（例如 com、org 或 net）。公共后缀就是在 publicsuffix.org 注册的一个 ICANN 域名。为获得最佳结果，网址值应符合 RFC 3986 定义的格式。如果网址值不符合 RFC 3986 格式，此函数会尽最大努力解析输入并返回相关结果。

如果下述任一条件为 true，则此函数返回 NULL：

  • 它无法通过输入解析主机；
  • 解析得出的主机中间包含相邻点（而非前导或尾随位置）；
  • 解析得到的主机不包含任何公开后缀。

在查找公开后缀之前，此函数会临时标准化主机，方法是将大写英文字母转换为小写字母，并使用 Punycode 编码所有非 ASCII 字符。随后，此函数将公开后缀作为原始主机（而非标准化主机）的一部分返回。

注意：此函数不执行 Unicode 标准化。

注意：publicsuffix.org 的公共后缀数据还包含不公开域名。此函数会忽略不公开域名。

注意：公开后缀数据可能会随着时间的推移而变化。因此，现在生成 NULL 结果的输入可能会在将来生成非 NULL 值。

返回数据类型

STRING

示例

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
输入 说明 主机 后缀 域名
"" 输入无效 NULL NULL NULL
"http://abc.xyz" 标准网址 "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 具有相对架构、端口、路径和查询的标准网址，但没有公开后缀 "a.b" NULL NULL
"https://[::1]:80" 采用 IPv6 主机的标准网址 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 采用国际化域名的标准网址 "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 带有空格、大写字母但没有架构的非标准网址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK
"mailto:?to=&subject=&body=" URI 而非网址 - 不支持 "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

说明

获取一个 STRING 格式的网址，并返回 STRING 格式的已注册或可注册域名（公共后缀加一个前置标签）。为获得最佳结果，网址值应符合 RFC 3986 定义的格式。如果网址值不符合 RFC 3986 格式，此函数会尽最大努力解析输入并返回相关结果。

如果下述任一条件为 true，则此函数返回 NULL：

  • 它无法通过输入解析主机；
  • 解析得出的主机中间包含相邻点（而非前导或尾随位置）；
  • 解析得到的主机不包含任何公开后缀；
  • 解析得出的主机只包含公开后缀，而无任何前置标签。

在查找公开后缀之前，此函数会临时标准化主机，方法是将大写英文字母转换为小写字母，并使用 Punycode 编码所有非 ASCII 字符。随后，此函数将已注册或可注册域名作为原始主机（而非标准化主机）的一部分返回。

注意：此函数不执行 Unicode 标准化。

注意：publicsuffix.org 的公共后缀数据还包含不公开域名。此函数不会将不公开域名视为公开后缀。例如，如果“us.com”是公开后缀数据中的一个不公开域名，NET.REG_DOMAIN("foo.us.com") 会返回“us.com”（公开后缀“com”加上前置标签“us”）而非“foo.us.com”（不公开域名“us.com”加上前置标签“foo”）。

注意：公开后缀数据可能会随着时间的推移而变化。因此，现在生成 NULL 结果的输入可能会在将来生成非 NULL 值。

返回数据类型

STRING

示例

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
输入 说明 主机 后缀 域名
"" 输入无效 NULL NULL NULL
"http://abc.xyz" 标准网址 "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 具有相对架构、端口、路径和查询的标准网址，但没有公开后缀 "a.b" NULL NULL
"https://[::1]:80" 采用 IPv6 主机的标准网址 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 采用国际化域名的标准网址 "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 带有空格、大写字母但没有架构的非标准网址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI 而非网址 - 不支持 "mailto" NULL NULL
此页内容是否有用？请给出您的反馈和评价：

发送以下问题的反馈：

此网页
文档反馈
BigQuery
产品反馈
需要帮助？请访问我们的支持页面。