Esta página foi traduzida pela API Cloud Translation.

Sintaxe de consulta de pesquisa

Quando pesquisa recursos, pode filtrar os resultados da pesquisa especificando uma consulta composta por um campo de metadados do recurso, um operador e um valor.

Campos e recursos pesquisáveis

Para ver os campos que pode usar numa consulta searchAllResources, consulte os campos ResourceSearchResult.

Para ver os campos que pode usar numa consulta searchAllIamPolicies, consulte os campos IamPolicySearchResult.

Para ver os recursos que pode pesquisar, consulte o artigo Tipos de recursos.

Correspondência de texto

Quando pesquisa uma correspondência de texto, pode fazer a correspondência de um campo de metadados de recursos exatamente ou parcialmente.

Correspondência exata de texto

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

ASSET_METADATA_FIELD=QUERY

Por exemplo:

location=us-central1-a

Tenha em atenção as seguintes regras quando fizer uma correspondência de texto exata:

Para que a consulta seja verdadeira, o valor da consulta tem de 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, é considerado uma correspondência.
Os valores de consulta são sensíveis a maiúsculas e minúsculas.
Um valor de consulta de correspondência exata é tratado como uma expressão, mas não pode conter carateres universais.

Correspondência parcial de texto

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

ASSET_METADATA_FIELD:QUERY

Por exemplo:

location:us-central1

Quando faz 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 existe por ordem consecutiva no valor do campo de metadados do recurso. Quando usa correspondências parciais, os valores de consulta não são sensíveis a maiúsculas e minúsculas.

Os valores de consulta de correspondência parcial podem ser expressões ou uma combinação de expressões e podem conter carateres universais. Pode fazer até 10 comparações numa consulta, com um máximo de 2048 carateres. Se tiver um exemplo de utilização para consultas mais longas, contacte gcp-asset-inventory-and-search-feedback@googlegroups.com.

Regras de conversão em tokens

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

Os carateres especiais à esquerda e à direita são removidos.
Os carateres que não são alfanuméricos ([a-zA-Z0-9]), sublinhados (_) ou E comerciais (&) são tratados como delimitadores.

Seguem-se alguns exemplos de tokenização:

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

Exemplos de correspondência de texto exata e parcial

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 expressão `us-central1-a` é exatamente igual ao valor do campo.
location:US-Central1-A	Há correspondência porque os carateres de pontuação são tratados como delimitadores e o valor da consulta não é sensível a maiúsculas e minúsculas.
location:"us central1 a"	Há correspondência porque as palavras na expressão `"us central1 a"` correspondem ao valor do campo por ordem consecutiva.
location:(central1 us a)	Há correspondência porque as palavras na combinação `(central1 us a)` correspondem às palavras no valor do campo em qualquer ordem.
location:(a "us central1")	Há uma correspondência porque as expressões na combinação, `a` e `"us central1"`, correspondem às palavras no valor do campo em qualquer ordem. Uma vez que `"us central1"` é uma expressão, estas palavras têm de corresponder por ordem consecutiva.
location:us-central*	Há correspondência porque o caráter universal `*` é usado para fazer uma correspondência de prefixo.

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

Consulta	Motivo da não correspondência
location=US-central1-a	Não corresponde porque a expressão é sensível a maiúsculas e minúsculas. Em alternativa, use o operador `:` para correspondências não sensíveis a maiúsculas e minúsculas.
location=us-central1	Não corresponde porque a frase corresponde parcialmente ao valor do campo. Em alternativa, use o operador `:` para correspondências parciais.

Construa uma consulta de correspondência de texto

Um valor de consulta pode ser composto por expressões, combinações, negações e carateres universais.

Expressões

Uma expressão é uma ou mais palavras que têm correspondência pela ordem. Para fazer corresponder palavras sem respeitar a ordem, use combinações.

A seguinte consulta corresponde a recursos cujo campo policy tem a palavra alex e a palavra 2020 por ordem consecutiva:

policy:"alex 2020"

Um recurso cujo valor do campo policy é "alex.2020@example.com" corresponde à consulta, porque as palavras alex e 2020 estão em ordem consecutiva. O caráter . é ignorado, uma vez que a pontuação é tratada como um delimitador.

Um recurso cujo valor do campo policy é "2020.alex@example.com" ou "alex.us.2020@example.com" não corresponde, porque as palavras alex e 2020 não estão por ordem consecutiva.

