适用于存储批量操作的 CEL 过滤器参考

本页面介绍了在基于 Storage Insights dataset 字段为 storage batch operations 作业构建高级过滤条件时，通用表达式语言 (CEL) 的语法和支持的 操作。

您可以使用高级过滤条件来评估条件，并根据存储空间分析数据集中的字段自动执行数百万个文件的管理操作。支持的过滤条件直接对对象 元数据使用 CEL规则。

创建作业时，您可以使用 Google Cloud CLI 中的 --bucket-filters 和 --object-filters 标志，或 JSON API 中的 bucketFilters 和 objectFilters 字段来提供过滤规则。此选项无需手动查询 BigQuery、将对象列表导出到 CSV，并将清单上传回存储桶。当您使用数据集过滤条件选择对象时，存储批量操作会以所选数据集快照中的实时对象和当前对象为目标。因此，作业仅包含在快照时 softDeleteTime 和 timeDeleted 的值为 NULL 的对象。

支持的运算符和函数

高级过滤条件支持由逻辑 AND (&&) 语句联接的条件。使用以下运算符构建条件字符串：

运算符 CEL 用法 等效的 GoogleSQL 语法 说明
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") 匹配具有以特定前缀开头的字符串属性的对象。
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") 匹配具有以特定后缀结尾的字符串属性的对象。
Equals == = 匹配具有等于特定值的属性的对象。
Not equals != != 排除具有与特定值完全匹配的属性的对象。
Greater than > > 匹配具有超过阈值的整数或时间戳属性的对象。
Greater than or equal to >= >= 匹配具有等于或超过阈值的整数或时间戳属性的对象。
Less than < < 匹配具有低于阈值的整数或时间戳属性的对象。
Less than or equal to <= <= 匹配具有等于或低于阈值的整数或时间戳属性的对象。
Contains name.contains("substring") STRPOS(name, "substring") != 0 匹配具有包含子字符串的字符串属性的对象。
In name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) 匹配具有存在于所提供列表中的属性的对象。
Logical NOT ! NOT 反转规则以过滤不符合条件的对象。
时间戳 timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" 将采用 RFC 3339 格式的日期字符串转换为时间戳。此函数支持微秒精度，以符合 BigQuery 时间戳类型标准。
Exists contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) 匹配重复记录类型属性中至少一项满足特定条件的对象。

支持的标识符

构建过滤表达式时，您可以引用存储桶级字段和对象级字段。以下标识符映射到 Storage Insights 数据集表架构中的识别字段：

存储桶属性

您可以使用以下存储桶级字段来过滤哪些存储桶包含在存储批量操作作业中。

字段 类型 说明
name STRING 存储桶的名称。
autoclass RECORD 包含 enabled 和 toggleTime 元数据。
autoclass.enabled BOOLEAN 指示是否为存储桶启用了 Autoclass。
autoclass.toggleTime TIMESTAMP 上次启用或停用 Autoclass 的时间。
labels REPEATED RECORD 包含标准键值对映射。
location STRING 存储桶位置标识符。
softDeletePolicy RECORD 包含 retentionDurationSeconds 和 effectiveTime。
softDeletePolicy.retentionDurationSeconds INTEGER 软删除保留期限，以秒为单位。
softDeletePolicy.effectiveTime TIMESTAMP 软删除政策生效的时间。

对象属性

您可以使用以下属性按对象级字段过滤存储批量操作作业：

字段 类型 说明
name STRING 对象的名称。
contexts REPEATED RECORD 附加到对象的上下文。
contexts.key STRING 自定义上下文键。
contexts.value STRING 自定义上下文键的值。
contexts.type STRING 自定义上下文类型。
contexts.createTime TIMESTAMP 创建自定义上下文键的时间。
contexts.updateTime TIMESTAMP 更新自定义上下文键的时间。
contentType STRING MIME 类型内容分类。
customTime TIMESTAMP 用户定义的时间戳。
generation INTEGER 对象世代标识符。
metadata REPEATED RECORD 自定义元数据。
metadata.key STRING 自定义元数据键。
metadata.value STRING 自定义元数据值。
metageneration INTEGER 元数据世代标识符。
retentionExpirationTime TIMESTAMP 对象保留期限到期的时间。
securityInsights RECORD 包含对象的公开访问权限洞见。
securityInsights.publicAccessInsight RECORD 提供对象的公开访问权限状态。
securityInsights.publicAccessInsight.readPublicAccess STRING 对象的公开可读性状态。支持的值包括 PUBLIC、NOT_PUBLIC、UNSUPPORTED 和 ERROR。
securityInsights.publicAccessInsight.readPublicAccessSource STRING 如果 readPublicAccess 为 PUBLIC，则返回公开读取权限的来源。支持的值包括 Object、Bucket 和 ERROR。
securityInsights.publicAccessInsight.writePublicAccess STRING 对象的公开可写性状态。支持的值包括 PUBLIC、NOT_PUBLIC、UNSUPPORTED 和 ERROR。
size INTEGER 对象大小，以字节为单位。
storageClass STRING 分配的存储类别。
temporaryHold BOOLEAN 阻止发布的活跃代码块状态。
timeCreated TIMESTAMP 初始世代注册时钟。
timeStorageClassUpdated TIMESTAMP 上次更新存储类别的时间。
updated TIMESTAMP 上次更新对象的时间。

表达式格式规则

为了帮助作业大规模运行，查询引擎应用了以下格式规则：

  1. 过滤条件：您只能使用 逻辑 AND (&&) 运算符联接过滤条件。查询引擎不支持逻辑 OR (||) 运算符。
  2. 实参定位：您必须将目标元数据字段放在 函数的左侧。例如，使用 name.startsWith("live-") 而不是 "live-".startsWith(name)。
  3. 数组方法：您可以直接对重复 字段调用 exists 宏，例如 contexts.exists(...) 或 metadata.exists(...)。
  4. 存储桶限制：单个存储批量操作作业最多可以对 1,000 个存储桶执行操作。如果过滤表达式在数据集中动态匹配超过 1,000 个存储桶，则作业创建会失败。使用特定的 存储桶级字段（例如，位置过滤条件，如 location == "us-central1"；或名称匹配，如 name.startsWith("prod-")）来缩小 查询范围并满足此限制。
  5. 字符数限制：存储桶过滤条件和对象过滤条件各自最多只能包含 150 个字符。

示例

以下示例展示了可用于以项目范围内的资源为目标的常见组合过滤条件。在 gcloud storage batch-operations jobs create 命令中，将过滤条件代码段直接指定为标志：

  • 以特定存储桶为目标：对特定存储桶中的对象应用操作： 

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

  • 检查存储类别和存储桶位置：对 US 位置的标准存储类别中的对象应用操作： 

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

  • 按软删除保留期限过滤：对已启用软删除至少 7 天的存储桶中的对象应用操作：

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

  • 按对象大小和扩展名过滤：查找大于 5 KiB: 

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

  • 检查自定义上下文键：对具有自定义 上下文键 env 的对象应用操作： 

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

  • 匹配自定义上下文键值对：对具有 自定义上下文键 env 且值为 prod 的对象应用操作： 

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

  • 按前缀和后缀匹配自定义上下文值：对具有自定义上下文值（以 prod 前缀开头，以 .txt 后缀结尾）的对象应用操作： 

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

  • 识别缺失的上下文键：对没有 自定义上下文键 env 的对象应用操作： 

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

后续步骤