Referência de filtros CEL para operações em lote de armazenamento

Esta página descreve a sintaxe da Common Expression Language (CEL) e as operações compatíveis ao criar filtros avançados para jobs de operações em lote de armazenamento com base em campos do conjunto de dados do Storage Insights.

É possível usar filtros avançados para avaliar condições e automatizar ações de gerenciamento em milhões de arquivos com base em campos no conjunto de dados do Storage Insights. Os filtros compatíveis usam CEL diretamente nos metadados do objeto.

Forneça regras de filtro usando as flags --bucket-filters e --object-filters na Google Cloud CLI ou os campos bucketFilters e objectFilters na API JSON ao criar um job. Essa opção elimina a necessidade de consultar manualmente o BigQuery, exportar listas de objetos para CSV e fazer upload de manifestos de volta aos buckets. Quando você usa filtros de conjunto de dados para seleção de objetos, as operações em lote de armazenamento têm como destino objetos ativos e atuais no momento do snapshot do conjunto de dados selecionado. Consequentemente, o job inclui apenas objetos que têm um valor NULL para softDeleteTime e timeDeleted no momento do snapshot.

Operadores e funções compatíveis

Os filtros avançados oferecem suporte a condições unidas por instruções lógicas AND (&&). Use os operadores a seguir para criar strings de critérios:

Operador Uso da CEL Sintaxe equivalente do GoogleSQL Descrição
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Corresponde a objetos com um atributo de string que começa com um prefixo específico.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Corresponde a objetos com um atributo de string que termina com um sufixo específico.
Igual a == = Corresponde a objetos com um atributo igual a um valor específico.
Diferente != != Exclui objetos com um atributo que corresponde exatamente a um valor específico.
Maior que > > Corresponde a objetos com um atributo de número inteiro ou carimbo de data/hora que exceda um limite.
Maior que ou igual a >= >= Corresponde a objetos com um atributo de número inteiro ou carimbo de data/hora igual ou maior que um limite.
Menor que < < Corresponde a objetos com um atributo de número inteiro ou carimbo de data/hora abaixo de um limite.
Menor que ou igual a <= <= Corresponde a objetos com um atributo de número inteiro ou carimbo de data/hora igual ou abaixo de um limite.
Contém name.contains("substring") STRPOS(name, "substring") != 0 Corresponde a objetos com um atributo de string que contém a substring.
Em name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Corresponde a objetos com um atributo que existe na lista fornecida.
Lógico NOT ! NOT Inverte uma regra para filtrar objetos que não correspondem às condições.
Carimbo de data/hora timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" Converte strings de data formatadas em RFC 3339 em um carimbo de data/hora. Essa função oferece suporte à precisão de microssegundos para corresponder aos padrões de tipo TIMESTAMP do BigQuery.
Existe contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Corresponde a objetos em que pelo menos um item em um atributo de tipo de registro repetido atende a uma condição específica.

Identificadores compatíveis

Ao criar expressões de filtro, é possível referenciar campos de bucket e de objeto. Os identificadores a seguir são mapeados para campos reconhecidos em esquemas de tabela do conjunto de dados do Storage Insights:

Atributos do bucket

É possível usar os campos de bucket a seguir para filtrar quais buckets são incluídos nos jobs de operações em lote de armazenamento.

Campo Tipo Descrição
name STRING O nome do bloco.
autoclass RECORD Contém metadados enabled e toggleTime.
autoclass.enabled BOOLEANO Indica se a classe automática está ativada para o bucket.
autoclass.toggleTime TIMESTAMP A hora em que a classe automática foi ativada ou desativada pela última vez.
labels REGISTRO REPETIDO Contém mapas de chave-valor padrão.
location STRING Identificador de local do bucket.
softDeletePolicy RECORD Contém retentionDurationSeconds e effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER O período de armazenamento da exclusão reversível, em segundos.
softDeletePolicy.effectiveTime TIMESTAMP A hora em que a política de exclusão reversível entrou em vigor.

Atributos de objeto

É possível usar os atributos a seguir para filtrar jobs de operações em lote de armazenamento por campos de objeto:

Campo Tipo Descrição
name STRING O nome do objeto.
contexts REGISTRO REPETIDO Contextos anexados a um objeto.
contexts.key STRING A chave de contexto personalizada.
contexts.value STRING O valor da chave de contexto personalizada.
contexts.type STRING O tipo de contexto personalizado.
contexts.createTime TIMESTAMP A hora em que a chave de contexto personalizada foi criada.
contexts.updateTime TIMESTAMP A hora em que a chave de contexto personalizada foi atualizada.
contentType STRING Categorização de conteúdo do tipo MIME.
customTime TIMESTAMP Carimbo de data/hora definido pelo usuário.
generation INTEGER Identificador de geração de objetos.
metadata REGISTRO REPETIDO Metadados personalizados.
metadata.key STRING A chave de metadados personalizada.
metadata.value STRING O valor de metadados personalizado.
metageneration INTEGER Identificador de geração de metadados.
retentionExpirationTime TIMESTAMP Hora em que a retenção de objetos expira.
securityInsights RECORD Contém insights de acesso público para o objeto.
securityInsights.publicAccessInsight RECORD Fornece o status de acessibilidade pública do objeto.
securityInsights.publicAccessInsight.readPublicAccess STRING O status de legibilidade pública do objeto. Os valores aceitos são PUBLIC, NOT_PUBLIC, UNSUPPORTED e ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Se readPublicAccess for PUBLIC, retorna a origem da permissão de leitura pública. Os valores aceitos são Object, Bucket e ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING O status de gravação pública do objeto. Os valores aceitos são PUBLIC, NOT_PUBLIC, UNSUPPORTED e ERROR.
size INTEGER Tamanho do objeto em bytes.
storageClass STRING A classe de armazenamento atribuída.
temporaryHold BOOLEANO Status de bloqueio ativo que impede a liberação.
timeCreated TIMESTAMP Relógio de registro de geração inicial.
timeStorageClassUpdated TIMESTAMP Hora em que a classe de armazenamento foi atualizada pela última vez.
updated TIMESTAMP Hora em que o objeto foi atualizado pela última vez.

Regras de formato de expressão

Para ajudar os jobs a serem executados em grande escala, o mecanismo de consulta aplica as seguintes regras de formatação:

  1. Condições de filtro: é possível unir condições de filtro apenas usando o operador lógico AND (&&). O mecanismo de consulta não oferece suporte ao operador lógico OR (||).
  2. Posicionamento de argumentos: é necessário colocar o campo de metadados de destino no lado esquerdo das funções. Por exemplo, use name.startsWith("live-") em vez de "live-".startsWith(name).
  3. Métodos de matriz: é possível chamar a macro exists diretamente em campos repetidos, como contexts.exists(...) ou metadata.exists(...).
  4. Limite de buckets: um único job de operações em lote de armazenamento pode operar em até 1.000 buckets. Se as expressões de filtro corresponderem dinamicamente a mais de 1.000 buckets no conjunto de dados, a criação do job falhará. Use campos específicos de bucket (por exemplo, filtragem de local como location == "us-central1" ou correspondência de nomes como name.startsWith("prod-")) para restringir o escopo da consulta e atender a esse limite.
  5. Limite de caracteres: os filtros de bucket e de objeto são limitados a um máximo de 150 caracteres.

Exemplos

Os exemplos a seguir mostram filtros combinados comuns que podem ser usados para segmentar recursos em todo o projeto. Especifique os snippets de filtro diretamente como flags no comando gcloud storage batch-operations jobs create:

  • Segmentar buckets específicos: aplica ações a objetos em buckets específicos: 

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

  • Verificar a classe de armazenamento e o local do bucket: aplica ações a objetos na classe de armazenamento Standard Storage em US locais: 

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

  • Filtrar por retenção de exclusão reversível: aplica ações a objetos em buckets que têm a exclusão reversível ativada por pelo menos sete dias: 

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

  • Filtrar por tamanho e extensões de objeto: encontra objetos PDF maiores que 5 KiB: 

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

  • Verificar chaves de contexto personalizadas: aplica ações a objetos que têm uma chave de contexto personalizada env: 

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

  • Corresponder a pares de chave-valor de contexto personalizados: aplica ações a objetos que têm uma chave de contexto personalizada env com um valor de prod: 

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

  • Corresponder a valores de contexto personalizados por prefixo e sufixo: aplica ações a objetos com um valor de contexto personalizado que começa com o prefixo prod e termina com o sufixo .txt: 

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

  • Identificar chaves de contexto ausentes: aplica ações a objetos que não têm uma chave de contexto personalizada env: 

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

A seguir