Construa uma expressão

Tenha em atenção as seguintes regras quando criar uma expressão:

Se a expressão contiver apenas carateres do alfabeto latino básico ISO [a-zA-Z], números [0-9], conectores básicos de email ou URL [_-+.@/&], ou carateres universais [*], não tem de estar entre aspas duplas:
```
policy:alex.2020@example.com
```
No entanto, a inclusão entre aspas duplas continua a funcionar e tem o mesmo comportamento:
```
policy:"alex.2020@example.com"
```
Se a expressão tiver espaços ou outros carateres especiais, tem de estar entre aspas duplas:
```
location:"us central1"
```
Se a expressão estiver entre aspas duplas e também contiver uma aspa dupla (") ou uma barra invertida (\), tem de usar o caráter de escape como \" ou \\. Em alternativa, substitua-os por um único espaço, uma vez que os carateres não alfanuméricos são tratados como delimitadores quando faz uma pesquisa. As seguintes consultas são tratadas da mesma forma:
```
description:"One of \"those\" descriptions."
description:"One of those descriptions."
```
Quando usar a CLI gcloud ou a API REST, tem de usar carateres de escape nas aspas duplas usadas para indicar uma expressão:
```
--query="location:(a \"us central1\")"
```
```
"query": "location:(a \"us central1\")"
```

Combinações

As expressões de pesquisa podem ser combinadas através dos operadores lógicos em maiúsculas AND ou OR. A inclusão de AND é opcional quando usa parênteses. Por exemplo, as seguintes consultas são tratadas da mesma forma:

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

Se um recurso contiver um campo de metadados com uma lista de valores, uma AND combinação não garante que todas as palavras têm de estar num ú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) corresponde, porque alex@example.com contém alex e charlie@example.com contém charlie.

Pode usar parênteses para agrupar tipos de combinações. O exemplo seguinte devolve 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)

Pode usar uma expressão numa combinação para fazer corresponder várias palavras em ordem consecutiva. O exemplo seguinte devolve recursos que têm um campo de política que contém alex e 2020 por ordem consecutiva ou bola:

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

Exemplos de combinações

As consultas seguintes demonstram várias combinações. Tenha em atenção o posicionamento dos parênteses para separar os operadores AND e OR. A combinação de operadores num único conjunto de parênteses é inválida, por exemplo: policy:(alex charlie OR bola).

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

Negação

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

Exemplos de negação

Devolve recursos cujo campo state não contém a palavra running.
```
NOT state:running
```
Devolva recursos cujo campo policy não contenha alex nem charlie.
```
NOT policy:(alex OR charlie)
```
Devolva recursos cujo campo networkTags não contenha internal ou private.
```
NOT (networkTags:internal OR networkTags:private)
```

Carateres universais

Os asteriscos (*) podem ser usados numa expressão como um caráter universal. Consoante a posição, um asterisco pode ter significados diferentes.

Se * estiver no final de uma expressão, é tratado como uma correspondência de prefixos de tokens. Por exemplo, "al 20*" é equivalente a (al* 20*). A ordem dos prefixos não é importante.

A expressão "al 20*" corresponde a um valor de campo com um token que começa por al (como alex) e um token que começa por 20 (como 2020).
Para labels, se o valor da consulta completo contiver apenas um único *, por exemplo, "labels.env:*", representa uma verificação de existência. Ou seja, o Cloud Asset Inventory verifica se a chave da etiqueta env existe. Apenas o campo labels suporta verificações de existência.
Se * estiver no meio de uma frase, por exemplo, "compute*storage", é tratado como um delimitador de tokenização. Este valor de consulta é equivalente a "compute storage".
Se * estiver no início e no fim de uma expressão, por exemplo, "*compute storage*", é tratado como um delimitador de tokenização. Este valor de consulta é equivalente a "compute storage".

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

Para a comparação numérica e 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
>: superior a
>=: superior ou igual a
<: inferior a
<=: inferior ou igual a

Para comparar com indicações de tempo, como as armazenadas nos campos de metadados de recursos createTime e updateTime, use um número inteiro com sinal de 64 bits (a indicação de tempo de época em segundos) ou uma string de data/hora UTC+0 num dos seguintes formatos:

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

Exemplos de data/hora

Um recurso cujo campo createTime tem o valor 1609459200 (data/hora de é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"