Google Cloud StorageのObject Contextを試してみる
はじめに
データアナリティクス事業本部のkobayashiです。
本記事は クラスメソッド Google Cloud Advent Calendar 2025の10日目の投稿になります。
Google Cloud Storageでオブジェクトにキーバリューペアの付加情報を追加できるObject Contextsがプレビューになっていたので早速試してみたのでその内容をまとめます。
Cloud StorageのObject Contextsとは
Cloud Storage のObject Contextsは、オブジェクトにキーバリューペアの形式で記述的な情報を付加できる機能になります。例えば請求書ファイルにcustomer_idやpayment_statusなどのビジネス上の意味を持つコンテキスト情報を付与することができます。
Object Contextsが解決する課題
従来、GCSのオブジェクトにビジネス情報を付与する場合、以下のような方法が取られていました。
- ファイル名やパスに情報を埋め込む:
invoices/2025/customer_001/processed/invoice_001.pdfのようなパス設計 - カスタムメタデータを使用する:
x-goog-meta-*ヘッダーで情報を付与 - 外部データベースで管理する: ファイルパスとメタ情報を別システムで紐付け
これらの方法にはそれぞれ課題がありました。パス設計は後から変更が難しく、カスタムメタデータはIAMでの細かい権限制御ができません。また外部データベースはシステムが複雑になります。
Object Contextsはこれらの課題を解決し、オブジェクトに直接ビジネス情報を紐付けながら、専用のIAM権限で管理できるようになります。
Object Contextsの操作に必要な権限
Object Contextsを操作するには以下の権限が必要です。
| 操作 | 必要な権限 |
|---|---|
| 作成 | storage.objects.createContext |
| 更新 | storage.objects.updateContext |
| 削除 | storage.objects.deleteContext |
これらの権限を持つカスタムロールを作成して使用するか、適切な事前定義ロールを付与します。
Object Contextsの活用例
具体的な活用シーンをいくつか紹介します。
ETL/データパイプラインでの処理状態管理
データレイクにファイルを投入する際、処理状態をObject Contextsで管理できます。
pipeline_stage: raw → cleansed → transformed → loaded
processed_at: 2025-01-15T10:30:00Z
source_system: salesforce
これにより、どのファイルがどの段階まで処理されたかをGCS上で直接追跡でき、重複処理を防止できます。
機械学習のデータセット管理
学習データの品質管理やバージョン管理に活用できます。
dataset_version: v2.1
annotation_status: verified
quality_score: 0.95
annotator: team_a
マルチテナント環境でのデータ分離
複数の顧客データを同一バケットで管理する際、テナント情報を付与できます。
tenant_id: customer_123
data_region: jp
retention_policy: 3years
Object Contextsの利点
Object Contextsには以下の利点があります。
- データ発見: オブジェクト一覧のフィルタリングが効率化される
- 相互運用性: 事前定義不要な文字列値に対応
- データ永続性: オブジェクト操作時にコンテキストが自動継承される
- IAM統合: アクセス制御との連携が可能
では早速試してみます。
Object Contextsを試してみる
Object Contextsを操作するにはgcloud alpha storageコマンドを使用します。
alphaコマンドなので--custom-contextsのflagが見つからないとエラーが出ることがありますがその際はgcloudを最新版にアップデートしコンポーネントもupdateする必要があります。
$ gcloud components update
新規オブジェクトにObject Contextsを付与する
オブジェクトをアップロードする際に--custom-contextsオプションでキーバリューペアを指定してコンテキストを付与します。
$ gcloud alpha storage cp ./sample.csv gs://cm-kobayashi-object-contexts/ --custom-contexts=department=sales,status=active
Copying file://./sample.csv to gs://cm-kobayashi-object-contexts/sample.csv
Completed files 1/1 | 1.2kiB/1.2kiB
アップロードしたオブジェクトのコンテキストを確認してみます。
$ gcloud alpha storage objects describe gs://cm-kobayashi-object-contexts/sample.csv --format="yaml(name,contexts)"
department:
createTime: 2025-11-30T01:11:48+0000
type: CUSTOM
updateTime: 2025-11-30T01:11:48+0000
value: sales
status:
createTime: 2025-11-30T01:11:48+0000
type: CUSTOM
updateTime: 2025-11-30T01:11:48+0000
value: active
name: sample.csv
contexts.custom配下にキーバリューペアが設定されていることが確認できます。
既存オブジェクトのObject Contextsを更新する
既存のオブジェクトに対してコンテキストを追加・更新するにはgcloud alpha storage objects updateコマンドの--update-custom-contextsオプションを使用します。
$ gcloud alpha storage objects update gs://cm-kobayashi-object-contexts/sample.csv --update-custom-contexts=status=processed,reviewer=kobayashi
Patching gs://cm-kobayashi-object-contexts/sample.csv...
Completed 1
更新後のコンテキストを確認してみます。
$ gcloud alpha storage objects describe gs://cm-kobayashi-object-contexts/sample.csv --format="yaml(name,contexts)"
department:
createTime: 2025-11-30T01:11:48+0000
type: CUSTOM
updateTime: 2025-11-30T01:11:48+0000
value: sales
reviewer:
createTime: 2025-11-30T01:25:18+0000
type: CUSTOM
updateTime: 2025-11-30T01:25:18+0000
value: kobayashi
status:
createTime: 2025-11-30T01:11:48+0000
type: CUSTOM
updateTime: 2025-11-30T01:25:18+0000
value: processed
name: sample.csv
statusの値がactiveからprocessedに更新され、新しいキーreviewerが追加されていることがわかります。
Object Contextsを削除する
特定のコンテキストを削除するには--remove-custom-contextsオプションを使用します。
$ gcloud alpha storage objects update gs://cm-kobayashi-object-contexts/sample.csv --remove-custom-contexts=reviewer
Patching gs://cm-kobayashi-object-contexts/sample.csv...
Completed 1
削除後のコンテキストを確認してみます。
$ gcloud alpha storage objects describe gs://cm-kobayashi-object-contexts/sample.csv --format="yaml(name,contexts)"
department:
createTime: 2025-11-30T01:11:48+0000
type: CUSTOM
updateTime: 2025-11-30T01:11:48+0000
value: sales
status:
createTime: 2025-11-30T01:11:48+0000
type: CUSTOM
updateTime: 2025-11-30T01:25:18+0000
value: processed
name: sample.csv
reviewerキーが削除されていることがわかります。
ディレクトリ全体にObject Contextsを付与する
ディレクトリ全体をアップロードする際にもコンテキストを付与できます。gcloud alpha storage rsyncコマンドを使用します。
$ gcloud alpha storage rsync ./data_dir gs://cm-kobayashi-object-contexts/data/ --recursive --custom-contexts=batch_id=2025_Q4,source=local_upload
Copying file://./data_dir/aaa.csv to gs://cm-kobayashi-object-contexts/data/aaa.csv
Copying file://./data_dir/bbb.csv to gs://cm-kobayashi-object-contexts/data/bbb.csv
Copying file://./data_dir/ccc.csv to gs://cm-kobayashi-object-contexts/data/ccc.csv
Completed files 3/3 | 3.6kiB/3.6kiB
Average throughput: 224.0kiB/s
JSON APIでの操作
REST APIを使用してコンテキストを操作することもできます。PATCHリクエストでコンテキストを更新できます。
{
"contexts": {
"custom": {
"Department": {
"value": "HR"
},
"Priority": {
"value": "High"
}
}
}
}
Object Contextsとメタデータの違い
Cloud Storageには既存のカスタムメタデータ機能がありますが、Object Contextsは以下の点で異なります。
- 目的の違い: カスタムメタデータは技術的な情報（Content-Type、Cache-Controlなど）を補完するためのもの。Object Contextsはビジネス上の意味を持つ情報を付与するためのもの
- IAM統合: Object Contextsは専用の権限で管理され、きめ細かいアクセス制御が可能
- データ発見: Object Contextsはオブジェクト一覧のフィルタリングに活用できる
要は、「ブラウザでどう表示するか」「いつ作成されたか」 といったファイルそのものの属性を管理したい場合は メタデータ を使用し、
「どの部署のデータか」「処理済みか未処理か」 といった業務上の分類や検索を行いたい場合は コンテキスト を使用します。
まとめ
Google Cloud Storageでオブジェクトにキーバリューペアでコンテキスト情報を付与できるObject Contextsを試してみました。Object Contextsを使うことでオブジェクトにビジネス上の意味を持つ情報を付与でき、データの分類・整理やワークフロー追跡に活用できます。ぜひ試してみてください。
最後まで読んで頂いてありがとうございました。
