Sintaxe de consulta

Para pesquisar recursos, filtre os resultados da pesquisa especificando um FIELD, um operador e um QUERY.

Correspondência exata do texto: operador igual (=)

FIELD=QUERY

Um exemplo de consulta é: policy=[e-mail].

O operador equals (=) verifica se QUERY corresponde exatamente ao valor dos metadados do recurso FIELD. Ela diferencia maiúsculas de minúsculas. Para um campo repetido, se QUERY corresponder a um dos valores do campo, o recurso será considerado uma correspondência. Os nomes de FIELD compatíveis dependem de a consulta ser uma pesquisa de recursos ou uma pesquisa de política do Identity and Access Management (IAM). O QUERY é uma frase, mas não pode ter caracteres curinga.

Correspondência parcial de texto: operador de dois-pontos (:)

FIELD:QUERY

Um exemplo de consulta é: policy:amy.2020@gmail.

Ao realizar uma pesquisa, o QUERY é comparado ao valor dos metadados de recursos especificados FIELD. Os campos de metadados da consulta e do recurso são convertidos em uma sequência de palavras (ou seja, tokens) para comparação. Isso é feito ao:

• Remover caracteres especiais iniciais/finais e tokenizar o valor da pesquisa tratando os caracteres especiais como delimitadores. Os caracteres especiais de tokenização são aqueles que não são alfanuméricos [a-zA-Z0-9], sublinhado [_] ou e comercial [&].

• realizar a dobragem Unicode para que a diferença de letra maiúscula e minúscula seja ignorada.

Veja alguns exemplos de tokenização:

• "[e-mail]" está tokenizado para: [amy,2020,gmail,com]

• "google.com/cloud" está tokenizado para: [google,com,cloud]

• "Compute %Instance%" está tokenizado para: [compute,instance]

• "$%^*-!" está tokenizado para: []

• "" está tokenizado para: []

• "compute*storage" está tokenizado para: [compute,storage]

• "compute&storage" está tokenizado para: [compute&storage]

• "[e-mail]" está tokenizado para: [bob_test,gmail,com]

• "instance/_my_vm_" está tokenizado para: [instance,_my_vm_]

O operador has (:) verifica se cada palavra de QUERY existe no valor do campo de metadados do recurso. Ele também verifica a ordem das palavras e a consecutividade. O FIELD compatível pode ser diferente, dependendo se é uma pesquisa de recursos ou uma pesquisa de política do IAM. O QUERY pode ser uma frase ou uma combinação de frases.

Observação: uma consulta pode conter várias comparações usando o formato acima. Consulte Combinação para mais informações. Eles são limitados a 10 comparações e 2.048 caracteres. Se você tiver um caso de uso para consultas mais longas, entre em contato conosco pelo e-mail [e-mail].

Examples

Por exemplo, um recurso cujo campo policy tem o valor [e-mail] corresponde às seguintes consultas:

• Corresponde porque a frase é exatamente igual ao valor do campo.

policy=[e-mail]

• Porque os caracteres de pontuação são tratados como delimitadores, e a consulta não diferencia maiúsculas de minúsculas.

policy:[e-mail]

• Corresponde porque as palavras em uma frase são correspondidas em ordem. Observe que "amy 2020 gmail" é uma frase. As palavras precisam ser correspondidas em ordem e consecutivas.

policy:"amy 2020 gmail"

• Corresponde porque uma combinação de palavras pode aparecer em qualquer ordem. Observe que (gmail 2020 amy) é uma combinação; correspondência de palavras e não necessariamente em ordem.

policy:(gmail 2020 amy)

• Corresponde porque as palavras na frase são correspondidas em ordem, e as palavras na combinação aparecem em qualquer ordem. Observe que "amy 2020" é uma frase, e as palavras precisam ser correspondidas em ordem e consecutivamente. (gmail "amy 2020") é combinação; gmail e "amy 2020" são correspondidos e não necessariamente em ordem.

policy:(gmail "amy 2020")

• Corresponde porque * pode ser usado em uma frase para indicar uma correspondência de prefixo.

