ストレージ バッチ オペレーションの 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 バケットのロケーション 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 オブジェクトの公開アクセスに関する 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. 配列メソッド: exists マクロは、 フィールド (例: contexts.exists(...) や metadata.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')"

次のステップ