Habilita y usa la configuración de retención de objetos

Descripción general

En esta página, se describe cómo usar la función de bloqueo de retención de objetos, incluida la habilitación para un bucket y la configuración de retención de los objetos dentro del bucket.

Roles obligatorios

Para obtener los permisos que necesitas a fin de habilitar la función de bloqueo de retención de objetos para un bucket y establecer la configuración de retención en los objetos, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el bucket o en el proyecto que contiene el bucket. Este rol predefinido contiene los permisos necesarios para establecer y administrar la configuración de retención. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

storage.buckets.create
storage.buckets.enableObjectRetention
storage.buckets.get
storage.buckets.list
- Este permiso solo es necesario si planeas usar la consola de Google Cloud para ejecutar las instrucciones en esta página.
storage.objects.get
storage.objects.list
- Este permiso solo es necesario si planeas usar la consola de Google Cloud para ejecutar las instrucciones en esta página.
storage.objects.overrideUnlockedRetention
- Este permiso solo es necesario si planeas bloquear o acortar una configuración de retención existente.
storage.objects.setRetention
storage.objects.update

También puedes obtener estos permisos con roles personalizados.

Para obtener más información sobre cómo otorgar roles en los buckets, consulta Usa IAM con buckets. Para obtener información sobre cómo otorgar roles en proyectos, consulta Administra el acceso a los proyectos.

Habilita las retenciones de objetos para un bucket

La habilitación de la retención de objetos solo se admite como parte de la creación del bucket y si la retención de objetos está habilitada en un bucket, no se puede inhabilitar. Usa las siguientes instrucciones para habilitar las retenciones de objetos para un bucket:

Console

Crea un bucket como lo harías normalmente y, en el paso Elige cómo proteger los datos de objetos, selecciona Retención (para el cumplimiento) y, a continuación, Habilitar la retención de objetos.

Línea de comandos

Crea un bucket como lo harías normalmente y, luego, incluye la marca --enable-per-object-retention en el comando.

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

//! [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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

