Usa la replicación entre buckets

En esta página, se describe cómo usar la replicación entre buckets, que usa el Servicio de transferencia de almacenamiento para copiar objetos nuevos y actualizados de forma asíncrona de un bucket de origen a uno de destino. Cuando usas la replicación entre buckets, creas y administras trabajos de replicación, que son un tipo de trabajo en Storage Transfer Service.

Antes de comenzar

Antes de comenzar, completa los pasos que se indican a continuación.

Habilita la API de Storage Transfer Service

Si aún no lo hiciste, habilita la API de Storage Transfer Service.

Obtén las funciones necesarias

Para obtener los permisos que necesitas para usar la replicación entre buckets, pídele a tu administrador que te otorgue el rol de IAM de usuario de transferencia de almacenamiento (roles/storagetransfer.user) en el bucket o el proyecto.

Este rol predefinido contiene los permisos necesarios para usar la replicación entre buckets. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para usar la replicación entre buckets:

storagetransfer.jobs.create
storagetransfer.jobs.delete
storagetransfer.jobs.get
storagetransfer.jobs.list
storagetransfer.jobs.run
storagetransfer.jobs.update

Para obtener instrucciones para otorgar roles a los buckets, consulta Usa IAM con buckets. Si deseas obtener instrucciones para otorgar roles a proyectos, consulta Administra el acceso a los proyectos.

Otorga roles necesarios

La replicación entre buckets usa Pub/Sub para recibir notificaciones de cambios en tu bucket de origen y el Servicio de transferencia de almacenamiento para replicar objetos de tu bucket de origen a tu bucket de destino. Para usar la replicación entre buckets, también debes otorgar los permisos necesarios al agente de servicio que usa el Servicio de transferencia de almacenamiento para replicar datos y al agente de servicio que usa Pub/Sub para escribir notificaciones.

Otorga los roles necesarios al agente de servicio del Servicio de transferencia de almacenamiento

El Servicio de transferencia de almacenamiento usa un agente de servicio administrado por Google para replicar los datos. La dirección de correo electrónico de este agente de servicio sigue el formato de nombres project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com. Puedes obtener la dirección de correo electrónico del agente de servicio del Servicio de transferencia de almacenamiento con la API de googleServiceAccounts.get del Servicio de transferencia de almacenamiento.

El agente de servicio del Servicio de transferencia de almacenamiento necesita los siguientes permisos para replicar tus objetos y configurar notificaciones de Pub/Sub para tu bucket de origen:

Permisos necesarios

storage.buckets.get en el bucket de origen y de destino
storage.buckets.update en el bucket de origen
storage.objects.list en el bucket de origen
storage.objects.get en el bucket de origen
storage.objects.rewrite en el bucket de destino
pubsub.topics.create en el proyecto

Estos permisos se pueden otorgar a través del rol de Editor de Pub/Sub (roles/pubsub.editor) y del rol de Administrador de almacenamiento (roles/storage.admin). Para obtener un rol menos permisivo que el de administrador de almacenamiento, también puedes usar un rol personalizado.

Otorga los roles necesarios al agente de servicio de Cloud Storage

Cloud Storage usa un agente de servicio administrado por Google para administrar las notificaciones de Pub/Sub. La dirección de correo electrónico de este agente de servicio sigue el formato de nombres service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com.

El agente de servicio de Cloud Storage necesita los siguientes permisos para configurar Pub/Sub y publicar mensajes en un tema:

Permisos necesarios

pubsub.topics.publish en el tema de Pub/Sub
pubsub.subscriptions.consume en el tema de Pub/Sub
pubsub.subscriptions.create en el proyecto

Estos permisos se pueden otorgar a través del rol de publicador de Pub/Sub (roles/pubsub.publisher).

Crea un trabajo de replicación

Console

Cuando usas la consola de Google Cloud, puedes crear un trabajo de replicación para buckets existentes o para buckets nuevos durante el proceso de creación de buckets.

Para crear un trabajo de replicación para un bucket nuevo, sigue las instrucciones para crear un bucket nuevo.

Para crear un trabajo de replicación para un bucket existente, completa los siguientes pasos:

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 de origen cuyos objetos deseas replicar.
En la página de detalles del bucket haz clic en la pestaña Configuración.
Busca la opción Replicación entre buckets y haz clic en Editar.
En el panel Editar replicación entre buckets que se abre, haz clic en Agregar un destino.
En la sección Elige un destino, selecciona un bucket de destino y, luego, haz clic en Siguiente.
En la sección Elige la configuración de replicación, haz lo siguiente:
- Opcional: Para filtrar los objetos que se replicarán por prefijo de nombre de objeto, selecciona la casilla de verificación Replicar objetos en función del prefijo en la sección Elegir qué objetos replicar.
  - Para incluir objetos por prefijo, ingresa un prefijo en la sección Incluir objetos con prefijo y, luego, haz clic en Agregar un prefijo.
  - Para excluir objetos por prefijo, ingresa un prefijo en la sección Excluir los objetos con prefijo y, luego, haz clic en Agregar un prefijo.
