Referencia de filtros de CEL para operaciones de almacenamiento por lotes

En esta página, se describe la sintaxis del Common Expression Language (CEL) y las operaciones admitidas cuando compilas filtros avanzados para trabajos de operaciones por lotes de almacenamiento basados en campos del conjunto de datos de Storage Insights.

Puedes usar filtros avanzados para evaluar condiciones y automatizar acciones de administración en millones de archivos según los campos de tu conjunto de datos de Storage Insights. Los filtros admitidos usan CEL directamente en los metadatos de objetos.

Proporciona reglas de filtro con las marcas --bucket-filters y --object-filters en Google Cloud CLI, o los campos bucketFilters y objectFilters en la API de JSON cuando creas un trabajo. Esta opción elimina la necesidad de consultar BigQuery de forma manual, exportar listas de objetos a CSV y volver a subir manifiestos a tus buckets. Cuando usas filtros de conjuntos de datos para la selección de objetos, las operaciones por lotes de almacenamiento segmentan objetos que están activos y actualizados a partir de la instantánea del conjunto de datos seleccionado. En consecuencia, el trabajo solo incluye objetos que tienen un valor NULL para softDeleteTime y timeDeleted en el momento de la instantánea.

Operadores y funciones admitidos

Los filtros avanzados admiten condiciones unidas por instrucciones AND (&&) lógicas. Usa los siguientes operadores para compilar tus cadenas de criterios:

Operador Uso de CEL Sintaxis equivalente de GoogleSQL Descripción
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Establece coincidencias con objetos con un atributo de cadena que comienza con un prefijo específico.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Establece coincidencias con objetos con un atributo de cadena que termina con un sufijo específico.
Es igual a == = Establece coincidencias con objetos con un atributo que es igual a un valor específico.
No es igual a != != Excluye objetos con un atributo que coincide exactamente con un valor específico.
Mayor que > > Establece coincidencias con objetos con un atributo de número entero o marca de tiempo que supera un umbral.
Mayor o igual que >= >= Establece coincidencias con objetos con un atributo de número entero o marca de tiempo que es igual o supera un umbral.
Menor que < < Establece coincidencias con objetos con un atributo de número entero o marca de tiempo que está por debajo de un umbral.
Menor o igual que <= <= Establece coincidencias con objetos con un atributo de número entero o marca de tiempo que es igual o está por debajo de un umbral.
Contiene name.contains("substring") STRPOS(name, "substring") != 0 Establece coincidencias con objetos con un atributo de cadena que contiene la subcadena.
En name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Establece coincidencias con objetos con un atributo que existe en la lista proporcionada.
NOT lógico ! NOT Invierte una regla para filtrar objetos que no coinciden con las condiciones.
Marca de tiempo timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" Convierte cadenas de fecha con formato RFC 3339 en una marca de tiempo. Esta función admite la precisión de microsegundos para que coincida con los estándares de tipo TIMESTAMP de BigQuery.
Ya existe. contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Establece coincidencias con objetos en los que al menos un elemento dentro de un atributo de tipo de registro repetido cumple con una condición específica.

Identificadores admitidos

Cuando compilas expresiones de filtro, puedes hacer referencia a campos a nivel del bucket y a nivel del objeto. Los siguientes identificadores se asignan a campos reconocidos en los esquemas de tablas del conjunto de datos de Storage Insights:

Atributos del bucket

Puedes usar los siguientes campos a nivel del bucket para filtrar qué buckets se incluyen en tus trabajos de operaciones por lotes de almacenamiento.

Campo Tipo Descripción
name STRING El nombre del bucket.
autoclass RECORD Contiene metadatos enabled y toggleTime.
autoclass.enabled BOOLEAN Indica si Autoclass está habilitado para el bucket.
autoclass.toggleTime TIMESTAMP La hora en la que se habilitó o inhabilitó Autoclass por última vez.
labels REPEATED RECORD Contiene mapas clave-valor estándar.
location STRING Identificador de ubicación del bucket.
softDeletePolicy RECORD Contiene retentionDurationSeconds y effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER El período de retención de eliminación no definitiva, en segundos.
softDeletePolicy.effectiveTime TIMESTAMP La hora en la que entró en vigencia la política de eliminación no definitiva.

Atributos de objetos

Puedes usar los siguientes atributos para filtrar trabajos de operaciones por lotes de almacenamiento por campos a nivel del objeto:

