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.

API 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

API 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.

API 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

API 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 objeto GET que incluya el campo retention:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/OBJECT_NAME?fields=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.

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 objeto GET con alcance ?retention:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?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.

¿Qué sigue?

Obtén más información sobre las configuraciones de retención.
Obtén más información sobre otras funciones que protegen tus datos de Cloud Storage.
Obtén más información sobre la Administración del ciclo de vida de los objetos, que puede borrar de forma automática los archivos una vez que alcanzan su período de retención.