儲存空間批次作業的 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 ! 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。

欄位 類型 說明
name STRING 值區名稱。
autoclass RECORD 包含 enabled 和 toggleTime 中繼資料。
autoclass.enabled BOOLEAN 指出 bucket 是否已啟用自動調整級別功能。
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. 陣列方法：您可以直接在重複欄位 (例如 contexts.exists(...) 或 metadata.exists(...)) 上呼叫 exists 巨集。
  4. 值區限制：單一儲存空間批次作業工作最多可對 1,000 個值區執行作業。如果篩選運算式在資料集中動態比對超過 1,000 個值區，工作建立作業就會失敗。使用特定 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']"

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

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

  • 依虛刪除保留時間篩選：對已啟用虛刪除功能至少 7 天的 bucket 中的物件採取行動：

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

後續步驟