Sintaxis de las consultas de búsqueda

Cuando buscas recursos, puedes filtrar los resultados de búsqueda especificando una consulta compuesta por un campo de metadatos de recursos, un operador y un valor.

Campos y recursos en los que se pueden realizar búsquedas

Para ver los campos que puede usar en una consulta searchAllResources, consulte Campos de ResourceSearchResult.

Para ver los campos que puede usar en una consulta searchAllIamPolicies, consulte Campos de IamPolicySearchResult.

Para ver los recursos que puedes buscar, consulta Tipos de recursos.

Coincidencia de texto

Cuando buscas una coincidencia de texto, puedes buscar una coincidencia exacta o parcial en un campo de metadatos de un recurso.

Concordancia de texto exacta

Para buscar una coincidencia de texto exacta, usa el operador = (igual) con la siguiente sintaxis:

ASSET_METADATA_FIELD=QUERY

Por ejemplo:

location=us-central1-a

Cuando hagas una búsqueda de texto exacto, ten en cuenta las siguientes reglas:

• Para que la consulta sea verdadera, el valor de la consulta debe coincidir exactamente con el valor del campo de metadatos del recurso.

• En el caso de un campo con un valor de lista, si el valor de la consulta coincide con uno de los elementos de la lista, se considera una coincidencia.

• En los valores de las consultas, se distingue entre mayúsculas y minúsculas.

• Un valor de consulta de coincidencia exacta se trata como una frase, pero no puede contener comodines.

Coincidencia parcial de texto

Para que se encuentre una coincidencia parcial de texto, usa el operador : (tiene) con la siguiente sintaxis:

ASSET_METADATA_FIELD:QUERY

Por ejemplo:

location:us-central1

Cuando se realiza una búsqueda con el operador :, los valores de la consulta y los valores del campo de metadatos del recurso se convierten en tokens para compararlos. Se comprueba cada palabra del valor de la consulta para determinar si existe en orden consecutivo en el valor del campo de metadatos del recurso. Cuando se usan coincidencias parciales, los valores de consulta no distinguen entre mayúsculas y minúsculas.

Los valores de consulta de coincidencia parcial pueden ser frases o una combinación de frases, y pueden contener comodines. Se pueden hacer hasta 10 comparaciones en una consulta, con un máximo de 2048 caracteres. Si tienes un caso práctico para consultas más largas, ponte en contacto con [e-mail].

Reglas de tokenización

Las reglas de tokenización para la coincidencia de texto parcial son las siguientes:

• Se quitan los caracteres especiales iniciales y finales.

• Los caracteres que no son alfanuméricos ([a-zA-Z0-9]), guiones bajos (_) ni signos et (&) se tratan como delimitadores.

Aquí tienes algunos ejemplos de tokenización:

• us-central1 se tokeniza en [us,central1]

• [e-mail] se tokeniza en [alex,2020,example,com]

• google.com/cloud se tokeniza en [google,com,cloud]

• Compute %Instance% se tokeniza en [compute,instance]

• $%^*-! se tokeniza en []

• compute*storage se tokeniza en [compute,storage]

• compute&storage se tokeniza en [compute&storage]

• [e-mail] se tokeniza en [alex_test,example,com]

• instance/_my_vm_ se tokeniza en [instance,_my_vm_]

Ejemplos de coincidencias de texto exactas y parciales

Un recurso cuyo campo location tiene el valor us-central1-a coincide con las siguientes consultas.

Consulta	Motivo de la coincidencia
location=us-central1-a	Coincide porque la frase us-central1-a es exactamente igual al valor del campo.
location:US-Central1-A	Hay una coincidencia porque los signos de puntuación se tratan como delimitadores y el valor de la consulta no distingue entre mayúsculas y minúsculas.
location:"us central1 a"	Se produce una coincidencia porque las palabras de la frase "us central1 a" coinciden con el valor del campo en orden consecutivo.
location:(central1 us a)	Se produce una coincidencia porque las palabras de la combinación (central1 us a) coinciden con las palabras del valor del campo en cualquier orden.
location:(a "us central1")	Coincide porque las frases de la combinación, a y "us central1", coinciden con las palabras del valor del campo en cualquier orden. Como "us central1" es una frase, estas palabras deben coincidir en orden consecutivo.
location:us-central*	Coincide porque se usa el comodín * para hacer una coincidencia de prefijo.

Un recurso cuyo campo location tiene el valor us-central1-a no coincide con las siguientes consultas.

Consulta	Motivo por el que no coincide
location=US-central1-a	No coincide porque la frase distingue entre mayúsculas y minúsculas. En su lugar, usa el operador : para buscar coincidencias sin distinguir entre mayúsculas y minúsculas.
location=us-central1	No coincide porque la frase coincide parcialmente con el valor del campo. En su lugar, usa el operador : para obtener coincidencias parciales.

Construir una consulta de coincidencia de texto

Un valor de consulta puede estar formado por frases, combinaciones, negaciones y comodines.

Frases

Una frase es una o varias palabras que coinciden en orden. Para buscar palabras sin tener en cuenta el orden, usa combinaciones.

La siguiente consulta coincide con los recursos cuyo campo policy contiene la palabra alex y la palabra 2020 en orden consecutivo:

policy:"alex 2020"

Un recurso cuyo valor del campo policy es "[e-mail]" coincide con la consulta porque las palabras alex y 2020 están en orden consecutivo. Se ignora el ., ya que los signos de puntuación se tratan como delimitadores.

Un recurso cuyo valor del campo policy es "[e-mail]" o "[e-mail]" no coincide porque las palabras alex y 2020 no están en orden consecutivo.

Construir una frase

Cuando crees una frase, ten en cuenta las siguientes reglas:

• Si la frase solo contiene caracteres del alfabeto latino básico ISO [a-zA-Z], números [0-9], conectores básicos de correo electrónico o URL [_-+.@/&] o comodines [*], no es necesario que vaya entre comillas dobles:

  policy:[e-mail]
  

  Sin embargo, seguirás pudiendo usar comillas dobles, que se comportarán de la misma forma:

  policy:"[e-mail]"
  

• Si la frase tiene espacios u otros caracteres especiales, debe incluirse entre comillas dobles:

  location:"us central1"
  

• Si la frase está entre comillas dobles y también contiene comillas dobles (") o una barra inversa (\), debe usar el formato de escape \" o \\. También puedes sustituirlos por un espacio, ya que los caracteres no alfanuméricos se tratan como delimitadores al realizar una búsqueda. Las siguientes consultas se tratan de la misma forma:

  description:"One of \"those\" descriptions."
  description:"One of those descriptions."
  

• Cuando se usa la CLI de gcloud o la API REST, es necesario usar el carácter de escape para las comillas dobles que se usan para indicar una frase:

  --query="location:(a \"us central1\")"
  

  "query": "location:(a \"us central1\")"
  

Combinaciones

Las frases de búsqueda se pueden combinar mediante los operadores lógicos en mayúsculas AND o OR. Incluir AND es opcional cuando se usan paréntesis. Por ejemplo, las siguientes consultas se tratan de la misma forma:

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

Si un recurso contiene un campo de metadatos con una lista de valores, una combinación AND no garantiza que todas las palabras deban estar en un solo elemento. Por ejemplo, si un campo de metadatos es policy=["[e-mail]", "[e-mail]", "[e-mail]"], al buscar con policy:(alex charlie) se obtienen coincidencias, ya que [e-mail] contiene alex y [e-mail] contiene charlie.

Puedes usar paréntesis para agrupar tipos de combinación. En el siguiente ejemplo se devuelven los recursos que tienen un campo de política que contiene alex y charlie en cualquier orden, o los recursos que tienen un campo de política que contiene bola.

policy:((alex charlie) OR bola)

Puedes usar una frase dentro de una combinación para que coincida con varias palabras en orden consecutivo. En el siguiente ejemplo se devuelven los recursos que tienen un campo de política que contiene alex y 2020 en orden consecutivo, o bola:

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

Ejemplos de combinaciones

Las siguientes consultas muestran varias combinaciones. Fíjate en la colocación de los paréntesis para separar los operadores AND y OR. No se pueden combinar operadores dentro de un mismo conjunto de paréntesis. Por ejemplo: policy:(alex charlie OR bola).

Consulta	Descripción
policy:(alex charlie)	Devuelve los recursos cuyo campo policy contiene tanto alex como charlie.
policy:(alex OR charlie)	Devuelve los recursos cuyo campo policy contiene alex o charlie.
policy:((alex charlie) OR bola)	Devuelve los recursos cuyo campo policy contiene tanto alex como charlie, o bien la palabra bola.
policy:(alex charlie) OR name:bola	Devuelve los recursos cuyo campo policy contiene alex y charlie, o cuyo campo name contiene bola.

Negación

Las consultas de búsqueda se pueden negar con el operador NOT en mayúsculas. Se admiten los paréntesis, pero no son obligatorios.

Nota: La negación solo se admite al buscar recursos, no en las políticas de gestión de identidades y accesos.

Ejemplos de negación

• Devuelve los recursos cuyo campo state no contenga la palabra running.

  NOT state:running
  

• Devuelve los recursos cuyo campo policy no contenga ni alex ni charlie.

  NOT policy:(alex OR charlie)
  

• Devuelve los recursos cuyo campo networkTags no contenga internal ni private.

  NOT (networkTags:internal OR networkTags:private)
  

Comodines

Los asteriscos (*) se pueden usar en una frase como caracteres comodín. Según la posición, un asterisco puede tener significados diferentes.

• Si * está al final de una frase, se trata como una coincidencia de prefijo de token. Por ejemplo, "al 20*" es equivalente a (al* 20*). El orden de los prefijos no importa.

  La frase "al 20*" coincide con un valor de campo que contiene un token que empieza por al (como alex) y un token que empieza por 20 (como 2020).

• En el caso de labels, si todo el valor de la consulta solo contiene un * (por ejemplo, "labels.env:*"), representa una comprobación de existencia. Es decir, Inventario de Recursos de Cloud comprueba si existe la clave de etiqueta env. Solo el campo labels admite comprobaciones de existencia.

• Si * está en medio de una frase (por ejemplo, "compute*storage"), se trata como un delimitador de tokenización. Este valor de consulta equivale a "compute storage".

• Si * está al principio y al final de una frase (por ejemplo, "*compute storage*"), se trata como un delimitador de tokenización. Este valor de consulta equivale a "compute storage".

Comparación numérica y de marcas de tiempo

Para comparar números y marcas de tiempo, usa operadores de comparación con la siguiente sintaxis:

ASSET_METADATA_FIELD>=QUERY

Los operadores de comparación disponibles son los siguientes:

• =: igual a

• >: mayor que

• >=: mayor o igual que

• <: inferior a

• <=: menor o igual que

Para comparar con marcas de tiempo como las almacenadas en los campos de metadatos de recursos createTime y updateTime, utilice un entero de 64 bits con signo (la marca de tiempo de época en segundos) o una cadena de fecha y hora UTC+0 en uno de los siguientes formatos:

• 2021-01-01 (AAAA-MM-DD)

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

Ejemplos de fecha y hora

Un recurso cuyo campo createTime tiene el valor 1609459200 (marca de tiempo de época de 2021-01-01T00:00:00) coincide con las siguientes 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"