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

Nesta página, descrevemos 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 do Storage com base nos 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 regras da CEL diretamente nos metadados do objeto.

Forneça regras de filtro usando as sinalizações --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 para os buckets. Quando você usa filtros de conjunto de dados para seleção de objetos, as operações em lote do Storage segmentam objetos que estão ativos e atualizados no 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 aceitam condições unidas por instruções lógicas AND (&&). Use os seguintes operadores para criar as 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 != != Excluir 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 excede um limite.
Maior que ou igual a >= >= Corresponde a objetos com um atributo de número inteiro ou carimbo de data/hora igual ou superior a 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 inferior a 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.
NOT lógico ! NOT Inverta 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" Converter strings de data formatadas em RFC 3339 em um carimbo de data/hora. Essa função é compatível com a 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 aceitos

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

Atributos de bucket

Use os campos no nível do bucket a seguir para filtrar quais buckets são incluídos nos jobs de operações em lote do Storage.

Campo Tipo Descrição
name STRING O nome do bloco.
autoclass RECORD Contém metadados de 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 do 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 O horário em que a política de exclusão reversível entrou em vigor.

Atributos de objeto

É possível usar os seguintes atributos para filtrar jobs de operações em lote do Storage por campos no nível do 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 personalizado.
contexts.value STRING O valor da chave de contexto personalizado.
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 dos metadados personalizados.
metageneration INTEGER Identificador de geração de metadados.
retentionExpirationTime TIMESTAMP Horário em que a retenção do objeto expira.
securityInsights RECORD Contém insights de acesso público para o objeto.
securityInsights.publicAccessInsight RECORD Informa o status de acessibilidade pública do objeto.
securityInsights.publicAccessInsight.readPublicAccess STRING O status de leitura pública do objeto. Os valores aceitos são PUBLIC, NOT_PUBLIC, UNSUPPORTED e ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Se readPublicAccess for PUBLIC, vai retornar a origem da permissão de leitura pública. Os valores com suporte 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 impedindo a liberação.
timeCreated TIMESTAMP Relógio de registro da 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 seus jobs a serem executados em grande escala, o mecanismo de consulta aplica as seguintes regras de formatação:

  1. Condições de filtro: só é possível mesclar condições de filtro usando o operador lógico AND (&&). O mecanismo de consulta não é compatível com o operador lógico OR (||).
  2. Posicionamento do argumento: é preciso 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 do Storage 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 vai falhar. Use campos específicos no nível do bucket (por exemplo, filtragem de local, como location == "us-central1", ou correspondência de nome, 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 cada.

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: aplique 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: aplique ações a objetos na classe de armazenamento Standard Storage em locais US: 

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

  • Filtrar por retenção de exclusão reversível: aplique ações a objetos em buckets que tenham a exclusão reversível ativada por pelo menos 7 dias: 

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

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

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

  • Verificar chaves de contexto personalizadas: aplique ações a objetos que tenham uma chave de contexto personalizada env: 

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

  • Corresponder a pares de chave-valor de contexto personalizado: aplique ações a objetos que tenham uma chave de contexto personalizado env com um valor de prod: 

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

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

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

  • Identificar chaves de contexto ausentes: aplique 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