Esta página foi traduzida pela API Cloud Translation.

Sintaxe de consulta de pesquisa

Ao pesquisar recursos, é possível filtrar os resultados especificando uma consulta composta por um campo de metadados de recursos, um operador e um valor.

Campos e recursos pesquisáveis

Para saber quais campos podem ser usados em uma consulta searchAllResources, consulte Campos ResourceSearchResult.

Para ver os campos que podem ser usados em uma consulta searchAllIamPolicies, consulte Campos de IamPolicySearchResult.

Para ver os recursos que podem ser pesquisados, consulte Tipos de recursos.

Correspondência de texto

Ao pesquisar uma correspondência de texto, você pode corresponder um campo de metadados de recurso exatamente ou parcialmente.

Correspondência exata de texto

Para uma correspondência exata de texto, use o operador = (igual a) com a seguinte sintaxe:

ASSET_METADATA_FIELD=QUERY

Exemplo:

location=us-central1-a

Considere as seguintes regras ao fazer uma correspondência exata de texto:

Para que a consulta seja verdadeira, o valor dela precisa corresponder exatamente ao valor do campo de metadados do recurso.
Para um campo com um valor de lista, se o valor da consulta corresponder a um dos elementos da lista, ele será considerado uma correspondência.
Os valores de consulta diferenciam maiúsculas de minúsculas.
Um valor de consulta de correspondência exata é tratado como uma frase, mas não pode conter curingas.

Correspondência parcial de texto

Para uma correspondência parcial de texto, use o operador : (tem) com a seguinte sintaxe:

ASSET_METADATA_FIELD:QUERY

Exemplo:

location:us-central1

Ao fazer uma pesquisa com o operador :, os valores da consulta e dos campos de metadados do recurso são convertidos em tokens para comparação. Cada palavra do valor da consulta é verificada para descobrir se ela existe em ordem consecutiva no valor do campo de metadados do recurso. Ao usar correspondências parciais, os valores da consulta não diferenciam maiúsculas de minúsculas.

Os valores de consulta de correspondência parcial podem ser frases ou uma combinação de frases e podem conter curingas. É possível fazer até 10 comparações em uma consulta, com um máximo de 2.048 caracteres. Se você tiver um caso de uso para consultas mais longas, entre em contato com gcp-asset-inventory-and-search-feedback@googlegroups.com.

Regras de tokenização

As regras de tokenização para correspondência parcial de texto são as seguintes:

Os caracteres especiais iniciais e finais são removidos.
Caracteres que não são alfanuméricos ([a-zA-Z0-9]), sublinhados (_) ou e comercial (&) são tratados como delimitadores.

Veja alguns exemplos de tokenização:

us-central1 é tokenizado como [us,central1]
alex-2020@EXAMPLE.com é tokenizado como [alex,2020,example,com]
google.com/cloud é tokenizado como [google,com,cloud]
Compute %Instance% é tokenizado como [compute,instance]
$%^*-! é tokenizado como []
compute*storage é tokenizado como [compute,storage]
compute&storage é tokenizado como [compute&storage]
ALEX_test@example.com é tokenizado como [alex_test,example,com]
instance/_my_vm_ é tokenizado como [instance,_my_vm_]

Exemplos de correspondência exata e parcial de texto

Um recurso cujo campo location tem o valor us-central1-a corresponde às seguintes consultas.

Consulta	Motivo da correspondência
location=us-central1-a	Corresponde porque a frase `us-central1-a` é exatamente igual ao valor do campo.
location:US-Central1-A	Corresponde porque os caracteres de pontuação são tratados como delimitadores e o valor da consulta não diferencia maiúsculas de minúsculas.
location:"us central1 a"	Corresponde porque as palavras na frase `"us central1 a"` correspondem ao valor do campo em ordem consecutiva.
location:(central1 us a)	Corresponde porque as palavras na combinação `(central1 us a)` correspondem às palavras no valor do campo em qualquer ordem.
location:(a "us central1")	Corresponde porque as frases dentro da combinação, `a` e `"us central1"`, correspondem às palavras no valor do campo em qualquer ordem. Como `"us central1"` é uma frase, essas palavras precisam ser correspondidas em ordem consecutiva.
location:us-central*	Corresponde porque o caractere curinga `*` é usado para fazer uma correspondência de prefixo.

Um recurso cujo campo location tem valor us-central1-a não corresponde às seguintes consultas:

Consulta	Motivo da divergência
location=US-central1-a	Não corresponde, porque a frase diferencia maiúsculas de minúsculas. Use o operador `:` em vez de correspondências que não diferenciam maiúsculas de minúsculas.
location=us-central1	Não corresponde, porque a frase corresponde parcialmente ao valor do campo. Use o operador `:` para correspondências parciais.

Criar uma consulta de correspondência de texto

Um valor de consulta pode ser composto de frases, combinações, negações e caracteres curinga.

Frases

Uma frase é uma ou mais palavras que correspondem em ordem. Para fazer a correspondência de palavras sem reordenação, use combinações.

A consulta a seguir corresponde a recursos em que o campo policy tem as palavras alex e 2020 em ordem consecutiva:

policy:"alex 2020"

Um recurso com valor de campo policy igual a "alex.2020@example.com" corresponde à consulta porque as palavras alex e 2020 estão em ordem consecutiva. O . é ignorado porque a pontuação é tratada como um delimitador.

Um recurso com valor de campo policy igual a "2020.alex@example.com" ou "alex.us.2020@example.com" não corresponde, porque as palavras alex e 2020 não estão em ordem consecutiva.