policy:amy-20*

Um recurso cujo campo policy tem valor "[e-mail]" NÃO corresponde às seguintes consultas:

• Não corresponde, porque a frase diferencia maiúsculas de minúsculas. Use o operador has (:) em vez da correspondência que não diferencia maiúsculas de minúsculas.

policy=[e-mail]

• Não corresponde, porque a frase corresponde parcialmente ao valor do campo. Em vez disso, use o operador has (:) para fazer uma correspondência parcial.

policy=amy.2020@gmail

Correspondência numérica: operadores de comparação (=, >, >=, <, <=)

FIELD=QUERY

FIELD>QUERY

FIELD>=QUERY

FIELD<QUERY

FIELD<=QUERY

Os operadores de comparação verificam se o resultado da comparação entre QUERY e o valor dos metadados do recurso FIELD é verdadeiro.

Os nomes de FIELD compatíveis incluem createTime e updateTime.

Para campos de carimbo de data/hora (createTime e updateTime), o QUERY pode ser um número inteiro assinado de 64 bits, que representa o carimbo de data/hora da época em segundos, ou uma string de data e hora em um dos formatos abaixo (o fuso horário é UTC):

• AAAA-MM-DD: 2021-01-01 (as aspas são opcionais)

• "AAAA-MM-DDThh:mm:ss": "2021-01-01T00:00:00" (é necessário inserir aspas)

Examples

Por exemplo, um recurso cujo campo createTime tem o valor 1609459200 (carimbo de data/hora de época de 2021-01-01T00:00:00) corresponde às seguintes consultas:

Igual a

createTime=1609459200
createTime=2021-01-01
createTime="2021-01-01T00:00:00"

Maior que

createTime>1500000000
createTime>2020-01-01
createTime>"2020-01-01T00:00:00"

Maior ou igual a.

createTime>=1609459200
createTime>=2021-01-01
createTime>="2021-01-01T00:00:00"

Menor que

createTime<1700000000
createTime<2022-01-01
createTime<"2022-01-01T00:00:00"

Menor ou igual a.

createTime<=1609459200
createTime<=2021-01-01
createTime<="2021-01-01T00:00:00"

Frase

