Funções de rede no SQL padrão

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

Descrição

Converte um endereço IPv4 ou IPv6 do formato de texto (STRING) para o formato binário (BYTES) na ordem de bytes da rede.

Essa função é compatível com os seguintes formatos de addr_str:

  • IPv4: formato "dotted-quad" (quádruplo com ponto). Por exemplo: 10.1.2.3.
  • IPv6: formato separado por dois-pontos. Por exemplo: 1234:5678:90ab:cdef:1234:5678:90ab:cdef. Para mais exemplos, consulte Arquitetura de endereçamento IP versão 6 (em inglês).

Essa função não é compatível com a notação CIDR (em inglês), como 10.1.2.3/32.

Se ela receber uma entrada NULL, retornará NULL. Se a entrada for considerada inválida, ocorrerá um erro OUT_OF_RANGE.

Tipo de dados retornados

BYTES

Exemplo

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)

Descrição

Semelhante a NET.IP_FROM_STRING, mas retorna NULL em vez de gerar um erro caso a entrada seja inválida.

Tipo de dados retornados

BYTES

Exemplo

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)

Descrição Converte um endereço IPv4 ou IPv6 do formato binário (BYTES) na ordem de bytes da rede para o formato de texto (STRING).

Se a entrada for de 4 bytes, essa função retornará um endereço IPv4 como uma STRING. Se a entrada for de 16 bytes, ela retornará um endereço IPv6 como uma STRING.

Se receber uma entrada NULL, essa função retornará NULL. Se a entrada tiver um comprimento diferente de 4 ou 16, ocorrerá um erro OUT_OF_RANGE.

Tipo de dados retornados

STRING

Exemplo

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)

Descrição

Retorna uma máscara de rede, isto é, uma sequência de bytes com comprimento igual a num_output_bytes, no qual os primeiros bits prefix_length são definidos para 1. Os outros bits são definidos para 0. num_output_bytes e prefix_length são INT64. Essa função gera um erro, se num_output_bytes não for 4 (para IPv4) ou 16 (para IPv6). Ela também gera um erro, se prefix_length for negativo ou maior que 8 * num_output_bytes.

Tipo de dados retornados

BYTES

Exemplo

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)

Descrição Utiliza addr_bin, um endereço IPv4 ou IPv6 em formato binário (BYTES) na ordem de bytes da rede e retorna um endereço de sub-rede no mesmo formato. O resultado tem o mesmo comprimento de addr_bin, no qual os primeiros bits prefix_length são iguais aos de addr_bin e os bits restantes são 0.

Essa função gera um erro, se LENGTH(addr_bin) não for 4 ou 16, ou se prefix_len for negativo ou maior que LENGTH(addr_bin) * 8.

Tipo de dados retornados

BYTES

Exemplo

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)

Descrição

Converte um endereço IPv4 do formato inteiro para binário (BYTES) na ordem de bytes da rede. Na entrada do inteiro, o bit menos significativo do endereço IP é armazenado no bit menos significativo do inteiro, independentemente da arquitetura do host ou do cliente. Por exemplo, 1 significa 0.0.0.1, e 0x1FF significa 0.0.1.255.

Essa função verifica se todos os 32 bits mais significativos são 0, ou se todos os 33 bits mais significativos são 1 (estendido por sinal de um inteiro de 32 bits). Em outras palavras, a entrada precisa estar no intervalo [-0x80000000, 0xFFFFFFFF]. Caso contrário, a função gera um erro.

Essa função não aceita IPv6.

Tipo de dados retornados

BYTES

Exemplo

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)

Descrição

Converte um endereço IPv4 do formato binário (BYTES) na ordem de bytes da rede para inteiro. Na saída do inteiro, o bit menos significativo do endereço IP é armazenado no bit menos significativo do inteiro, independentemente da arquitetura do host ou do cliente. Por exemplo, 1 significa 0.0.0.1, e 0x1FF significa 0.0.1.255. A saída está no intervalo [0, 0xFFFFFFFF].

Se o comprimento da entrada não for 4, a função gerará um erro.

Essa função não aceita IPv6.

Tipo de dados retornados

INT64

Exemplo

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)

Descrição

Toma um URL como STRING e retorna o host com STRING. Para ter os melhores resultados, os valores do URL precisam estar de acordo com o formato definido por RFC 3986. Se não estiverem em conformidade com a formatação RFC 3986, a função analisará a entrada da melhor maneira possível e retornará um resultado relevante. Se não for possível analisar a entrada, será retornado NULL.

