標準 SQL 中的 Net 函式

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 位址從網路位元組順序的二進位 (BYTES) 格式轉換為文字 (STRING) 格式。

如果輸入是 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_bytesprefix_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.10x1FF 表示 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.10x1FF 表示 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://例子.卷筒纸.中国" 含國際化網域名稱的標準網址 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    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 格式的公開尾碼 (例如 comorgnet)。公開尾碼是在 publicsuffix.org 註冊的 ICANN 網域。若要獲得最佳效果,網址值應符合 RFC 3986 定義的格式。如果網址值不符合 RFC 3986 格式,這個函式會盡可能剖析輸入並傳回相關結果。

如果出現以下任何一個情況,這個函式就會傳回 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://例子.卷筒纸.中国" 含國際化網域名稱的標準網址 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    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 格式,這個函式會盡可能剖析輸入並傳回相關結果。

如果出現以下任何一個情況,這個函式就會傳回 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://例子.卷筒纸.中国" 含國際化網域名稱的標準網址 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 含空格、大寫字母,不含通訊協定的非標準網址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" 網址以外的 URI--不支援 "mailto" NULL 空值
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
需要協助嗎?請前往我們的支援網頁