Esta página foi traduzida pela API Cloud Translation.

Sintaxe da consulta de pesquisa

Ao pesquisar recursos, é possível filtrar os resultados da pesquisa especificando uma consulta composta por um campo de metadados de recurso, 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 saber quais campos podem ser usados em uma consulta searchAllIamPolicies, consulte Campos de searchAllIamPolicies SearchResult.

Para saber quais recursos podem ser pesquisados, consulte Tipos de recursos.

Correspondência de texto

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

Correspondência de texto exata

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

ASSET_METADATA_FIELD=QUERY

Exemplo:

location=us-central1-a

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

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 da consulta diferenciam maiúsculas de minúsculas.
Um valor de consulta de correspondência exata é tratado como uma frase, mas não pode conter caracteres curinga.

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 realizar uma pesquisa com o operador :, o valor da consulta e os valores do campo de metadados do recurso são convertidos em tokens para comparação. Cada palavra do valor da consulta é verificada para saber 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 caracteres curinga. É 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 ampersands (&) são tratados como delimitadores.

Veja alguns exemplos de tokenização:

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

Exemplos de correspondência de texto exata e parcial

Um recurso com o campo location que 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 com o campo location que tem o valor us-central1-a não corresponde às consultas a seguir.

Consulta	Motivo da divergência
location=US-central1-a	Não corresponde, porque a frase diferencia maiúsculas de minúsculas. Use o operador `:` para 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 fazer correspondências parciais.

Criar uma consulta de correspondência de texto

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

Frases

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

A consulta a seguir corresponde aos recursos em que o campo policy tem a palavra alex e a palavra 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

Considere as seguintes regras ao criar uma frase:

Se a frase contiver apenas caracteres do alfabeto latino básico ISO [a-zA-Z], números [0-9], conectores de e-mail ou URL básicos [_-+.@/&] ou caracteres curinga [*], não será necessário usar aspas duplas:
```
policy:alex.2020@example.com
```
No entanto, o uso de aspas duplas ainda funciona e tem o mesmo comportamento:
```
policy:"alex.2020@example.com"
```
Se a frase tiver espaços ou outros caracteres especiais, ela precisará estar entre aspas duplas:
```
location:"us central1"
```
Se a frase estiver entre aspas duplas e também contiver uma aspa dupla (") ou barra invertida (\), é necessário criar um escape para elas como \" ou \\. Como alternativa, 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 escapar das 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. A inclusão de AND é opcional ao usar parênteses. Por exemplo, as seguintes consultas 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 de AND não garante 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 com um campo de política que contém alex e charlie em qualquer ordem ou recursos com 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ções

As consultas a seguir demonstram várias combinações. Observe a colocação de parênteses para separar os operadores AND e OR. A combinação de operadores em um único conjunto de parênteses é inválida, 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. Dependendo da 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 inteiro 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 início 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 carimbos de data/hora

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

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 aqueles 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/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"