オブジェクト保持構成の有効化と使用

このページでは、オブジェクト保持ロック機能の使用方法（バケットで有効にしたり、バケット内のオブジェクトの保持構成を設定する方法）について説明します。

必要なロール

バケットでオブジェクト保持ロック機能を有効にしてオブジェクトの保持構成を設定するために必要な権限を取得するには、バケットまたはバケットを含むプロジェクトに対するストレージ管理者（roles/storage.admin）IAM ロールを付与するよう管理者に依頼してください。この事前定義ロールには、保持構成の設定と管理に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

storage.buckets.create
storage.buckets.enableObjectRetention
storage.buckets.get
storage.buckets.list
- この権限は、Google Cloud コンソールを使用してこのページの手順を実施する場合にのみ必要です。
storage.objects.get
storage.objects.list
- この権限は、Google Cloud コンソールを使用してこのページの手順を実施する場合にのみ必要です。
storage.objects.overrideUnlockedRetention
- この権限は、既存の保持構成をロックまたは短縮する場合にのみ必要です。
storage.objects.setRetention
storage.objects.update

カスタムロールを使用して、これらの権限を取得することもできます。

バケットのロールの付与については、バケットで IAM を使用するをご覧ください。プロジェクトに対するロールの付与については、プロジェクトへのアクセス権を管理するをご覧ください。

バケットのオブジェクト保持を有効にする

オブジェクト保持の有効化はバケットの作成の一部としてのみサポートされています。バケットでオブジェクト保持が有効になっている場合、オブジェクト保持を無効にすることはできません。バケットのオブジェクト保持を有効にするには、次の操作を行います。

コンソール

通常どおりにバケットを作成し、[オブジェクトデータを保護する方法を選択する] ステップで [保持（コンプライアンス用）] を選択して、[オブジェクト保持を有効にする] を選択します。

コマンドライン

通常どおりにバケットを作成し、コマンドに --enable-per-object-retention フラグを含めます。

クライアントライブラリ

C++

詳細については、Cloud Storage C++ API のリファレンスドキュメントをご覧ください。

Cloud Storage に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

//! [create-bucket-with-object-retention]
namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& project_id) {
  auto bucket = client.CreateBucket(bucket_name, gcs::BucketMetadata{},
                                    gcs::EnableObjectRetention(true),
                                    gcs::OverrideDefaultProject(project_id));
  if (!bucket) throw std::move(bucket).status();

  if (!bucket->has_object_retention()) {
    throw std::runtime_error("missing object retention in new bucket");
  }
  std::cout << "Successfully created bucket " << bucket_name
            << " with object retention: " << bucket->object_retention()
            << "\n";
}
//! [create-bucket-with-object-retention]

C#

詳細については、Cloud Storage C# API のリファレンスドキュメントをご覧ください。


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreateBucketWithObjectRetentionSample
{
    public Bucket CreateBucketWithObjectRetention(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.CreateBucket(projectId, bucketName, new CreateBucketOptions
        {
            ObjectRetentionEnabled = true
        });
        Console.WriteLine($"Created {bucketName}, with Object Retention enabled.");
        return bucket;
    }
}

Java

詳細については、Cloud Storage Java API のリファレンスドキュメントをご覧ください。


import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class CreateBucketWithObjectRetention {
  public static void createBucketWithObjectRetention(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

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

    Bucket bucket =
        storage.create(
            BucketInfo.of(bucketName), Storage.BucketTargetOption.enableObjectRetention(true));

    System.out.println(
        "Created bucket "
            + bucket.getName()
            + " with object retention enabled setting: "
            + bucket.getObjectRetention().getMode().toString());
  }
}

Node.js

詳細については、Cloud Storage Node.js API のリファレンスドキュメントをご覧ください。

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithObjectRetention() {
  const [bucket] = await storage.createBucket(bucketName, {
    enableObjectRetention: true,
  });

  console.log(
    `Created '${bucket.name}' with object retention enabled setting: ${bucket.metadata.objectRetention.mode}`
  );
}

createBucketWithObjectRetention().catch(console.error);

PHP

詳細については、Cloud Storage PHP API のリファレンスドキュメントをご覧ください。

use Google\Cloud\Storage\StorageClient;

