このページでは、Cloud Storage オブジェクトに Key-Value ペアの形式でコンテキストを関連付けて管理する方法について説明します。
必要なロールを取得する
オブジェクト コンテキストの作成と管理に必要な権限を取得するには、オブジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- 
              コンテキストを使用してオブジェクトを作成する: Storage オブジェクト作成者(roles/storage.objectCreator)
- 
              オブジェクトのコンテキストの追加、更新、表示、削除: Storage オブジェクト ユーザー(roles/storage.objectUser)
- 
              オブジェクトに付加されたコンテキスト キーと値を表示する: Storage オブジェクト閲覧者(roles/storage.objectViewer)
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
これらの事前定義ロールには、オブジェクト コンテキストの作成と管理に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
オブジェクト コンテキストの作成と管理には、次の権限が必要です。
- 
                  オブジェクト コンテキストを使用したオブジェクトの作成:
                - 
                      storage.objects.create
- 
                      storage.objects.createContext
 
- 
                      
- 
                  オブジェクト コンテキストの関連付け、更新、削除:
                - 
                      storage.objects.update
- 
                      storage.objects.createContext
- 
                      storage.objects.updateContext
- 
                      storage.objects.deleteContext
 
- 
                      
- 
                  オブジェクト コンテキストの表示:
                - 
                      storage.objects.get
- 
                      storage.objects.list
 
- 
                      
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
新しいオブジェクトにコンテキストを関連付ける
新しいオブジェクトを Cloud Storage バケットにアップロードするときに、オブジェクトにコンテキストを関連付けます。各コンテキストはキーと値で構成されます。
コマンドライン
gcloud alpha storage cp コマンドでオブジェクトをアップロードするときにコンテキストを関連付けるには、--custom-contexts フラグを使用します。
gcloud alpha storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...
ここで
- OBJECT_LOCATIONは、オブジェクトへのローカルパスです。たとえば- Desktop/dog.pngです。
- DESTINATION_BUCKET_NAMEは、オブジェクトをアップロードするバケットの名前です。例:- my-bucket
- KEYは、オブジェクトに付加するコンテキスト キーです。例:- Department複数の Key-Value ペアをカンマ区切りで指定できます。
- VALUEは、コンテキスト キーに関連付ける値です。例:- Human resources
または、オブジェクトに付加するコンテキストを含む JSON ファイルを作成し、--custom-contexts-file フラグを使用します。
{ "KEY": { "value": "VALUE" }, ... }
ここで
- KEYは、オブジェクトに付加するコンテキスト キーです。例:- Department複数の Key-Value ペアを指定できます。
- VALUEは、コンテキスト キーに関連付ける値です。例:- Human resources
gcloud alpha storage rsync コマンドでディレクトリをアップロードするときにコンテキストを関連付けるには、--custom-contexts フラグまたは --custom-contexts-file フラグを使用します。
gcloud alpha storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...
ここで
- DIRECTORY_LOCATIONは、ディレクトリへのローカルパスです。例:- ~/my_directory
- DESTINATION_BUCKET_NAMEは、ディレクトリをアップロードするバケットの名前です。例:- my-bucket
- KEYは、オブジェクトに関連付けるコンテキスト キーです。例:- Department複数の Key-Value ペアをカンマ区切りで指定できます。
- VALUEは、コンテキスト キーに関連付ける値です。例:- Human resources
JSON API
新しいオブジェクトをアップロードするときにコンテキストをオブジェクトに関連付けるには、次のいずれかの方法を使用します。
JSON 形式のオブジェクト メタデータの一部として、contexts フィールドを含めます。
{ "contexts": { "custom": { "KEY": { "value": "VALUE" }, ... } } }
ここで
- KEYは、オブジェクトに付加するコンテキスト キーです。例:- Department- customオブジェクトには複数の Key-Value ペアを指定できます。
- VALUEは、コンテキスト キーに関連付ける値です。例:- Human resources
既存のオブジェクトにコンテキストを関連付ける、またはコンテキストを変更する
Cloud Storage バケット内の既存のオブジェクトに新しいコンテキストを関連付けることができます。
コマンドライン
gcloud alpha storage objects update コマンドを使用します。
gcloud alpha storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG
ここで
- BUCKET_NAMEは、コンテキストを編集するオブジェクトを含むバケットの名前です。例:- my-bucket
- OBJECT_NAMEはオブジェクトの名前です。例:- pets/dog.png
- CUSTOM_CONTEXTS_FLAGは、次のいずれかのフラグです。- 既存のコンテキストをすべて置き換えるには、 - --custom-contexts=KEY=VALUE,...または- --custom-contexts-file=CUSTOM_CONTEXTS_FILEを使用します。- ここで - KEYは、オブジェクトに付加するコンテキスト キーです。例:- Department複数の Key-Value ペアをカンマ区切りで指定できます。
- VALUEは、コンテキスト キーに関連付ける値です。例:- Human resources
- CUSTOM_CONTEXTS_FILEは、オブジェクトにアタッチするコンテキストを含む JSON ファイルまたは YAML ファイルのパスです。
 