Campo Tipo Descripción
name STRING El nombre del objeto.
contexts REPEATED RECORD Contextos adjuntos a un objeto.
contexts.key STRING La clave de contexto personalizado.
contexts.value STRING El valor de la clave de contexto personalizado.
contexts.type STRING El tipo de contexto personalizado.
contexts.createTime TIMESTAMP La hora en la que se creó la clave de contexto personalizado.
contexts.updateTime TIMESTAMP La hora en la que se actualizó la clave de contexto personalizado.
contentType STRING Categorización del contenido del tipo de MIME.
customTime TIMESTAMP Marca de tiempo definida por el usuario.
generation INTEGER Identificador de generación de objetos.
metadata REPEATED RECORD Metadatos personalizados.
metadata.key STRING La clave de metadatos personalizados.
metadata.value STRING El valor de metadatos personalizados.
metageneration INTEGER Identificador de generación de metadatos.
retentionExpirationTime TIMESTAMP Hora en la que vence la retención de objetos.
securityInsights RECORD Contiene estadísticas de acceso público para el objeto.
securityInsights.publicAccessInsight RECORD Proporciona el estado de accesibilidad pública del objeto.
securityInsights.publicAccessInsight.readPublicAccess STRING El estado de legibilidad pública del objeto. Los valores admitidos son PUBLIC, NOT_PUBLIC, UNSUPPORTED y ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Si readPublicAccess es PUBLIC, muestra la fuente del permiso de lectura pública. Los valores admitidos son Object, Bucket y ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING El estado de capacidad de escritura pública del objeto. Los valores admitidos son PUBLIC, NOT_PUBLIC, UNSUPPORTED y ERROR.
size INTEGER Tamaño del objeto en bytes.
storageClass STRING La clase de almacenamiento asignada.
temporaryHold BOOLEAN Estado de bloqueo activo que impide la liberación.
timeCreated TIMESTAMP Reloj de registro de generación inicial.
timeStorageClassUpdated TIMESTAMP Hora en la que se actualizó la clase de almacenamiento por última vez.
updated TIMESTAMP Hora en la que se actualizó el objeto por última vez.

Reglas de formato de expresiones

Para ayudar a que tus trabajos se ejecuten a gran escala, el motor de consultas aplica las siguientes reglas de formato:

  1. Condiciones de filtro: Solo puedes unir condiciones de filtro con el operador AND (&&) lógico. El motor de consultas no admite el operador OR (||) lógico.
  2. Posicionamiento de argumentos: Debes colocar el campo de metadatos de destino en el lado izquierdo de las funciones. Por ejemplo, usa name.startsWith("live-") en lugar de "live-".startsWith(name).
  3. Métodos de array: Puedes llamar a la macro exists directamente en campos repetidos, como contexts.exists(...) o metadata.exists(...).
  4. Límite de buckets: Un solo trabajo de operaciones por lotes de almacenamiento puede operar en hasta 1,000 buckets. Si tus expresiones de filtro coinciden de forma dinámica con más de 1,000 buckets en tu conjunto de datos, la creación del trabajo falla. Usa campos específicos a nivel del bucket (por ejemplo, el filtrado de ubicación como location == "us-central1" o la coincidencia de nombres como name.startsWith("prod-")) para reducir el alcance de tu consulta y satisfacer este límite.
  5. Límite de caracteres: Los filtros de buckets y los filtros de objetos están limitados a un máximo de 150 caracteres cada uno.

Ejemplos

En los siguientes ejemplos, se muestran filtros combinados comunes que puedes usar para segmentar recursos en todo el proyecto. Especifica los fragmentos de filtro directamente como marcas en el comando gcloud storage batch-operations jobs create:

  • Segmenta buckets específicos: Aplica acciones a objetos en buckets específicos: 

    --bucket-filters="name in ['bucket-1', 'bucket-2']"

  • Verifica la clase de almacenamiento y la ubicación del bucket: Aplica acciones a objetos en la clase de almacenamiento Standard Storage en US ubicaciones: 

    --bucket-filters="location.startsWith('us')" 
    
--object-filters="storageClass == 'STANDARD'"

  • Filtra por retención de eliminación no definitiva: Aplica acciones a objetos en buckets que tienen habilitada la eliminación no definitiva durante al menos 7 días: 

    --bucket-filters="softDeletePolicy.retentionDurationSeconds >= 604800"

  • Filtra por tamaño y extensiones de objetos: Busca objetos PDF mayores que 5 KiB: 

    --object-filters="size >= 5120 && name.endsWith('.pdf')"

  • Verifica las claves de contexto personalizadas: Aplica acciones a objetos que tienen una clave de contexto personalizada env: 

    --object-filters="contexts.exists(context, context.key == 'env')"

  • Establece coincidencias con pares clave-valor de contexto personalizados: Aplica acciones a objetos que tienen una clave de contexto personalizado env con un valor de prod: 

    --object-filters="contexts.exists(context, context.key == 'env' && context.value == 'prod')"

  • Establece coincidencias con valores de contexto personalizados por prefijo y sufijo: Aplica acciones a objetos con un valor de contexto personalizado que comienza con el prefijo prod y termina con el sufijo .txt: 

    --object-filters="contexts.exists(context, context.value.startsWith('prod') && context.value.endsWith('.txt'))"

  • Identifica las claves de contexto faltantes: Aplica acciones a objetos que no tienen una clave de contexto personalizado env: 

    --object-filters="!contexts.exists(context, context.key == 'env')"

¿Qué sigue?