儲存空間批次作業的 CEL 篩選器參考資料

本頁說明建構 儲存空間批次作業工作的高階篩選器時，根據 Storage Insights 資料集欄位使用的通用運算式語言 (CEL) 語法和支援的作業。

您可以根據儲存空間分析資料集中的欄位，使用進階篩選器評估條件，並自動管理數百萬個檔案。支援的篩選器會直接對物件中繼資料使用 CEL 規則。

使用 Google Cloud CLI 中的 --bucket-filters 和 --object-filters 旗標，或 JSON API 中的 bucketFilters 和 objectFilters 欄位，在建立工作時提供篩選規則。這樣一來，您就不必手動查詢 BigQuery、將物件清單匯出為 CSV 檔案，以及將資訊清單上傳回 bucket。使用資料集篩選器選取物件時，儲存空間批次作業會以所選資料集快照中現有且最新的物件為目標。因此，這項工作只會納入在快照時間點，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 ! NOT 反轉規則，篩選不符合條件的物件。
時間戳記 timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" 將採用 RFC 3339 格式的日期字串轉換為時間戳記。這項函式支援微秒精確度，符合 BigQuery TIMESTAMP 類型標準。
已存在 contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) 比對重複記錄類型屬性中至少有一個項目符合特定條件的物件。

支援的 ID

建構篩選運算式時，您可以參照 bucket 層級和物件層級的欄位。下列 ID 會對應至儲存空間分析資料集資料表結構定義中的已辨識欄位：

Bucket 屬性

您可以使用下列 bucket 層級的欄位，篩選要納入儲存空間批次作業工作的 bucket。

欄位 類型 說明
name STRING 值區名稱。
autoclass RECORD 包含 enabled 和 toggleTime 中繼資料。
autoclass.enabled BOOLEAN 指出 bucket 是否已啟用 Autoclass。
autoclass.toggleTime TIMESTAMP 上次啟用或停用自動調整級別的時間。
labels REPEATED RECORD 包含標準鍵/值對應。
location STRING Bucket 位置 ID。
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 物件產生 ID。
metadata REPEATED RECORD 自訂中繼資料。
metadata.key STRING 自訂中繼資料鍵。
metadata.value STRING 自訂中繼資料值。
metageneration INTEGER 中繼資料生成 ID。
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. bucket 限制：單一儲存空間批次作業工作最多可對 1,000 個 bucket 執行作業。如果篩選運算式動態比對資料集內超過 1,000 個 bucket，工作建立作業就會失敗。請使用特定的 bucket 層級欄位 (例如 location == "us-central1" 等位置篩選條件，或 name.startsWith("prod-") 等名稱比對條件)，縮小查詢範圍並符合這項限制。
  5. 字元限制：bucket 篩選器和物件篩選器的字元上限皆為 150 個。

範例

以下範例說明常見的組合篩選器，可用於指定整個專案的資源。直接在 gcloud storage batch-operations jobs create 指令中將篩選器程式碼片段指定為旗標：

  • 指定特定 bucket：對特定 bucket 中的物件套用動作： 

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

  • 檢查儲存空間級別和 bucket 位置：對 US 位置中 Standard Storage 儲存空間級別的物件套用動作：

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

  • 依虛刪除保留期限篩選：對 bucket 中的物件套用動作，這些 bucket 必須啟用虛刪除功能至少 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')"

後續步驟