このページでは、Storage Insights dataset フィールドに基づいて ストレージ バッチ オペレーション ジョブの詳細フィルタを作成する際の 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 | オブジェクトの公開アクセスに関する分析情報が含まれます。 |
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 | オブジェクトが最後に更新された時刻。 |
式の形式ルール
ジョブを大規模に実行できるように、クエリエンジンは次の形式ルールを適用します。
- フィルタ条件: フィルタ条件は、
論理 AND (
&&) 演算子を使用してのみ結合できます。クエリエンジンは、論理 OR（||）演算子をサポートしていません。 - 引数の位置: ターゲット メタデータ フィールドは、関数の
左側に配置する必要があります。たとえば、
"live-".startsWith(name)ではなくname.startsWith("live-")を使用します。 - 配列メソッド:
existsマクロは、 フィールド (例:contexts.exists(...)やmetadata.exists(...)) で直接呼び出すことができます。 - バケットの上限: 1 つのストレージ バッチ オペレーション ジョブで操作できるバケットは 1,000 個までです。フィルタ式がデータセット内の 1,000 個を超えるバケットに動的に一致する場合、ジョブの作成は失敗します。特定の
バケットレベルのフィールド（
location == "us-central1"などのロケーション フィルタや、name.startsWith("prod-")などの名前の一致）を使用して、クエリの範囲を絞り込み、この上限を満たします。 - 文字数制限: バケットフィルタとオブジェクト フィルタは、それぞれ 最大 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')"
次のステップ
- 詳細フィルタを使用してジョブを作成する方法を学習する。
- ストレージ バッチ オペレーション ジョブを 作成して管理する方法を学習する。