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

このページでは、Cloud Storage オブジェクトに Key-Value ペアの形式でコンテキストを関連付けて管理する方法について説明します。

必要なロールを取得する

オブジェクト コンテキストの作成と管理に必要な権限を取得するには、オブジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、オブジェクト コンテキストの作成と管理に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

オブジェクト コンテキストの作成と管理には、次の権限が必要です。

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。


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

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

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

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

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

    ここで

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

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

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

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

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

    ここで

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

  3. 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.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

    ここで

    • JSON_FILE_NAME は、オブジェクト コンテキスト情報を含むファイルへのパスです。
    • BUCKET_NAME は、コンテキストを編集するオブジェクトを含むバケットの名前です。例: my-bucket
    • OBJECT_NAME は、オブジェクトの URL エンコードされた名前です。たとえば、pets/dog.pngpets%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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。


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

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

  2. cURL使用して、GET Object リクエストで JSON API を呼び出します。

    curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://storage.s3nsapis.fr/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 プロパティで、宛先オブジェクトの新しいコンテキストを指定することもできます。

次のステップ