Sintaxis de las búsquedas

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

Campos y recursos aptos para búsquedas

Para conocer los campos que puedes usar en una búsqueda de searchAllResources, consulta Campos de ResourceSearchResult.

Para conocer los campos que puedes usar en una búsqueda de searchAllIamPolicies, consulta Campos de IamPolicySearchResult.

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

Coincidencia de texto

Cuando buscas una coincidencia de texto, puedes hacer que coincida un campo de metadatos de un recurso exactamente o parcialmente.

Coincidencia exacta de texto

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

ASSET_METADATA_FIELD=QUERY

Por ejemplo:

location=us-central1-a

Ten en cuenta las siguientes reglas cuando realices una coincidencia de texto exacta:

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

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

• Los valores de la consulta distinguen mayúsculas de minúsculas.

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

Coincidencia parcial de texto

Para 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 :, el valor de la búsqueda y los valores de los campos de metadatos del activo se convierten en tokens para la comparación. Se verifica cada palabra del valor de la búsqueda para determinar si existe en orden consecutivo en el valor del campo de metadatos del activo. Cuando se usan coincidencias parciales, los valores de la búsqueda no distinguen mayúsculas de minúsculas.

Los valores de consulta de coincidencia parcial pueden ser frases o una combinación de frases, y pueden contener comodines. Se pueden realizar hasta 10 comparaciones en una consulta, con un máximo de 2,048 caracteres. Si tienes un caso de uso para consultas más largas, comunícate con [e-mail].

Reglas de tokenización

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

• Se quitan los caracteres especiales iniciales y finales.

• Los caracteres que no sean alfanuméricos ([a-zA-Z0-9]), guiones bajos (_) o ampersands (&) se tratan como delimitadores.

A continuación, se presentan algunos ejemplos de asignación de token:

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

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

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

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

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

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

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

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

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

Ejemplos de concordancia de texto exacta y parcial

Un activo cuyo campo location tiene el valor us-central1-a coincide con las siguientes búsquedas.

Consulta	Motivo de la coincidencia
location=us-central1-a	Coincide porque la frase us-central1-a es exactamente la misma que el valor del campo.
location:US-Central1-A	Coincide porque los caracteres de puntuación se tratan como delimitadores y el valor de la búsqueda no distingue entre mayúsculas y minúsculas.
location:"us central1 a"	Coincide porque las palabras de la frase "us central1 a" coinciden con el valor del campo en orden consecutivo.
location:(central1 us a)	Coincide 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 dentro 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 el comodín * se usa para hacer una coincidencia de prefijo.

Un activo cuyo campo location tiene el valor us-central1-a no coincide con las siguientes búsquedas.

Consulta	Motivo por el que no hay coincidencia
location=US-central1-a	No coincide porque la frase distingue mayúsculas de minúsculas. En su lugar, usa el operador : para las coincidencias que no distinguen entre mayúsculas y minúsculas.
location=us-central1	No coincide porque la frase coincide de forma parcial con el valor del campo. En su lugar, usa el operador : para las coincidencias parciales.

Cómo construir una búsqueda de coincidencia de texto

Un valor de búsqueda puede estar compuesto por frases, combinaciones, negaciones y comodines.

Frases

Una frase es una o más palabras que coinciden en orden. Para que coincidan palabras sin respetar el orden, usa combinaciones.

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

policy:"alex 2020"

Un activo cuyo valor del campo policy es "[e-mail]" coincide con la búsqueda, ya que las palabras alex y 2020 están en orden consecutivo. Se ignora el carácter ., ya que la puntuación se trata como un delimitador.

No coincide un activo cuyo valor del campo policy sea "[e-mail]" o "[e-mail]", ya que las palabras alex y 2020 no están en orden consecutivo.

Cómo construir una frase

Ten en cuenta las siguientes reglas cuando construyas una frase:

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

  policy:[e-mail]
  

  Sin embargo, el uso de comillas dobles sigue funcionando y se comporta de la misma manera:

  policy:"[e-mail]"
  

• Si la frase tiene espacios o algún otro carácter especial, debe estar entre comillas dobles:

  location:"us central1"
  

• Si la frase está entre comillas dobles y también contiene una comilla doble (") o una barra inversa (\), debes reemplazarlas por \" o \\. También puedes reemplazarlos por un solo espacio, ya que los caracteres no alfanuméricos se tratan como delimitadores cuando se realiza una búsqueda. Las siguientes búsquedas se tratan de la misma manera:

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

• Cuando usas gcloud CLI o la API de REST, debes agregar un carácter de escape a 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 con 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 manera:

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

Si un activo contiene un campo de metadatos con una lista de valores, una combinación de 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]"], la búsqueda con policy:(alex charlie) coincide, ya que [e-mail] contiene alex y [e-mail] contiene charlie.

Puedes usar paréntesis para agrupar los tipos de combinación. En el siguiente ejemplo, se muestran los recursos que tienen un campo de política que contiene alex y charlie en cualquier orden, o bien 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 muestran 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

En las siguientes búsquedas, se muestran varias combinaciones. Observa la ubicación de los paréntesis para separar los operadores AND y OR. No es válido combinar operadores dentro de un solo conjunto de paréntesis, por ejemplo, policy:(alex charlie OR bola).

Consulta	Descripción
policy:(alex charlie)	Devuelve los recursos cuyo campo policy contiene alex y 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 alex y 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 búsquedas se pueden negar con el operador NOT en mayúsculas. Los paréntesis son compatibles, pero no obligatorios.

Nota: La negación solo se admite cuando se buscan recursos, no políticas de IAM.

Ejemplos de negación

• Muestra los elementos cuyo campo state no contengan la palabra running.

  NOT state:running
  

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

  NOT policy:(alex OR charlie)
  

• Muestra los elementos cuyo campo networkTags no contenga internal ni private.

  NOT (networkTags:internal OR networkTags:private)
  

Comodines

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

• 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*). No importa el orden de los prefijos.

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

• En el caso de labels, si todo el valor de la búsqueda solo contiene un solo * (por ejemplo, "labels.env:*"), representa una verificación de existencia. Es decir, Cloud Asset Inventory verifica si existe la clave de etiqueta env. Solo el campo labels admite verificaciones de existencia.

• Si * está en medio de una frase, por ejemplo, "compute*storage", se trata como un delimitador de asignación de token. Este valor de la búsqueda es equivalente 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. El valor de esta consulta es equivalente a "compute storage".

Comparación numérica y de marcas de tiempo

Para la comparación numérica y de 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

• <: Menor que

• <=: Menor o igual que

Para comparar con marcas de tiempo, como las que se almacenan en los campos de metadatos de activos createTime y updateTime, usa un número entero de 64 bits con firma (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 activo cuyo campo createTime tiene el valor 1609459200 (marca de tiempo de época de 2021-01-01T00:00:00) coincide con las siguientes búsquedas:

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"