/**
 * 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

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}")

APIs de REST

API de JSON

Crea un bucket como lo harías normalmente y, luego, incluye el parámetro de búsqueda enableObjectRetention=true como parte de la solicitud.

API de XML

Crea un bucket como lo harías normalmente y, luego, incluye el encabezado x-goog-bucket-object-lock-enabled: True como parte de la solicitud.

Ve el estado de retención de objetos de un bucket

A fin de ver si las retenciones de objetos están habilitadas para un bucket, sigue estos pasos:

Console

En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
Ir a Buckets
Haz clic en el nombre del bucket cuyo estado deseas verificar.
Haz clic en la pestaña Protección.
El estado de retención de objetos del bucket se muestra en la sección Retención de objetos.

Línea de comandos

Usa el comando gcloud storage buckets describe con la marca --format:

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

En el ejemplo anterior, BUCKET_NAME es el nombre del bucket cuya política de retención deseas ver. Por ejemplo, my-bucket.

Si se realiza de forma correcta y existe una política de retención en el bucket, la respuesta será similar a la siguiente:

per_object_retention:
  mode: Enabled

Si se realiza de forma correcta y no existe una política de retención para el bucket, la respuesta será similar a la siguiente:

null

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Si deseas ver la configuración de retención de objetos de un bucket, sigue las instrucciones para mostrar los metadatos de un bucket y busca el campo de retención de objetos en la respuesta.

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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Si deseas ver la configuración de retención de objetos de un bucket, sigue las instrucciones para mostrar los metadatos de un bucket y busca el campo de retención de objetos en la respuesta.


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Si deseas ver la configuración de retención de objetos de un bucket, sigue las instrucciones para mostrar los metadatos de un bucket y busca el campo de retención de objetos en la respuesta.


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Si deseas ver la configuración de retención de objetos de un bucket, sigue las instrucciones para mostrar los metadatos de un bucket y busca el campo de retención de objetos en la respuesta.

// 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Si deseas ver la configuración de retención de objetos de un bucket, sigue las instrucciones para mostrar los metadatos de un bucket y busca el campo de retención de objetos en la respuesta.

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Si deseas ver la configuración de retención de objetos de un bucket, sigue las instrucciones para mostrar los metadatos de un bucket y busca el campo de retención de objetos en la respuesta.


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}")

APIs de REST

API de JSON

Tener la gcloud CLI instalada e inicializada a fin de generar un token de acceso para el encabezado Authorization.

Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.
Usa cURL para llamar a la API de JSON con una solicitud de bucket GET que incluya el campo objectRetention:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=objectRetention"
```
En el que BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.

API de XML

Tener la gcloud CLI instalada e inicializada a fin de generar un token de acceso para el encabezado Authorization.

Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.
Usa cURL para llamar a la API de XML con una solicitud de bucket GET con alcance ?object-lock:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?object-lock"
```
En el que BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.

Establece la configuración de retención de un objeto

Si quieres establecer una configuración de retención para un objeto, este debe almacenarse en un bucket en el que las retenciones de objetos estén habilitadas. Para establecer una configuración de retención para un objeto, sigue estos pasos:

Console

En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
Ir a Buckets
En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto cuya configuración de retención deseas establecer o modificar.

Se abrirá la página Detalles del bucket y se seleccionará la pestaña Objetos.
Navega hasta el objeto, que puede estar en una carpeta.
Haz clic en el nombre del objeto.

Se abre la página Detalles del objeto, que muestra los metadatos de objetos.
En la sección Protección, haz clic en el ícono Editar () asociado con Desde la configuración de retención de objetos.

Se abrirá el panel Editar la retención.
En la sección Configuración de retención de objetos, haz clic en Habilitada o Inhabilitada.
1. Si la configuración de retención está habilitada, selecciona una fecha y hora para la configuración en la sección Período de retención y haz clic en Desbloqueada o Bloqueada en la sección Modo de retención.
Haz clic en Confirmar.

Línea de comandos

Usa el comando gcloud storage objects update con las marcas adecuadas: Para agregar o modificar una configuración de retención, usa el siguiente comando. Ten en cuenta que debes incluir la marca --override-unlocked-retention si modificas una configuración existente de una manera que la bloquea o acorta su tiempo de retención:

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

Aquí:

BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre del objeto pertinente. Por ejemplo, kitten.png.
DATETIME es la fecha y hora más tempranas en las que se puede borrar el objeto. Por ejemplo, 2028-02-15T05:30:00Z.
STATE es Locked o Unlocked.

Si se realiza de forma correcta, la respuesta se verá como el ejemplo siguiente:

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

Para quitar una configuración de retención de un objeto, usa el siguiente comando:

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

Aquí:

BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre del objeto pertinente. Por ejemplo, kitten.png.

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

/**
 * 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

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}."
    )

APIs de REST

API de JSON

Tener la gcloud CLI instalada e inicializada a fin de generar un token de acceso para el encabezado Authorization.

Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.
Crea un archivo JSON que contenga la siguiente información:
```
{
  "retention": {
    "mode": STATE,
    "retainUntilTime": "DATETIME"
  }
}
```
Aquí:
- STATE es Locked o Unlocked.
- DATETIME es la fecha y hora más tempranas en las que se puede borrar el objeto. Por ejemplo, 2028-02-15T05:30:00Z.
Usa cURL para llamar a la API de JSON con una solicitud de objeto PATCH:
```
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"
```
Aquí:
- JSON_FILE_NAME es la ruta de acceso del archivo que creaste en el paso 2.
- BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.
- OBJECT_NAME es el nombre codificado en URL del objeto relevante. Por ejemplo, pets/kitten.png, codificado en URL como pets%2Fkitten.png.
- BOOLEAN debe ser true si la solicitud se acorta, se quita o se bloquea una configuración de retención existente. De lo contrario, el parámetro overrideUnlockedRetention se puede excluir de la solicitud por completo.

API de XML

Tener la gcloud CLI instalada e inicializada a fin de generar un token de acceso para el encabezado Authorization.

Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.
Crea un archivo XML que contenga la siguiente información:
```
<Retention>
  <Mode>
    STATE
  </Mode>
  <RetainUntilDate>
    DATETIME
  </RetainUntilDate>
</Retention>
```
Aquí:
- STATE es GOVERNANCE o COMPLIANCE.
- DATETIME es la fecha y hora más tempranas en las que se puede borrar el objeto. Por ejemplo, 2028-02-15T05:30:00Z.
Usa cURL para llamar a la API de XML con una solicitud de objeto PUT con alcance ?retention:
```
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"
```
Aquí:
- XML_FILE_NAME es la ruta de acceso del archivo XML que creaste en el paso 2.
- BOOLEAN debe ser true si la solicitud se acorta, se quita o se bloquea una configuración de retención existente. De lo contrario, el encabezado x-goog-bypass-governance-retention se puede excluir de la solicitud por completo.
- BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.
- OBJECT_NAME es el nombre codificado en URL del objeto relevante. Por ejemplo, pets/kitten.png, codificado en URL como pets%2Fkitten.png.

Ve la configuración de retención de un objeto

Para ver qué configuración de retención, si hay alguna, está establecida en un objeto, haz lo siguiente:

Console

En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
Ir a Buckets
En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto cuya configuración de retención deseas ver.

Se abrirá la página Detalles del bucket y se seleccionará la pestaña Objetos.
Navega hasta el objeto, que puede estar en una carpeta.
Haz clic en el nombre del objeto.

Se abre la página Detalles del objeto, que muestra los metadatos de objetos. En la sección Protección, se muestra información sobre las opciones de configuración de retención que tiene el objeto.

Línea de comandos

Usa el comando gcloud storage objects describe con la marca --format:

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

Aquí:

BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre del objeto pertinente. Por ejemplo, kitten.png.

Si se ejecuta de forma correcta y existe una configuración de retención para el objeto, la respuesta es similar a la siguiente:

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

Si se ejecuta de forma correcta y no existe una configuración de retención para el objeto, la respuesta es similar a la siguiente:

null