/**
 * Create a Cloud Storage bucket with the object retention enabled.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_with_object_retention(string $bucketName): void
{
    $storage = new StorageClient();

    $bucket = $storage->createBucket($bucketName, [
        'enableObjectRetention' => true
    ]);
    printf(
        'Created bucket %s with object retention enabled setting: %s' . PHP_EOL,
        $bucketName,
        $bucket->info()['objectRetention']['mode']
    );
}

Python

詳細については、Cloud Storage Python API のリファレンスドキュメントをご覧ください。

from google.cloud import storage


def create_bucket_object_retention(bucket_name):
    """Creates a bucket with object retention enabled."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.create_bucket(bucket_name, enable_object_retention=True)

    print(f"Created bucket {bucket_name} with object retention enabled setting: {bucket.object_retention_mode}")

REST API

JSON API

通常どおりにバケットを作成し、リクエストの一部としてクエリパラメータ enableObjectRetention=true を含めます。

XML API

通常どおりにバケットを作成し、リクエストの一部としてヘッダー x-goog-bucket-object-lock-enabled: True を含めます。

バケットのオブジェクト保持ステータスを表示する

バケットでオブジェクト保持が有効になっているかどうかを確認するには:

コンソール

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
ステータスを確認するバケットの名前をクリックします。
[保護] タブをクリックします。
バケットのオブジェクト保持ステータスが [オブジェクト保持] セクションに表示されます。

コマンドライン

gcloud storage buckets describe コマンドを使用し、--format フラグを指定します。

gcloud storage buckets describe gs://BUCKET_NAME --format="default(per_object_retention)"

ここで、BUCKET_NAME は、保持ポリシーを表示するバケットの名前です。例: my-bucket

処理に成功し、バケットに保持ポリシーが存在する場合、レスポンスは次のようになります。

per_object_retention:
  mode: Enabled

処理に成功し、バケットに保持ポリシーが存在しない場合、レスポンスは次のようになります。

null

クライアントライブラリ

C++

詳細については、Cloud Storage C++ API のリファレンスドキュメントをご覧ください。

バケットのオブジェクト保持構成を表示するには、バケットのメタデータを表示する手順に沿って、レスポンスでオブジェクト保持フィールドを探します。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.GetBucketMetadata(bucket_name);
  if (!bucket_metadata) throw std::move(bucket_metadata).status();

  std::cout << "The metadata for bucket " << bucket_metadata->name() << " is "
            << *bucket_metadata << "\n";
}

C#

詳細については、Cloud Storage C# API のリファレンスドキュメントをご覧ください。


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class GetBucketMetadataSample
{
    public Bucket GetBucketMetadata(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{bucket.Name}");
        Console.WriteLine($"Acl:\t{bucket.Acl}");
        Console.WriteLine($"Billing:\t{bucket.Billing}");
        Console.WriteLine($"Cors:\t{bucket.Cors}");
        Console.WriteLine($"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}");
        Console.WriteLine($"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}");
        Console.WriteLine($"Encryption:\t{bucket.Encryption}");
        if (bucket.Encryption != null)
        {
            Console.WriteLine($"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}");
        }
        Console.WriteLine($"Id:\t{bucket.Id}");
        Console.WriteLine($"Kind:\t{bucket.Kind}");
        Console.WriteLine($"Lifecycle:\t{bucket.Lifecycle}");
        Console.WriteLine($"Location:\t{bucket.Location}");
        Console.WriteLine($"LocationType:\t{bucket.LocationType}");
        Console.WriteLine($"Logging:\t{bucket.Logging}");
        Console.WriteLine($"Metageneration:\t{bucket.Metageneration}");
        Console.WriteLine($"ObjectRetention:\t{bucket.ObjectRetention}");
        Console.WriteLine($"Owner:\t{bucket.Owner}");
        Console.WriteLine($"ProjectNumber:\t{bucket.ProjectNumber}");
        Console.WriteLine($"RetentionPolicy:\t{bucket.RetentionPolicy}");
        Console.WriteLine($"SelfLink:\t{bucket.SelfLink}");
        Console.WriteLine($"StorageClass:\t{bucket.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{bucket.TimeCreated}");
        Console.WriteLine($"Updated:\t{bucket.Updated}");
        Console.WriteLine($"Versioning:\t{bucket.Versioning}");
        Console.WriteLine($"Website:\t{bucket.Website}");
        Console.WriteLine($"TurboReplication:\t{bucket.Rpo}");
        if (bucket.Labels != null)
        {
            Console.WriteLine("Labels:");
            foreach (var label in bucket.Labels)
            {
                Console.WriteLine($"{label.Key}:\t{label.Value}");
            }
        }
        return bucket;
    }
}

Java

詳細については、Cloud Storage Java API のリファレンスドキュメントをご覧ください。


import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetBucketMetadata {
  public static void getBucketMetadata(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

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

    // Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
    Bucket bucket =
        storage.get(bucketName, Storage.BucketGetOption.fields(Storage.BucketField.values()));

    // Print bucket metadata
    System.out.println("BucketName: " + bucket.getName());
    System.out.println("DefaultEventBasedHold: " + bucket.getDefaultEventBasedHold());
    System.out.println("DefaultKmsKeyName: " + bucket.getDefaultKmsKeyName());
    System.out.println("Id: " + bucket.getGeneratedId());
    System.out.println("IndexPage: " + bucket.getIndexPage());
    System.out.println("Location: " + bucket.getLocation());
    System.out.println("LocationType: " + bucket.getLocationType());
    System.out.println("Metageneration: " + bucket.getMetageneration());
    System.out.println("NotFoundPage: " + bucket.getNotFoundPage());
    System.out.println("RetentionEffectiveTime: " + bucket.getRetentionEffectiveTime());
    System.out.println("RetentionPeriod: " + bucket.getRetentionPeriod());
    System.out.println("RetentionPolicyIsLocked: " + bucket.retentionPolicyIsLocked());
    System.out.println("RequesterPays: " + bucket.requesterPays());
    System.out.println("SelfLink: " + bucket.getSelfLink());
    System.out.println("StorageClass: " + bucket.getStorageClass().name());
    System.out.println("TimeCreated: " + bucket.getCreateTime());
    System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
    System.out.println("ObjectRetention: " + bucket.getObjectRetention());
    if (bucket.getLabels() != null) {
      System.out.println("\n\n\nLabels:");
      for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {
        System.out.println(label.getKey() + "=" + label.getValue());
      }
    }
    if (bucket.getLifecycleRules() != null) {
      System.out.println("\n\n\nLifecycle Rules:");
      for (BucketInfo.LifecycleRule rule : bucket.getLifecycleRules()) {
        System.out.println(rule);
      }
    }
  }
}

Node.js

詳細については、Cloud Storage Node.js API のリファレンスドキュメントをご覧ください。

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function getBucketMetadata() {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // Get Bucket Metadata
  const [metadata] = await storage.bucket(bucketName).getMetadata();

  console.log(JSON.stringify(metadata, null, 2));
}

PHP

詳細については、Cloud Storage PHP API のリファレンスドキュメントをご覧ください。

use Google\Cloud\Storage\StorageClient;

/**
 * Get bucket metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function get_bucket_metadata(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $info = $bucket->info();

    printf('Bucket Metadata: %s' . PHP_EOL, print_r($info));
}

Python

詳細については、Cloud Storage Python API のリファレンスドキュメントをご覧ください。


from google.cloud import storage


def bucket_metadata(bucket_name):
    """Prints out a bucket's metadata."""
    # bucket_name = 'your-bucket-name'

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    print(f"ID: {bucket.id}")
    print(f"Name: {bucket.name}")
    print(f"Storage Class: {bucket.storage_class}")
    print(f"Location: {bucket.location}")
    print(f"Location Type: {bucket.location_type}")
    print(f"Cors: {bucket.cors}")
    print(f"Default Event Based Hold: {bucket.default_event_based_hold}")
    print(f"Default KMS Key Name: {bucket.default_kms_key_name}")
    print(f"Metageneration: {bucket.metageneration}")
    print(
        f"Public Access Prevention: {bucket.iam_configuration.public_access_prevention}"
    )
    print(f"Retention Effective Time: {bucket.retention_policy_effective_time}")
    print(f"Retention Period: {bucket.retention_period}")
    print(f"Retention Policy Locked: {bucket.retention_policy_locked}")
    print(f"Object Retention Mode: {bucket.object_retention_mode}")
    print(f"Requester Pays: {bucket.requester_pays}")
    print(f"Self Link: {bucket.self_link}")
    print(f"Time Created: {bucket.time_created}")
    print(f"Versioning Enabled: {bucket.versioning_enabled}")
    print(f"Labels: {bucket.labels}")

REST API

JSON API

Authorization ヘッダーのアクセストークンを生成するには、gcloud CLI のインストールと初期化を行います。

OAuth 2.0 Playground を使用してアクセストークンを作成し、Authorization ヘッダーに含めることもできます。
cURL を使用して、objectRetention フィールドを含む GET Bucket リクエストで JSON API を呼び出します。
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=objectRetention"
```
BUCKET_NAME は、該当するバケットの名前です。例: my-bucket

XML API

Authorization ヘッダーのアクセストークンを生成するには、gcloud CLI のインストールと初期化を行います。

OAuth 2.0 Playground を使用してアクセストークンを作成し、Authorization ヘッダーに含めることもできます。
cURL を使用して、?object-lock をスコープとする GET バケットリクエストで XML API を呼び出します。
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?object-lock"
```
BUCKET_NAME は、該当するバケットの名前です。例: my-bucket

オブジェクトの保持構成を設定する

オブジェクトの保持構成を設定するには、オブジェクト保持が有効になっているバケットにオブジェクトが保存されている必要があります。オブジェクトの保持構成を設定するには:

コンソール

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、保持構成を設定または変更するオブジェクトを含むバケットの名前をクリックします。

[バケットの詳細] ページが開き、[オブジェクト] タブが選択されています。
フォルダ内にあるオブジェクトに移動します。
オブジェクトの名前をクリックします。

[オブジェクトの詳細] ページが開き、オブジェクトのメタデータが表示されます。
[保護] セクションで、[オブジェクト保持構成から] の編集アイコン（）をクリックします。

[保持を編集] ペインが開きます。
[オブジェクト保持構成] セクションで、[有効] または [無効] をクリックします。
1. 保持構成が有効になっている場合は、[保持期限] セクションで構成の日時を選択し、[保持モード] セクションで [未ロック] または [ロック中] をクリックします。
[確認] をクリックします。

コマンドライン

適切なフラグを指定して、gcloud storage objects update コマンドを使用します。保持構成を追加または変更するには、次のコマンドを使用します。既存の構成をロックするか、保持期間を短縮するように既存の構成を変更する場合は、--override-unlocked-retention フラグも追加する必要があります。

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --retain-until=DATETIME --retention-mode=STATE

ここで

BUCKET_NAME は、関連するバケットの名前です。例: my-bucket
OBJECT_NAME は、該当するオブジェクトの名前です。例: kitten.png
DATETIME は、オブジェクトを削除できる最も早い日時です。例: 2028-02-15T05:30:00Z
STATE は Locked か Unlocked のどちらかです。

正常に終了すると、レスポンスは次の例のようになります。

Updating gs://my-bucket/kitten.png...
  Completed 1

オブジェクトから保持構成を削除するには、次のコマンドを使用します。

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --clear-retention --override-unlocked-retention

ここで

BUCKET_NAME は、関連するバケットの名前です。例: my-bucket
OBJECT_NAME は、該当するオブジェクトの名前です。例: kitten.png

クライアントライブラリ

C++

詳細については、Cloud Storage C++ API のリファレンスドキュメントをご覧ください。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  auto original = client.GetObjectMetadata(bucket_name, object_name);
  if (!original) throw std::move(original).status();

  auto const until =
      std::chrono::system_clock::now() + std::chrono::hours(24);
  auto updated = client.PatchObject(
      bucket_name, object_name,
      gcs::ObjectMetadataPatchBuilder().SetRetention(
          gcs::ObjectRetention{gcs::ObjectRetentionUnlocked(), until}),
      gcs::OverrideUnlockedRetention(true),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!updated) throw std::move(updated).status();

  std::cout << "Successfully updated object retention configuration: "
            << *updated << "\n";
}

C#

詳細については、Cloud Storage C# API のリファレンスドキュメントをご覧ください。


using Google.Cloud.Storage.V1;
using System;
using Object = Google.Apis.Storage.v1.Data.Object;

public class SetObjectRetentionPolicySample
{
    public Google.Apis.Storage.v1.Data.Object SetObjectRetentionPolicy(
        string bucketName = "your-unique-bucket-name", // A bucket that has object retention enabled
        string objectName = "your-object-name") // An object that does not have a retention policy set
    {
        var storage = StorageClient.Create();
        var file = storage.GetObject(bucketName, objectName);


        file.Retention = new Object.RetentionData
        {
            Mode = "Unlocked", RetainUntilTimeDateTimeOffset = DateTimeOffset.UtcNow.AddDays(10)
        };

        file = storage.UpdateObject(file);

        Console.WriteLine($"The retention policy for object {objectName} was set to:");
        Console.WriteLine("Mode: " + file.Retention.Mode);
        Console.WriteLine("RetainUntilTime: " + file.Retention.RetainUntilTimeDateTimeOffset.ToString());

        // To modify an existing policy on an Unlocked object, pass in the override parameter
        file.Retention = new Object.RetentionData
        {
            Mode = "Unlocked", RetainUntilTimeDateTimeOffset = DateTimeOffset.UtcNow.AddDays(9)
        };

        file = storage.UpdateObject(file, new UpdateObjectOptions { OverrideUnlockedRetention = true });

        Console.WriteLine($"The retention policy for object {objectName} was updated to:");
        Console.WriteLine("Mode: " + file.Retention.Mode);
        Console.WriteLine("RetainUntilTime: " + file.Retention.RetainUntilTimeDateTimeOffset.ToString());

        return file;
    }
}

Java

詳細については、Cloud Storage Java API のリファレンスドキュメントをご覧ください。


import static java.time.OffsetDateTime.now;

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo.Retention;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageException;
import com.google.cloud.storage.StorageOptions;

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

    // The ID of your GCS bucket that has object retention enabled
    // String bucketName = "your-unique-bucket-name";

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

    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;
    }

    Blob updated =
        blob.toBuilder()
            .setRetention(
                Retention.newBuilder()
                    .setMode(Retention.Mode.UNLOCKED)
                    .setRetainUntilTime(now().plusDays(10))
                    .build())
            .build()
            .update();

    System.out.println("Retention policy for object " + objectName + " was set to:");
    System.out.println(updated.getRetention().toString());

    // To modify an existing policy on an Unlocked object, pass in the override parameter
    blob.toBuilder()
        .setRetention(
            updated.getRetention().toBuilder().setRetainUntilTime(now().plusDays(9)).build())
        .build()
        .update(Storage.BlobTargetOption.overrideUnlockedRetention(true));

    System.out.println("Retention policy for object " + objectName + " was updated to:");
    System.out.println(storage.get(blobId).getRetention().toString());
  }
}

Node.js

詳細については、Cloud Storage Node.js API のリファレンスドキュメントをご覧ください。

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The new ID for your GCS file
// const destFileName = 'your-new-file-name';

// The content to be uploaded in the GCS file
// const contents = 'your file content';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function setObjectRetentionPolicy() {
  // Get a reference to the bucket
  const myBucket = storage.bucket(bucketName);

  // Create a reference to a file object
  const file = myBucket.file(destFileName);

  // Save the file data
  await file.save(contents);

  // Set the retention policy for the file
  const retentionDate = new Date();
  retentionDate.setDate(retentionDate.getDate() + 10);
  const [metadata] = await file.setMetadata({
    retention: {
      mode: 'Unlocked',
      retainUntilTime: retentionDate.toISOString(),
    },
  });

  console.log(
    `Retention policy for file ${file.name} was set to: ${metadata.retention.mode}`
  );

  // To modify an existing policy on an unlocked file object, pass in the override parameter
  const newRetentionDate = new Date();
  retentionDate.setDate(retentionDate.getDate() + 9);
  [metdata] = await file.setMetadata({
    retention: {retainUntilTime: newRetentionDate},
    overrideUnlockedRetention: true,
  });

  console.log(
    `Retention policy for file ${file.name} was updated to: ${metadata.retention.retainUntilTime}`
  );
}

setObjectRetentionPolicy().catch(console.error);

PHP

詳細については、Cloud Storage PHP API のリファレンスドキュメントをご覧ください。

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a bucket's retention policy.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function set_object_retention_policy(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $expires = (new \DateTime)->add(
        \DateInterval::createFromDateString('+10 days')
    );
    // To modify an existing policy on an Unlocked object, pass the override parameter
    $object->update([
        'retention' => [
            'mode' => 'Unlocked',
            'retainUntilTime' => $expires->format(\DateTime::RFC3339)
        ],
        'overrideUnlockedRetention' => true
    ]);
    printf(
        'Retention policy for object %s was updated to: %s' . PHP_EOL,
        $objectName,
        $object->info()['retention']['retainUntilTime']
    );
}

Python

詳細については、Cloud Storage Python API のリファレンスドキュメントをご覧ください。

from google.cloud import storage


def set_object_retention_policy(bucket_name, contents, destination_blob_name):
    """Set the object retention policy of a file."""

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The contents to upload to the file
    # contents = "these are my contents"

    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)
    blob.upload_from_string(contents)

    # Set the retention policy for the file.
    blob.retention.mode = "Unlocked"
    retention_date = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=10)
    blob.retention.retain_until_time = retention_date
    blob.patch()
    print(
        f"Retention policy for file {destination_blob_name} was set to: {blob.retention.mode}."
    )

    # To modify an existing policy on an unlocked file object, pass in the override parameter.
    new_retention_date = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=9)
    blob.retention.retain_until_time = new_retention_date
    blob.patch(override_unlocked_retention=True)
    print(
        f"Retention policy for file {destination_blob_name} was updated to: {blob.retention.retain_until_time}."
    )

REST API

JSON API

Authorization ヘッダーのアクセストークンを生成するには、gcloud CLI のインストールと初期化を行います。

OAuth 2.0 Playground を使用してアクセストークンを作成し、Authorization ヘッダーに含めることもできます。
次の情報が含まれる JSON ファイルを作成します。
```
{
  "retention": {
    "mode": STATE,
    "retainUntilTime": "DATETIME"
  }
}
```
ここで
- STATE は Locked か Unlocked のどちらかです。
- DATETIME は、オブジェクトを削除できる最も早い日時です。例: 2028-02-15T05:30:00Z
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?overrideUnlockedRetention=BOOLEAN"
```
ここで
- JSON_FILE_NAME は、手順 2 で作成したファイルのパスです。
- BUCKET_NAME は、関連するバケットの名前です。例: my-bucket
- OBJECT_NAME は、関連するオブジェクトの URL エンコードされた名前です。例: pets%2Fkitten.png として URL エンコードされている pets/kitten.png
- リクエストで既存の保持構成を短縮、削除、またはロックする場合は、BOOLEAN を true にする必要があります。それ以外の場合は、リクエストから overrideUnlockedRetention パラメータを完全に除外できます。

XML API

Authorization ヘッダーのアクセストークンを生成するには、gcloud CLI のインストールと初期化を行います。

OAuth 2.0 Playground を使用してアクセストークンを作成し、Authorization ヘッダーに含めることもできます。
次の情報が含まれる XML ファイルを作成します。
```
<Retention>
  <Mode>
    STATE
  </Mode>
  <RetainUntilDate>
    DATETIME
  </RetainUntilDate>
</Retention>
```
ここで
- STATE は GOVERNANCE か COMPLIANCE のどちらかです。
- DATETIME は、オブジェクトを削除できる最も早い日時です。例: 2028-02-15T05:30:00Z
cURL を使用して、?retention をスコープとする PUT Object リクエストで XML API を呼び出します。
```
curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-bypass-governance-retention: BOOLEAN" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"
```
ここで
- XML_FILE_NAME は、手順 2 で作成した XML ファイルのパスです。
- リクエストで既存の保持構成を短縮、削除、またはロックする場合は、BOOLEAN を true にする必要があります。それ以外の場合は、リクエストから x-goog-bypass-governance-retention ヘッダーを完全に除外できます。
- BUCKET_NAME は、関連するバケットの名前です。例: my-bucket
- OBJECT_NAME は、関連するオブジェクトの URL エンコードされた名前です。例: pets%2Fkitten.png として URL エンコードされている pets/kitten.png

オブジェクトの保持構成を表示する

オブジェクトに設定されている保持構成を確認するには:

コンソール

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、保持構成を表示するオブジェクトを含むバケットの名前をクリックします。

[バケットの詳細] ページが開き、[オブジェクト] タブが選択されています。
フォルダ内にあるオブジェクトに移動します。
オブジェクトの名前をクリックします。

[オブジェクトの詳細] ページが開き、オブジェクトのメタデータが表示されます。オブジェクトの保持構成に関する情報が [保護] セクションに表示されます。

コマンドライン

gcloud storage objects describe コマンドを使用し、--format フラグを指定します。

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(retention_settings)"

ここで

BUCKET_NAME は、関連するバケットの名前です。例: my-bucket
OBJECT_NAME は、該当するオブジェクトの名前です。例: kitten.png

成功し、オブジェクトに保持構成が存在する場合、レスポンスは次のようになります。

retention_settings:
  mode: Unlocked
  retainUntilTime: '2028-11-30T14:11:14+00:00'

成功し、オブジェクトに保持構成が存在しない場合、レスポンスは次のようになります。

null