Referencia de filtros de CEL para operaciones de almacenamiento por lotes

En esta página, se describe la sintaxis de Common Expression Language (CEL) y las operaciones admitidas cuando creas filtros avanzados para el trabajo de operaciones por lotes de almacenamiento en función de los 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 reglas de CEL directamente en los metadatos del objeto.

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 seleccionar objetos, las operaciones por lotes en objetos almacenados se orientan a objetos que están activos y actualizados según la instantánea del conjunto de datos seleccionado. Por lo tanto, el trabajo solo incluye objetos que tienen un valor NULL para softDeleteTime y timeDeleted en el momento de la instantánea.

Operadores y funciones compatibles

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

Operador Uso de CEL Sintaxis de GoogleSQL equivalente Descripción
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Coincide con objetos que tienen un atributo de cadena que comienza con un prefijo específico.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Coincide con objetos que tienen un atributo de cadena que termina con un sufijo específico.
Es igual a == = Coincide con objetos que tienen un atributo que es igual a un valor específico.
No es igual a != != Excluye objetos con un atributo que coincida exactamente con un valor específico.
Mayor que > > Coincide con objetos que tienen un atributo de número entero o marca de tiempo que supera un umbral.
Mayor o igual que >= >= Coincide con objetos que tienen un atributo de número entero o marca de tiempo igual o superior a un umbral.
Menor que < < Coincide con objetos que tengan un atributo de número entero o marca de tiempo inferior a un umbral.
Menor o igual que <= <= Coincide con objetos que tienen un atributo de número entero o marca de tiempo igual o inferior a un umbral.
Contiene name.contains("substring") STRPOS(name, "substring") != 0 Coincide con objetos que tienen un atributo de cadena que contiene la subcadena.
En name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Coincide con los objetos que tienen un atributo que existe en la lista proporcionada.
NOT lógico ! NOT Invierte una regla para filtrar los 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 las 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) Coincide 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 construyes expresiones de filtro, puedes hacer referencia a campos a nivel de bucket y a nivel de objeto. Los siguientes identificadores se asignan a campos reconocidos en los esquemas de tablas del conjunto de datos de Storage Insights:

Atributos de los buckets

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

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

Atributos de objetos

Puedes usar los siguientes atributos para filtrar los trabajos de operaciones por lotes en objetos almacenados por campos a nivel de objeto:

Campo Tipo Descripción
name STRING El nombre del objeto.
contexts REPEATED RECORD Son los contextos adjuntos a un objeto.
contexts.key STRING Es la clave de contexto personalizado.
contexts.value STRING Es el valor de la clave de contexto personalizado.
contexts.type STRING Es el tipo de contexto personalizado.
contexts.createTime TIMESTAMP Es la hora en la que se creó la clave de contexto personalizada.
contexts.updateTime TIMESTAMP Es la hora en la que se actualizó la clave de contexto personalizada.
contentType STRING Es la categorización del contenido por tipo de MIME.
customTime TIMESTAMP Marca de tiempo definida por el usuario.
generation INTEGER Es el identificador de generación del objeto.
metadata REPEATED RECORD Metadatos personalizados.
metadata.key STRING Es la clave de metadatos personalizados.
metadata.value STRING Es el valor de los metadatos personalizados.
metageneration INTEGER Es el identificador de la generación de metadatos.
retentionExpirationTime TIMESTAMP Es la hora en la que vence la retención del objeto.
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 Es el estado de legibilidad pública del objeto. Los valores admitidos son PUBLIC, NOT_PUBLIC, UNSUPPORTED, and ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Si readPublicAccess es PUBLIC, devuelve la fuente del permiso de lectura público. Los valores admitidos son Object, Bucket y ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING Es el estado de escritura pública del objeto. Los valores admitidos son PUBLIC, NOT_PUBLIC, UNSUPPORTED, and ERROR.
size INTEGER Es el tamaño del objeto en bytes.
storageClass STRING La clase de almacenamiento asignada.
temporaryHold BOOLEAN Estado de bloqueo activo que impide el lanzamiento.
timeCreated TIMESTAMP Reloj de registro de generación inicial.
timeStorageClassUpdated TIMESTAMP Es la hora en la que se actualizó la clase de almacenamiento por última vez.
updated TIMESTAMP Es la 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 lógico AND (&&). El motor de consultas no admite el operador lógico OR (||).
  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 en objetos almacenados 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 fallará. Usa campos específicos a nivel de bucket (por ejemplo, filtrado por ubicación, como location == "us-central1", o coincidencia de nombres, como name.startsWith("prod-")) para reducir el alcance de la consulta y cumplir con este límite.
  5. Límite de caracteres: Los filtros de bucket y de objetos tienen un límite de 150 caracteres como máximo.

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 los objetos en la clase de almacenamiento Standard Storage en las ubicaciones de US: 

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

  • Filtrar por retención de eliminación no definitiva: Aplica acciones a los objetos de los 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 de más de 5 KiB: 

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

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

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

  • Coincidir con pares clave-valor de contexto personalizado: Aplica acciones a los objetos que tienen una clave de contexto personalizada env con un valor de prod: 

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

  • Hacer coincidir los valores de contexto personalizados por prefijo y sufijo: Aplica acciones a los objetos con un valor de contexto personalizado que comience con el prefijo prod y termine 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 los objetos que no tienen una clave de contexto personalizada env: 

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

¿Qué sigue?