- 既存のコンテキストをすべて削除するには、 - --clear-custom-contextsを使用します。
- 個々のコンテキストを追加、変更、削除するには、 - --update-custom-contexts=KEY=VALUE,...と- --remove-custom-contexts=KEY,...を組み合わせて使用します。- ここで - KEYは、オブジェクトに付加するコンテキスト キー、またはオブジェクトから削除するコンテキスト キーです。例:- Department
- VALUEは、オブジェクトに関連付けるコンテキスト キーに関連付ける値です。例:- Human resources
 
 
成功した場合は、次の例のようなレスポンスになります。
Patching gs://my-bucket/pets/dog.png#1560574162144861... Completed 1
クライアント ライブラリ
Java
詳細については、Cloud Storage Java API のリファレンス ドキュメントをご覧ください。
Cloud Storage に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
JSON API
- gcloud CLI のインストールと初期化を行います。これにより、 - Authorizationヘッダーのアクセス トークンを生成できます。
- オブジェクトの設定を含む JSON ファイルを作成します。この設定には、オブジェクトの - contexts構成フィールドを含める必要があります。- 既存のコンテキストを追加、変更、または上書きするには、次の形式を使用します。 - { "contexts": { "custom": { "KEY": { "value": "VALUE" }, ... } } } - ここで - KEYは、オブジェクトに付加するコンテキスト キーです。例:- Department- customオブジェクトには複数の Key-Value ペアを指定できます。
- VALUEは、コンテキスト キーに関連付ける値です。例:- Human resources
 - 既存のコンテキストをすべて削除するには、次の形式を使用します。 - { "contexts": { "custom": null } } - コンテキストから特定のキーを削除するには、次の形式を使用します。 - { "contexts": { "custom": { "KEY": null, ... } } } - ここで - KEYは、オブジェクトから削除するコンテキスト キーです。例:- Department- customオブジェクトから削除する複数のキーを指定できます。
- cURLを使用して、- PATCHObject リクエストで JSON API を呼び出します。- curl -X PATCH --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME" - ここで - JSON_FILE_NAMEは、オブジェクト コンテキスト情報を含むファイルへのパスです。
- BUCKET_NAMEは、コンテキストを編集するオブジェクトを含むバケットの名前です。例:- my-bucket
- OBJECT_NAMEは、オブジェクトの URL エンコードされた名前です。たとえば、- pets/dog.pngは- pets%2Fdog.pngとして URL エンコードされます。
 