- Opcional: Para establecer una clase de almacenamiento para los objetos replicados, selecciona una clase de almacenamiento del menú en la sección Establecer la clase de almacenamiento para los objetos replicados.
  
  Si omites este paso, los objetos replicados usarán la clase de almacenamiento del bucket de destino de forma predeterminada.
1. Haz clic en Guardar.

Línea de comandos

Cuando usas Google Cloud CLI, puedes crear un trabajo de replicación para buckets existentes.

Para crear un trabajo de replicación, usa el comando gcloud alpha transfer jobs create con la marca --replication:

gcloud alpha transfer jobs create gs://SOURCE_BUCKET_NAME gs://DESTINATION_BUCKET_NAME --replication

Reemplaza lo siguiente:

SOURCE_BUCKET_NAME por el nombre del bucket de origen que deseas replicar. Por ejemplo, my-source-bucket
DESTINATION_BUCKET_NAME por el nombre del bucket de destino. Por ejemplo, my-destination-bucket

API de REST

API de JSON

Cuando usas la API de JSON, puedes crear un trabajo de replicación para los buckets existentes.

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 un objeto TransferJob con un recurso ReplicationSpec inicializado:
```
TransferJob {
 "name": "TRANSFER_JOB_NAME",
 ...
 ReplicationSpec: {
   "gcsDataSource": {
     "bucketName": "SOURCE_BUCKET_NAME"
   },
   "gcsDataSink" {
     "bucketName": "DESTINATION_BUCKET_NAME"
   },
   "objectConditions": {
   },
   "transferOptions": {
     "overwriteWhen": "OVERWRITE_OPTION"
   }
 }
 ...
}
```
Reemplaza lo siguiente:
- TRANSFER_JOB_NAME por el nombre que deseas asignar al trabajo de replicación. Consulta la documentación de referencia de transferJobs para conocer los requisitos de nombres.
- SOURCE_BUCKET_NAME con el nombre del bucket de origen que contiene los objetos que deseas replicar. Por ejemplo, example-source-bucket.
- DESTINATION_BUCKET_NAME por el nombre del bucket de destino en el que se replicarán tus objetos. Por ejemplo, example-destination-bucket.
- OVERWRITE_OPTION con una opción para indicar cómo se pueden reemplazar los objetos existentes en el bucket de destino como resultado de un trabajo de replicación, lo que puede ocurrir cuando el objeto de destino y el objeto de origen tienen el mismo nombre. El valor debe ser uno de los siguientes:
  - ALWAYS: Siempre reemplaza los objetos en el bucket de destino.
  - DIFFERENT: Solo reemplaza los objetos en el bucket de destino si los datos del objeto de destino son diferentes de los datos del objeto de origen.
  - NEVER: Nunca reemplaza objetos en el bucket de destino.

Usa cURL para llamar a la API de REST del Servicio de transferencia de almacenamiento con una solicitud transferJobs.create:

curl -X POST --data-binary @JSON_FILE_NAME \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs"

Donde:

JSON_FILE_NAME es el nombre del archivo JSON que creaste en el paso 2.

Para verificar el estado de la tarea de replicación, consulta Cloud Logging para ver los registros del Servicio de transferencia de almacenamiento.

Enumera los trabajos de replicación

Console

No puedes enumerar trabajos de replicación con la consola de Google Cloud. Consulta Cómo ver un trabajo de replicación para obtener instrucciones sobre cómo ver un solo trabajo de replicación a la vez.

Línea de comandos

Usa el comando gcloud alpha transfer jobs list con la marca --job-type:

gcloud alpha transfer jobs list --job-type=replication

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 REST del Servicio de transferencia de almacenamiento con una solicitud transferJobs.list:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs"

Ve un trabajo de replicación

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 de origen cuyo trabajo de replicación entre buckets deseas ver.
En la página de detalles del bucket haz clic en la pestaña Configuración.
Busca la opción Replicación entre buckets y haz clic en Editar.

Aparecerá el panel Editar replicación entre buckets, que muestra la tarea de replicación de cada bucket de destino.

En la página Buckets, puedes ver la columna Replication, que muestra si un bucket tiene un trabajo de replicación turbo o un trabajo de replicación entre buckets en ejecución. Para obtener instrucciones sobre cómo mostrar la columna Replicación, consulta Cómo mostrar columnas.

Línea de comandos

Usa el comando gcloud alpha transfer jobs describe:

gcloud alpha transfer jobs describe JOB_NAME

Reemplaza lo siguiente:

JOB_NAME con el ID único del trabajo de replicación. Por ejemplo, 1234567890 Para encontrar el ID de tu trabajo de transferencia, enumera tus trabajos de replicación.

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 REST del Servicio de transferencia de almacenamiento con una solicitud transferJobs.get:
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"
```
Reemplaza lo siguiente:
- JOB_NAME con el ID único del trabajo de replicación. Por ejemplo, 1234567890 Para encontrar el ID de tu trabajo de replicación, enumera tus trabajos de replicación.

Actualiza un trabajo de replicación

Puedes actualizar los siguientes campos de un trabajo de replicación:

La descripción del trabajo de replicación
La configuración para ejecutar un trabajo de replicación
La configuración de las notificaciones publicadas en Pub/Sub
El comportamiento de registro para las operaciones de trabajos de replicación
El estado del trabajo de replicación (si está habilitado, inhabilitado o eliminado)

Console

Cuando usas la consola de Google Cloud, solo puedes actualizar un trabajo de replicación si lo pausas o lo reanudas.

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 de origen cuya replicación deseas pausar o reanudar.
En la página de detalles del bucket haz clic en la pestaña Configuración.
Busca la opción Replicación entre buckets y haz clic en Editar.
En el panel Editar replicación entre buckets que aparece, haz clic en Pausar o Despausar junto al trabajo de replicación que deseas actualizar.

Línea de comandos

Usa el comando gcloud alpha transfer jobs update con las marcas que controlan las propiedades del trabajo de replicación que deseas actualizar. Para obtener una lista de marcas posibles, consulta la documentación de gcloud alpha transfer jobs update.

Por ejemplo, para actualizar el comportamiento de reemplazo de objetos del trabajo de replicación, ejecuta el comando gcloud alpha transfer jobs update con la marca --overwrite-when:

gcloud alpha transfer jobs update JOB_NAME --overwrite-when=OVERWRITE_OPTION

Reemplaza lo siguiente:

JOB_NAME con el ID único del trabajo de replicación. Por ejemplo, 1234567890 Para encontrar el ID de tu trabajo de transferencia, enumera o consulta el trabajo.
OVERWRITE_OPTION con una opción para indicar cómo se pueden reemplazar los objetos existentes en el bucket de destino como resultado de un trabajo de replicación, lo que puede ocurrir cuando el objeto de destino y el objeto de origen tienen el mismo nombre. El valor debe ser uno de los siguientes:
- always: Siempre reemplaza los objetos de destino.
- different: Solo reemplaza los objetos en el bucket de destino si los datos del objeto de destino son diferentes de los datos del objeto de origen.
- never: Nunca reemplaza los objetos de destino.

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 estructura que incluya los campos del objeto TransferJob que deseas actualizar:
```
{
 "projectId": string,
 "transferJob": {
   object (TransferJob)
 },
   "updateTransferJobFieldMask": UPDATE_MASK
}
```
Donde:
- object (TransferJob) se reemplaza por los campos del trabajo de replicación que deseas actualizar. Consulta la representación de recursos TransferJob para obtener más información.
- UPDATE_MASK es una lista separada por comas de los nombres de campo que deseas actualizar. Los valores pueden ser uno o más de los siguientes: description, transferSpec, notificationConfig, loggingConfig y status.
Para obtener más información sobre los nombres de campos que puedes incluir, consulta el cuerpo de la solicitud de transferJobs.patch.
Usa cURL para llamar a la API de REST del Servicio de transferencia de almacenamiento con una solicitud transferJobs.patch:
```
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"
```
Reemplaza lo siguiente:
- JOB_NAME con el ID único del trabajo de replicación. Por ejemplo, 1234567890 Para encontrar el ID de tu trabajo de replicación, enumera tus trabajos de replicación.

Borra un trabajo de replicación

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 de origen que deseas dejar de replicar.
En la página de detalles del bucket haz clic en la pestaña Configuración.
Busca la opción Replicación entre buckets y haz clic en Editar.
En el panel Editar replicación entre buckets que aparece, haz clic en Borrar junto al trabajo de replicación que deseas borrar.
En el cuadro de diálogo que aparece, haz clic en Permitir.

Línea de comandos

Usa el comando gcloud alpha transfer jobs delete:

gcloud alpha transfer jobs delete JOB_NAME

Reemplaza lo siguiente:

JOB_NAME con el ID único del trabajo de replicación. Por ejemplo, 1234567890 Para encontrar el ID de tu trabajo de replicación, enumera tus trabajos de replicación.

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 REST del Servicio de transferencia de almacenamiento con una solicitud transferJobs.delete:
```
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"
```
Reemplaza lo siguiente:
- JOB_NAME con el ID único del trabajo de replicación. Por ejemplo, 1234567890 Para encontrar el ID de tu trabajo de replicación, enumera tus trabajos de replicación.