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

本页介绍了基于 Storage Insights 数据集字段为 存储批量操作作业构建高级过滤条件时，通用表达式语言 (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") 匹配具有以特定后缀结尾的字符串属性的对象。
等于 == = 匹配具有等于特定值的属性的对象。
不等于 != != 排除属性与特定值完全匹配的对象。
大于 > > 匹配具有超过阈值的整数或时间戳属性的对象。
大于或等于 >= >= 匹配具有等于或超过阈值的整数或时间戳属性的对象。
小于 < < 匹配具有低于阈值的整数或时间戳属性的对象。
小于或等于 <= <= 匹配具有等于或低于阈值的整数或时间戳属性的对象。
包含 name.contains("substring") STRPOS(name, "substring") != 0 匹配具有包含子字符串的字符串属性的对象。
在 name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) 匹配具有所提供列表中属性的对象。
逻辑非 ! NOT 反转规则以过滤不符合条件的对象。
时间戳 timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" 将采用 RFC 3339 格式的日期字符串转换为时间戳。此函数支持微秒精度，以符合 BigQuery TIMESTAMP 类型标准。
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 时间戳 上次启用或停用 Autoclass 的时间。
labels REPEATED RECORD 包含标准键值对映射。
location STRING 存储分区位置标识符。
softDeletePolicy RECORD 包含 retentionDurationSeconds 和 effectiveTime。
softDeletePolicy.retentionDurationSeconds INTEGER 软删除保留期限（以秒为单位）。
softDeletePolicy.effectiveTime 时间戳 软删除政策生效的时间。

对象特性

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

字段 类型 说明
name STRING 对象的名称。
contexts REPEATED RECORD 附加到对象的上下文。
contexts.key STRING 自定义上下文键。
contexts.value STRING 自定义上下文键的值。
contexts.type STRING 自定义上下文类型。
contexts.createTime 时间戳 自定义上下文键的创建时间。
contexts.updateTime 时间戳 自定义情境键的更新时间。
contentType STRING MIME 类型内容分类。
customTime 时间戳 用户定义的时间戳。
generation INTEGER 对象生成标识符。
metadata REPEATED RECORD 自定义元数据。
metadata.key STRING 自定义元数据键。
metadata.value STRING 自定义元数据值。
metageneration INTEGER 元数据生成标识符。
retentionExpirationTime 时间戳 对象保留期限到期时间。
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 时间戳 初始生成注册时钟。
timeStorageClassUpdated 时间戳 上次更新存储类别的时间。
updated 时间戳 对象的上次更新时间。

表达式格式规则

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

  1. 过滤条件：您只能使用逻辑 AND (&&) 运算符联接过滤条件。查询引擎不支持逻辑 OR (||) 运算符。
  2. 实参位置：您必须将目标元数据字段放在函数的左侧。例如，使用 name.startsWith("live-") 而不是 "live-".startsWith(name)。
  3. 数组方法：您可以直接对重复字段（例如 contexts.exists(...) 或 metadata.exists(...)）调用 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 的 PDF 对象： 

    --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')"

后续步骤