ストレージ バッチ オペレーションの CEL フィルタのリファレンス

このページでは、Storage Insights データセット フィールドに基づいて ストレージ バッチ オペレーション ジョブの高度なフィルタを作成する際の Common Expression Language（CEL）構文とサポートされているオペレーションについて説明します。

高度なフィルタを使用すると、Storage Insights データセットのフィールドに基づいて、数百万のファイルにわたる条件を評価し、管理アクションを自動化できます。サポートされているフィルタは、オブジェクト メタデータに 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 部分文字列を含む文字列属性を持つオブジェクトを照合します。
In 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) 繰り返しレコードタイプ属性内の少なくとも 1 つの項目が特定の条件を満たすオブジェクトを照合します。

サポートされている識別子

フィルタ式を作成するときに、バケットレベルのフィールドとオブジェクト レベルのフィールドの両方を参照できます。次の識別子は、Storage Insights データセット テーブル スキーマの認識されたフィールドにマッピングされます。

バケット属性

次のバケットレベルのフィールドを使用して、ストレージ バッチ オペレーション ジョブに含めるバケットをフィルタできます。

フィールド タイプ 説明
name STRING バケットの名前です。
autoclass RECORD enabled と toggleTime のメタデータが含まれます。
autoclass.enabled BOOLEAN バケットで Autoclass が有効になっているかどうかを示します。
autoclass.toggleTime TIMESTAMP Autoclass が最後に有効または無効になった時刻。
labels REPEATED RECORD 標準の Key-Value マップが含まれます。
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 オブジェクトの公開アクセスに関する Insights へのアクセスが含まれます。
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. 引数の位置: ターゲット メタデータ フィールドは関数の左側に配置する必要があります。たとえば、"live-".startsWith(name) ではなく name.startsWith("live-") を使用します。
  3. 配列メソッド: contexts.exists(...) や metadata.exists(...) などの繰り返しフィールドで exists マクロを直接呼び出すことができます。
  4. バケットの上限: 1 つのストレージ バッチ オペレーション ジョブで操作できるバケットは最大 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 ロケーションの Standard Storage ストレージ クラスのオブジェクトにアクションを適用します。

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

  • カスタム コンテキストの Key-Value ペアを照合する: 値が prod のカスタム コンテキスト キー env を持つオブジェクトにアクションを適用します。

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

次のステップ