または、オブジェクトのコンテキストを PUT Object リクエストで置き換えることもできます。PUT Object リクエストは、他のオブジェクト メタデータも置き換えます。そのため、PUT Object リクエストの使用はおすすめしません。
オブジェクト コンテキストを表示する
オブジェクトのコンテキストを表示するには、オブジェクトのメタデータを一覧表示するか、特定のオブジェクトを記述します。
コマンドライン
gcloud alpha storage objects describe コマンドを使用します。
gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME
ここで
- BUCKET_NAMEは、コンテキストを表示するオブジェクトが含まれるバケットの名前です。例:- my-bucket
- OBJECT_NAMEは、コンテキストを表示するオブジェクトの名前です。例:- pets/dog.png
正常に終了すると、レスポンスは次の例のようになります。
bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt
クライアント ライブラリ
Java
詳細については、Cloud Storage Java API のリファレンス ドキュメントをご覧ください。
Cloud Storage に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
JSON API
- gcloud CLI をインストールして初期化します。これにより、 - Authorizationヘッダーのアクセス トークンを生成できます。
- cURLを使用して、- GETObject リクエストで JSON API を呼び出します。- curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME" - ここで - BUCKET_NAMEは、コンテキストを表示するオブジェクトが含まれるバケットの名前です。例:- my-bucket
- OBJECT_NAMEは、コンテキストを表示するオブジェクトの URL エンコード名です。たとえば、- pets%2Fdog.pngと URL エンコードした- pets/dog.pngです。
 - 正常に終了すると、レスポンスは次の例のようになります。 - { "kind": "storage#object", "name": "employees.txt", "bucket": "my-bucket", "contexts": { "custom": { "Department": { "value": "HR", "createTime": "2023-01-01T00:00:00.000Z", "updateTime": "2023-01-01T00:00:00.000Z" }, "DataClassification": { "value": "Confidential", "createTime": "2023-01-01T00:00:00.000Z", "updateTime": "2023-01-01T00:00:00.000Z" } } } } 
コンテキストでオブジェクトをフィルタする
オブジェクト コンテキスト キーの存在またはその特定の値でオブジェクトをフィルタします。コンテキストでオブジェクトをフィルタすると、特定のオブジェクト グループを効率的に見つけて管理できます。詳細については、コンテキストでオブジェクトをフィルタするをご覧ください。
オブジェクト オペレーション時にオブジェクト コンテキストを管理する
オブジェクトをコピー、書き換え、作成、移動、復元すると、オブジェクト コンテキストはデフォルトで保持されます。コピー、書き換え、作成のオペレーション中にコンテキストを変更することもできます。
コマンドライン
gcloud alpha storage cp コマンド、gcloud alpha storage rsync コマンド、gcloud alpha storage mv コマンドは、デフォルトでソース オブジェクトのコンテキストを保持します。これらのオペレーション中にコンテキストを変更するには、次のいずれかのフラグを使用します。
- 宛先オブジェクトの新しいコンテキストを設定する --custom-contextsまたは--custom-contexts-fileフラグ。
- ソース オブジェクトのコンテキストが宛先オブジェクトに付加されないようにする --clear-custom-contextsフラグ。
- --update-custom-contextsフラグと- --remove-custom-contextsフラグの組み合わせ。ソース オブジェクトの個々のコンテキストを変更してから、宛先オブジェクトにアタッチします。
gcloud alpha storage objects compose コマンドは、デフォルトでソース オブジェクトのコンテキストをマージして、宛先オブジェクトに付加します。Cloud Storage は、後で処理されたソース オブジェクトのコンテキストを優先することで、競合を解決します。作成オペレーション中のオブジェクト コンテキストの動作について詳しくは、複合オブジェクト コンテキストをご覧ください。--custom-contexts フラグまたは --custom-contexts-file フラグを使用して、宛先オブジェクトの新しいコンテキストを指定することもできます。
JSON API
- コピーまたは書き換えのオブジェクト オペレーション中にコンテキストを変更するには、リクエストの本文に - contexts.customプロパティを含めます。このプロパティを含めない場合、ソース オブジェクトのコンテキストはデフォルトで保持されます。
- オブジェクトを作成すると、デフォルトでソース オブジェクトのコンテキストが宛先オブジェクトにマージされます。Cloud Storage は、後で処理されたソース オブジェクトのコンテキストを優先することで、競合を解決します。作成オペレーション中のオブジェクト コンテキストの動作について詳しくは、複合オブジェクト コンテキストをご覧ください。 - destination.contexts.customプロパティで、宛先オブジェクトの新しいコンテキストを指定することもできます。
次のステップ
- オブジェクト コンテキスト プロパティについては、Cloud Storage API ドキュメントをご覧ください。