Uma frase é uma ou várias palavras entre aspas duplas ("). Com frases, a ordem das palavras é importante. As palavras na frase precisam ser correspondentes em ordem e consecutivas. Para fazer a correspondência de várias palavras sem respeitar a ordem, você precisa usar a combinação (por exemplo, field:(word1 word2 word3)).

Observação: se a frase contiver apenas caracteres em inglês [a-zA-Z], números [0-9], conectores de e-mail/URL básicos [_-+.@/&] e caracteres curinga [*], não será necessário colocá-la entre aspas duplas. Se uma frase entre aspas tiver " ou \, o escape será como \" ou \\. Também é possível substituir " ou \ por um único espaço, já que caracteres não alfanuméricos são tratados como delimitadores ao realizar a pesquisa.

As expressões a seguir são as mesmas:

policy:amy
policy:"amy"

policy:[e-mail]
policy:"[e-mail]"

name://cloudresourcemanager.googleapis.com/projects/projects/foo-bar
name:"//cloudresourcemanager.googleapis.com/projects/projects/foo-bar"

As seguintes frases precisam estar entre aspas:

name:"my instance"

policy:"[e-mail]"

description:"domain:gmail.com"

description:"hello \"world\""

description:"hello\\world"

Exemplos: frase

• Retorne recursos em que o campopolicy tenha as palavras amy e palavra 2020 em ordem e consecutivamente:

  policy:"amy 2020"
  

• Se você tiver um recurso com valor de campo policy igual a "[e-mail]", a consulta acima corresponderá.

• Se você tiver um recurso com valor de campo policy igual a "[e-mail]", a consulta acima não corresponderá, porque as palavras não são correspondidas em ordem.

• Se você tiver um recurso com valor de campo policy igual a "[e-mail]", a consulta acima não corresponderá, porque as palavras não são correspondidas de forma consecutiva.

Combinação

As frases de pesquisa podem ser combinadas usando AND ou OR. Os parênteses são usados para agrupar combinações.

Observação: os operadores AND e OR precisam estar em maiúsculas. Quando AND e OR são usados na consulta, é preciso usar parênteses para agrupar as combinações.

Exemplos: combinação

• Retorne recursos cujo campo policy tenha a palavra amy e a palavra john, sem respeitar a ordem. AND é opcional em uma combinação. Para corresponder várias palavras em ordem, você precisa usar a frase (por exemplo, field:"word1 word2 word3").

  owner:(amy john)
  

  Observação: se um recurso tiver um campo com uma lista de valores, por exemplo, policy=["[e-mail]", "[e-mail]", "[e-mail]"]. A pesquisa com policy:(amy john) corresponde ao recurso, porque [e-mail] contém a palavra amy e [e-mail] contém a palavra john. Ele não garante que esse campo precise ter um único elemento (por exemplo, [e-mail]) contendo as palavras amy e john.

• Retorne recursos em que o campo policy tem a palavra amy ou a palavra john.

  policy:(amy OR john)
  

• Retorne recursos em que o campo policy tem a palavra amy e a palavra john ou tem a palavra bob.

  policy:((amy john) OR bob)
  

  Observação: os parênteses precisam ser usados adequadamente para agrupar as combinações. Nas consultas acima, não é possível omitir os parênteses. A consulta a seguir é ilegal: policy:(amy john OR bob).

• Retorne recursos em que o campo policy tem a palavra amy e a palavra john ou name tem a palavra bob.

  policy:(amy john) OR name:bob
  

Negar filtros de pesquisa

Os filtros de pesquisa podem ser negados usando o operador NOT. Os parênteses são aceitos, mas não obrigatórios.

Observação: o operador NOT precisa estar em letra maiúscula. A negação só é aceita com a pesquisa de recursos.

Exemplos: negar filtros de pesquisa

• Retorna recursos em que o campo state não contém a palavra ACTIVE.

  NOT state:ACTIVE
  

• Retorna recursos em que o campo policy não tem a palavra amy nem a palavra john.

  NOT policy:(amy OR john)
  

• Retorna recursos em que o campo networkTags não contém a palavra internal ou private.

  NOT (networkTags:internal OR networkTags:private)
  

Curinga

O asterisco (*) pode ser usado em frases como caractere curinga. Conforme a posição, pode ter significados diferentes.

• Se estiver no final de uma frase, por exemplo, "am 20*", é um indicador de correspondência de prefixo de token. A consulta é equivalente a (am* 20*). Ele corresponde ao campo que contém um token que começa com "am", por exemplo, "ana", e um token que começa com "20", por exemplo, "2021". A ordem dos prefixos não importa.

• Se a frase inteira contiver apenas uma *, por exemplo, "labels.env:*", ela realizará uma verificação de existência. Ele verifica se a chave de rótulo "env" fornecida existe. Não há suporte para outros campos.

• Se estiver no meio de uma frase, por exemplo, "compute*storage", ele será tratado como um delimitador de tokenização. A consulta equivale a "armazenamento de computação".

• Se estiver no início e no fim de uma frase, por exemplo, "*compute storage*", ele será tratado como um delimitador de tokenização. A consulta é equivalente a "compute storage".

Exemplos: correspondência de prefixo de token

• Retorna recursos em que o campo policy contém uma palavra que começa com am:

  policy:am*
  

• Retorna recursos em que o campo policy tem duas palavras com "amy" e "20" como prefixos:

  policy:"amy 20*"
  
  policy:"20 amy*"
  

• Se você tiver um recurso com valor de campo policy igual a "[e-mail]", as consultas acima vão corresponder. Após a tokenização, "amy" e "20" passam a ser prefixos. Lembre-se de que a string de consulta "amy 20*" é diferente de "amy 20", que exige que 20 seja uma palavra inteira, e não um prefixo.

Exemplo: existência da chave do rótulo

Retorne recursos em que um dos labels tenha "env" como chave e tenha qualquer valor (incluindo valor vazio ou sem valor):

labels.env:*