Nota: a função não realiza a normalização.

Tipo de dados retornados

STRING

Exemplo

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"
);
entrada descrição host sufixo domínio
"" entrada inválida NULL NULL NULL
"http://abc.xyz" URL padrão "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL padrão com esquema, porta, caminho e consulta relativos, mas sem sufixo público "a.b" NULL NULL
"https://[::1]:80" URL padrão com host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL padrão com nome de domínio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL não padrão com espaços, letras maiúsculas e sem esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI, e não URL, não compatível "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Descrição

Utiliza um URL como STRING e retorna o sufixo público (como com, org ou net) como STRING. Um sufixo público é um domínio ICANN registrado em publicuffix.org (em inglês). Para os melhores resultados, os valores de URL precisam obedecer ao formato conforme definido pelo RFC 3986. Se não estiverem em conformidade com a formatação RFC 3986, a função analisará a entrada da melhor maneira possível e retornará um resultado relevante.

A função retornará NULL, se qualquer uma das seguintes situações for verdadeira:

  • Não é possível analisar o host com a entrada.
  • O host analisado contém pontos adjacentes no meio (não à esquerda ou direita).
  • O host analisado não contém um sufixo público.

Antes de pesquisar o sufixo público, essa função normalizará temporariamente o host convertendo letras em inglês em maiúsculas para minúsculas e codificando todos os caracteres não ASCII com Punycode. Depois, ela retornará o sufixo público como parte do host original em vez do host normalizado:

Observação: a função não realiza a normalização Unicode (em inglês).

Observação: os dados do sufixo público em publicuffix.org (em inglês) também contêm domínios particulares. Essa função ignora os domínios privados.

Observação: os dados do sufixo público podem mudar ao longo do tempo. Por conseguinte, a entrada que produz um resultado NULL no momento pode produzir um valor não NULL no futuro.

Tipo de dados retornados

STRING

Exemplo

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"
);
entrada descrição host sufixo domínio
"" entrada inválida NULL NULL NULL
"http://abc.xyz" URL padrão "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL padrão com esquema, porta, caminho e consulta relativos, mas sem sufixo público "a.b" NULL NULL
"https://[::1]:80" URL padrão com host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL padrão com nome de domínio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL não padrão com espaços, letras maiúsculas e sem esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK
"mailto:?to=&subject=&body=" URI, e não URL, não compatível "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Descrição

Utiliza um URL como STRING e retorna o domínio registrado ou registrável (o sufixo público mais um rótulo precedente), como STRING. Para melhores resultados, os valores de URL precisam obedecer ao formato definido pela norma RFC 3986 (em inglês). Se não estiverem em conformidade com a formatação RFC 3986, a função analisará a entrada da melhor maneira possível e retornará um resultado relevante.

A função retornará NULL, se qualquer uma das seguintes situações for verdadeira:

  • Não é possível analisar o host com a entrada.
  • O host analisado contém pontos adjacentes no meio (não à esquerda ou direita).
  • O host analisado não contém um sufixo público.
  • O host analisado contém somente um sufixo público sem rótulo precedente.

Antes de pesquisar o sufixo público, essa função normalizará temporariamente o host convertendo letras em inglês em maiúsculas para minúsculas e codificando todos os caracteres não ASCII com Punycode. Depois, ela retornará o domínio registrado ou registrável como parte do host original em vez do host normalizado.

Observação: a função não realiza a normalização Unicode (em inglês).

Observação: os dados do sufixo público em publicuffix.org (em inglês) também contêm domínios particulares. Essa função não trata um domínio privado como um sufixo público. Por exemplo, se "us.com" for um domínio privado nos dados de sufixo público, NET.REG_DOMAIN ("foo.us.com") retornará "us.com" (o sufixo público "com" mais o rótulo anterior "us ") em vez de "foo.us.com" (o domínio privado "us.com" mais o rótulo anterior "foo").

Observação: os dados do sufixo público podem mudar ao longo do tempo. Por conseguinte, a entrada que produz um resultado NULL no momento pode produzir um valor não NULL no futuro.

Tipo de dados retornados

STRING

Exemplo

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"
);
entrada descrição host sufixo domínio
"" entrada inválida NULL NULL NULL
"http://abc.xyz" URL padrão "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL padrão com esquema, porta, caminho e consulta relativos, mas sem sufixo público "a.b" NULL NULL
"https://[::1]:80" URL padrão com host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL padrão com nome de domínio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL não padrão com espaços, letras maiúsculas e sem esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI, e não URL, não compatível "mailto" NULL NULL
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.