Sintaxe da consulta

Para pesquisar recursos, é possível filtrar os resultados da pesquisa especificando um FIELD, um operador e um QUERY.

Correspondência exata de texto: operador "igual a" (=)

FIELD=QUERY

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

O operador equals (=) verifica se QUERY corresponde exatamente ao valor dos metadados do recurso FIELD. Ele 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 FIELD compatíveis dependem de a consulta ser uma pesquisa de recursos ou uma pesquisa de política de gerenciamento de identidade e acesso (IAM, na sigla em inglês). O QUERY é uma frase, mas não pode conter caracteres curinga.

Correspondência parcial de texto: operador "tem" (:)

FIELD:QUERY

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

Ao executar uma pesquisa, QUERY é comparado ao valor dos metadados de recursos especificados FIELD. Os campos de consulta e de metadados 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 os caracteres que não são de [a-zA-Z0-9], sublinhados [_] 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 há cada palavra QUERY dentro do 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 do Google 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 em [e-mail].

Exemplos

Por exemplo, um recurso com o campo owner que tem valor "[e-mail]" corresponde às seguintes consultas:

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

    owner=[e-mail]
  

• Corresponde porque as pontuações são tratadas como delimitadores e a capitalização não é sensível.

    owner:[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.

    owner:"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.

    owner:(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.

    owner:(gmail "amy 2020")
  

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

    owner:amy-20*
  

Um recurso cujoowner O campo tem valor"[e-mail]" N matchO 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.

    owner=[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.

    owner=amy.2020@gmail
  

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

FIELD=QUERY

FIELD>QUERY

FIELD>=QUERY

FIELD<QUERY

FIELD<=QUERY

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

Os nomes aceitos para FIELD incluem createTime e updateTime.

Para campos de carimbo de data/hora (createTime e updateTime), 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)

Exemplos

Por exemplo, um recurso em que o campo createTime tem o valor 1609459200 (carimbo de data/hora da é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 reordenação, 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 é necessário colocá-la entre aspas duplas. Se uma frase entre aspas contém " ou \", é preciso inserir caracteres de escape como \ ou \. Também é possível substituir " ou \" como um espaço único, já que os caracteres não alfanuméricos são tratados como delimitadores ao executar a pesquisa.

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

owner:amy
owner:"amy"

owner:[e-mail]
owner:"[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"

owner:"[e-mail]"

description:"domain:gmail.com"

description:"hello \"world\""

description:"hello\\world"

Exemplos: frase

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

  owner:"amy 2020"
  

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

• Se você tiver um recurso com valor de campo owner 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 owner 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 em que o campo owner tem a palavra amy e a palavra john, sem especificar a ordem. AND é opcional em uma combinação. Para corresponder a várias palavras em ordem, é preciso 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, owner=["[e-mail]", "[e-mail]", "[e-mail]"]. A pesquisa com owner:(amy john) corresponde ao recurso, porque [e-mail] contém a palavra amy e [e-mail] contém a palavra john. Isso não garante que esse campo precisa ter um único elemento (por exemplo, [e-mail]) contendo as palavras amy e palavra john.

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

  owner:(amy OR john)
  

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

  owner:((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: owner:(amy john OR bob).

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

  owner:(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 owner não tem a palavra amy nem a palavra john.

  NOT owner:(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, como "am 20*", é um indicador de correspondência de prefixo de token. A consulta é equivalente a (am* 20*). Ele corresponde ao campo contendo um token que começa com "am", como "amy", e um token que começa com "20", como "2021". A ordem dos prefixos não importa.

• Se a frase inteira contiver apenas um *, como "labels.env:*", ele realiza uma verificação de existência. Ele verifica se a chave de rótulo "env" fornecida existe. Os demais campos não são compatíveis.

• Se estiver no meio de uma frase, como "compute*storage", ele é tratado como um delimitador de tokenização. A consulta é equivalente a "compute storage".

• Se estiver no começo e no fim de uma frase, como "*compute storage*", ele é 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 owner contém uma palavra que começa com am:

  owner:am*
  

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

  owner:"amy 20*"
  
  owner:"20 amy*"
  

• Se você tiver um recurso com valor de campo owner 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.

Exemplos: existência da chave de rótulo

• Retorne recursos em que um dos objetos labels tem "env" como chave e tem qualquer valor (incluindo valor vazio ou nenhum valor):

  labels.env:*