Construir uma frase

Ao criar uma frase, lembre-se das seguintes regras:

Se a frase contiver apenas caracteres do alfabeto latino básico ISO [a-zA-Z], números [0-9], conectores básicos de e-mail ou URL [_-+.@/&] ou caracteres curinga [*], não é necessário colocá-la entre aspas duplas:
```
policy:alex.2020@example.com
```
No entanto, o uso de aspas duplas ainda funciona e se comporta da mesma forma:
```
policy:"alex.2020@example.com"
```
Se a frase tiver espaços ou outros caracteres especiais, ela precisará ser colocada entre aspas duplas:
```
location:"us central1"
```
Se a frase estiver entre aspas duplas e também contiver aspas duplas (") ou uma barra invertida (\), crie um escape para elas como \" ou \\. Ou substitua-os por um espaço único, já que os caracteres não alfanuméricos são tratados como delimitadores ao realizar uma pesquisa. As consultas a seguir são tratadas da mesma forma:
```
description:"One of \"those\" descriptions."
description:"One of those descriptions."
```
Ao usar a CLI gcloud ou a API REST, é necessário usar escape nas aspas duplas usadas para indicar uma frase:
```
--query="location:(a \"us central1\")"
```
```
"query": "location:(a \"us central1\")"
```

Combinações

As frases de pesquisa podem ser combinadas usando os operadores lógicos em maiúsculas AND ou OR. Incluir AND é opcional ao usar parênteses. Por exemplo, as consultas a seguir são tratadas da mesma forma:

policy:(alex charlie)
policy:(alex AND charlie)

Se um recurso tiver um campo de metadados com uma lista de valores, uma combinação AND não vai garantir que todas as palavras estejam em um único elemento. Por exemplo, se um campo de metadados for policy=["alex@example.com", "bola@example.com", "charlie@example.com"], a pesquisa com policy:(alex charlie) vai corresponder, porque alex@example.com contém alex e charlie@example.com contém charlie.

É possível usar parênteses para agrupar tipos de combinação. O exemplo a seguir retorna recursos que têm um campo de política que contém alex e charlie em qualquer ordem ou recursos que têm um campo de política que contém bola.

policy:((alex charlie) OR bola)

Você pode usar uma frase dentro de uma combinação para corresponder a várias palavras em ordem consecutiva. O exemplo a seguir retorna recursos que têm um campo de política que contém alex e 2020 em ordem consecutiva ou bola:

policy:(("alex 2020") OR bola)

Exemplos de combinação

As consultas a seguir demonstram várias combinações. Observe o posicionamento dos parênteses para separar os operadores AND e OR. Combinar operadores em um único conjunto de parênteses é inválido. Por exemplo: policy:(alex charlie OR bola).

Consulta	Descrição
policy:(alex charlie)	Retorna recursos em que o campo `policy` contém `alex` e `charlie`.
policy:(alex OR charlie)	Retorna recursos em que o campo `policy` contém `alex` ou `charlie`.
policy:((alex charlie) OR bola)	Retorna recursos em que o campo `policy` contém `alex` e `charlie` ou tem a palavra `bola`.
policy:(alex charlie) OR name:bola	Retorna recursos em que o campo `policy` contém `alex` e `charlie` ou em que o campo `name` contém `bola`.

Negação

As consultas de pesquisa podem ser negadas usando o operador NOT em maiúsculas. Os parênteses são aceitos, mas não obrigatórios.

Exemplos de negação

Retorna recursos em que o campo state não contém a palavra running.
```
NOT state:running
```
Retorna recursos em que o campo policy não contém alex nem charlie.
```
NOT policy:(alex OR charlie)
```
Retorna recursos em que o campo networkTags não contém internal ou private.
```
NOT (networkTags:internal OR networkTags:private)
```

Caracteres curinga

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

Se * estiver no final de uma frase, ele será tratado como uma correspondência de prefixo de token. Por exemplo, "al 20*" é equivalente a (al* 20*). A ordem dos prefixos não importa.

A frase "al 20*" corresponde a um valor de campo com um token que começa com al (como alex) e um token que começa com 20 (como 2020).
Para labels, se o valor da consulta inteira contiver apenas um * (por exemplo, "labels.env:*"), ele representará uma verificação de existência. Ou seja, o Inventário de recursos do Cloud verifica se a chave de rótulo env existe. Somente o campo labels oferece suporte a verificações de existência.
Se * estiver no meio de uma frase, por exemplo, "compute*storage", ele será tratado como um delimitador de tokenização. Esse valor de consulta é equivalente a "compute storage".
Se * estiver no começo e no fim de uma frase, por exemplo, "*compute storage*", ele será tratado como um delimitador de tokenização. Esse valor de consulta é equivalente a "compute storage".

Comparação numérica e de carimbo de data/hora

Para comparação numérica e de carimbo de data/hora, use operadores de comparação com a seguinte sintaxe:

ASSET_METADATA_FIELD>=QUERY

Os operadores de comparação disponíveis são os seguintes:

=: igual a
>: maior que
>=: maior que ou igual a
<: menor que
<=: menor que ou igual a

Para comparar com carimbos de data/hora, como os armazenados nos campos de metadados de recursos createTime e updateTime, use um número inteiro assinado de 64 bits (o carimbo de data/hora da época em segundos) ou uma string de data e hora UTC+0 em um dos seguintes formatos:

2021-01-01 (AAAA-MM-DD)
"2021-01-01T00:00:00" ("YYYY-MM-DDThh:mm:ss")

Exemplos de data e hora

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:

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

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

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

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

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