このページは Cloud Translation API によって翻訳されました。

オブジェクトコンテキストを使用する

このページでは、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 は、オブジェクトに付加するコンテキストキーです。例: Departmentcustom オブジェクトには複数の 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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証情報を設定するをご覧ください。


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId blobId = BlobId.of(bucketName, objectName);
      Blob blob = storage.get(blobId);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

JSON API

gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセストークンを生成できます。

オブジェクトの設定を含む JSON ファイルを作成します。この設定には、オブジェクトの contexts 構成フィールドを含める必要があります。

既存のコンテキストを追加、変更、または上書きするには、次の形式を使用します。

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

ここで

KEY は、オブジェクトに付加するコンテキストキーです。例: Departmentcustom オブジェクトには複数の Key-Value ペアを指定できます。
VALUE は、コンテキストキーに関連付ける値です。例: Human resources

既存のコンテキストをすべて削除するには、次の形式を使用します。

  {
    "contexts": {
      "custom": null
    }
  }

コンテキストから特定のキーを削除するには、次の形式を使用します。

  {
    "contexts": {
      "custom": {
        "KEY": null,
        ...
      }
    }
  }

ここで

KEY は、オブジェクトから削除するコンテキストキーです。例: Departmentcustom オブジェクトから削除する複数のキーを指定できます。

cURL を使用して、PATCH Object リクエストで 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 のリファレンスドキュメントをご覧ください。


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

JSON API

gcloud CLI をインストールして初期化します。これにより、Authorization ヘッダーのアクセストークンを生成できます。

cURL を使用して、GET Object リクエストで 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 ドキュメントをご覧ください。

オブジェクト コンテキストを使用する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

必要なロールを取得する

必要な権限

新しいオブジェクトにコンテキストを関連付ける

コマンドライン

JSON API

既存のオブジェクトにコンテキストを関連付ける、またはコンテキストを変更する

コマンドライン

クライアント ライブラリ

Java

JSON API

オブジェクト コンテキストを表示する

コマンドライン

クライアント ライブラリ

Java

JSON API

コンテキストでオブジェクトをフィルタする

オブジェクト オペレーション時にオブジェクト コンテキストを管理する

コマンドライン

JSON API

次のステップ

オブジェクトコンテキストを使用する

クライアントライブラリ

オブジェクトコンテキストを表示する

クライアントライブラリ

オブジェクトオペレーション時にオブジェクトコンテキストを管理する