El Servicio de transferencia de almacenamiento se puede usar para transferir grandes cantidades de datos entre buckets de Cloud Storage, dentro del mismo proyecto de Google Cloud o entre diferentes proyectos.
Las migraciones de buckets son útiles en varias situaciones. Se pueden usar para consolidar datos de proyectos separados, mover datos a una ubicación de copia de seguridad o cambiar la ubicación de tus datos.
Cuándo usar el Servicio de transferencia de almacenamiento
Google Cloud ofrece varias opciones para transferir datos entre buckets de Cloud Storage. Recomendamos los siguientes lineamientos:
Transferencia de menos de 1 TB: usa
gcloud. Para obtener instrucciones, consulta Mueve y cambia el nombre de los buckets.Transferencia de más de 1 TB: usa el Servicio de transferencia de almacenamiento. El Servicio de transferencia de almacenamiento es una opción de transferencia administrada que proporciona seguridad, confiabilidad y rendimiento listos para usar. Elimina la necesidad de optimizar y mantener secuencias de comandos, y controlar los reintentos.
En esta guía, se analizan las prácticas recomendadas para transferir datos entre buckets de Cloud Storage mediante el Servicio de transferencia de almacenamiento.
Define una estrategia de transferencia
La estrategia de transferencia depende de la complejidad de tu situación. Asegúrate de incluir las siguientes consideraciones en tu plan.
Elige un nombre para el bucket
Para mover tus datos a un bucket de almacenamiento diferente, elige uno de los siguientes enfoques:
- Nombre del bucket nuevo. Actualiza tus aplicaciones para que apunten a un bucket de almacenamiento con un nombre diferente.
- Conserva el nombre del bucket. Reemplaza tu bucket de almacenamiento para mantener el nombre actual, lo que significa que no necesitas actualizar tus aplicaciones.
En ambos casos, debes planificar el tiempo de inactividad y avisarles a los usuarios con anticipación. Revisa las siguientes explicaciones para comprender qué opción es la mejor para ti.
Nombre del bucket nuevo
Con un nombre de bucket nuevo, debes actualizar todo el código y los servicios que usan tu bucket actual. La forma de hacerlo depende de cómo se compilen y se implementen tus aplicaciones.
Para ciertas configuraciones, este enfoque puede tener menos tiempo de inactividad, pero requiere más trabajo para garantizar una transición sin problemas. Implica los siguientes pasos:
- Copiar tus datos en un bucket de almacenamiento nuevo
- Iniciando el tiempo de inactividad.
- Actualizar tus aplicaciones para que apunten al bucket nuevo
- Verificar que todo funcione como se espera y que todos los sistemas y cuentas pertinentes tengan acceso al bucket.
- Borrar el bucket original
- Finalizando el tiempo de descanso.
Conservar el nombre del bucket
Usa este enfoque si prefieres no cambiar el código para que apunte a un nombre de bucket nuevo. Implica los siguientes pasos:
- Copia tus datos en un bucket de almacenamiento temporal.
- Iniciando el tiempo de inactividad.
- Borrar el bucket original
- Crear un bucket nuevo con el mismo nombre que el original
- Copia los datos del bucket temporal al nuevo.
- Borra el bucket temporal.
- Verificar que todo funcione como se espera y que todos los sistemas y cuentas pertinentes tengan acceso al bucket.
- Finalizando el tiempo de descanso.
Reducir el tiempo de inactividad
El Servicio de transferencia de almacenamiento no bloquea la lectura o escritura en los buckets de origen o destino durante una transferencia.
Si eliges bloquear de forma manual la lectura o la escritura en tu bucket, para minimizar el tiempo de inactividad, considera transferir tus datos en dos pasos: origen y sincronización.
Transferencia de origen: Realiza una transferencia masiva sin bloquear las lecturas y escrituras en la fuente.
Transferencia de sincronización: Una vez que se complete la primera ejecución, bloquea la lectura y la escritura en el bucket de origen y realiza otra transferencia. Las transferencias del Servicio de transferencia de almacenamiento son incrementales de forma predeterminada, por lo que esta segunda transferencia solo transferirá los datos que cambiaron durante la transferencia de origen.
Optimiza la velocidad de transferencia
Cuando estimes cuánto tiempo llevará un trabajo de transferencia, considera los posibles cuellos de botella. Por ejemplo, si la fuente tiene miles de millones de archivos pequeños, la velocidad de transferencia estará vinculada a QPS. Si los tamaños de objetos son grandes, el ancho de banda puede ser el cuello de botella.
Los límites de ancho de banda se establecen a nivel de la región y se asignan de manera equitativa entre todos los proyectos. Si hay suficiente ancho de banda disponible, el Servicio de transferencia de almacenamiento puede completar alrededor de 1,000 tareas por trabajo de transferencia por segundo. En este caso, puedes acelerar una transferencia si divides tu trabajo en varios trabajos de transferencia pequeños, por ejemplo, si usas prefijos de inclusión y exclusión para transferir ciertos archivos.
En los casos en que la ubicación, la clase de almacenamiento y la clave de encriptación sean iguales, el Servicio de transferencia de almacenamiento no creará una copia nueva de los bytes. En su lugar, crea una nueva entrada de metadatos que apunta al BLOB de origen. Como resultado, las copias de la misma ubicación y clase de un corpus grande se completan muy rápido y solo están vinculadas a QPS.
Las eliminaciones también son operaciones de solo metadatos. Para estas transferencias, paralelizar la transferencia dividiéndola en varios trabajos pequeños puede aumentar la velocidad.
Conservar metadatos
Los siguientes metadatos de objeto se conservan cuando se transfieren datos entre buckets de Cloud Storage con el Servicio de transferencia de almacenamiento:
- Metadatos personalizados creados por el usuario.
- Campos de metadatos de clave fija de Cloud Storage, como Cache-Control, Content-Disposition, Content-Type y Custom-Time.
- Tamaño del objeto
- El número de generación se conserva
como un campo de metadatos personalizado con la clave
x-goog-reserved-source-generation, que puedes editar más adelante o quitar.
De manera opcional, los siguientes campos de metadatos se pueden conservar cuando se transfieren con la API:
- LCA (
acl) - Clase de almacenamiento (
storageClass) - CMEK (
kmsKey) - Retención temporal (
temporaryHold) - Hora de creación de los objetos (
timeCreated)
Consulta la referencia de la API de TransferOptions
para obtener más detalles.
No se conservan los siguientes campos de metadatos:
- Hora de la última actualización (
updated) etagcomponentCount
Si se conserva, la hora de creación del objeto se almacena como un campo personalizado,
customTime. La hora de updated del objeto se restablece cuando se transfiere, por lo que también se restablece el tiempo que pasó el objeto en su clase de almacenamiento.
Puedes aplicar tus políticas de ciclo de vida basadas en createTime
con customTime. Se reemplazan los valores de customTime existentes.
Para obtener más detalles sobre lo que se conserva y lo que no, consulta Conservación de metadatos.
Controla objetos con versión
Si deseas transferir todas las versiones de tus objetos de almacenamiento y no solo la más reciente, puedes usar la función de manifiesto del Servicio de transferencia de almacenamiento.
Para transferir todas las versiones de los objetos, haz lo siguiente:
Enumera los objetos de bucket y cópialos en un archivo JSON:
gcloud storage ls --all-versions --recursive --json gs://SOURCE_BUCKET > object-listing.jsonPor lo general, este comando enumera alrededor de 1,000 objetos por segundo.
Copia los objetos no actuales en un archivo CSV:
jq -r '.[] | select( .type=="cloud_object" and (.metadata | has("timeDeleted"))) | [.metadata.name, .metadata.generation] | @csv' object-listing.json > non-current-object-manifest.csvHabilita el control de versiones de objetos en el bucket de destino.
Transfiere las versiones no actuales con las siguientes opciones de transferencia:
- Especifica el archivo de manifiesto.
- Elige reemplazar siempre los objetos en el receptor
(
--overwrite-when=alwaysotransferOptions.overwriteWhen: ALWAYSen la API). Ten en cuenta que, en casos excepcionales, esto puede crear versiones duplicadas de un archivo. - Conserva los metadatos de
timeCreated(metadataOptions.timeCreated: TIME_CREATED_PRESERVE_AS_CUSTOM_TIME).
Transfiere las versiones activas con un trabajo de transferencia normal.
Configura las opciones de transferencia
Estas son algunas de las opciones disponibles para configurar tu transferencia:
Registro: Cloud Logging proporciona registros detallados de objetos individuales, lo que te permite verificar el estado de las transferencias y realizar verificaciones adicionales de integridad de los datos.
Filtros: Puedes usar los prefijos de inclusión y exclusión para limitar en qué objetos opera el Servicio de transferencia de almacenamiento. Esta opción se puede usar para dividir una transferencia en varios trabajos de transferencia para que puedan ejecutarse en paralelo. Consulta Optimiza la velocidad de transferencia para obtener más información.
Opciones de transferencia: Puedes configurar tu transferencia para reemplazar los elementos existentes en el bucket de destino, para borrar objetos en el destino que no existen en el conjunto de transferencia o para borrar objetos transferidos del origen.
Transfiere tus datos
Después de definir tu estrategia de transferencia, puedes realizar la transferencia en sí.
Crea un bucket nuevo
Antes de comenzar la transferencia, crea un bucket de almacenamiento.
Consulta Consideraciones de ubicación para obtener ayuda con la elección de una ubicación adecuada del bucket.
Te recomendamos copiar algunos de los metadatos del bucket cuando crees el bucket nuevo. Consulta Obtén metadatos del bucket para obtener información sobre cómo mostrar los metadatos del bucket de origen, de modo que puedas aplicar la misma configuración a tu bucket nuevo.
Copia objetos en el bucket nuevo
Puedes copiar objetos del bucket de origen a un bucket nuevo con la
consola deGoogle Cloud , la CLI de gcloud, la API de REST o las bibliotecas cliente.
El enfoque que elijas dependerá de tu estrategia de transferencia.
Las siguientes instrucciones son para el caso de uso básico de transferir objetos de un bucket a otro y deben modificarse para adaptarse a tus necesidades.
Consola de Google Cloud
Usa el Servicio de transferencia de almacenamiento desde la consola deGoogle Cloud :
Abre la página Transferencia en la consola de Google Cloud .
- Haz clic en Crear trabajo de transferencia.
Sigue la explicación detallada y haz clic en Siguiente a medida que completas cada uno de los siguientes pasos:
Para comenzar, usa Cloud Storage como Tipo de fuente y Tipo de destino.
Elige una fuente: ingresa el nombre del bucket deseado de forma directa o haz clic en Examinar para buscar y seleccionar el bucket que deseas.
Elige un destino: ingresa el nombre del bucket deseado de forma directa o haz clic en Examinar para buscar y seleccionar el bucket que deseas.
Selecciona la configuración: Selecciona la opción Borrar archivos desde la fuente después de la transferencia.
Opciones de programación: Puedes ignorar esta sección.
Después de completar la explicación paso a paso, haz clic en Crear.
Así, comienza el proceso de copia de objetos desde tu bucket anterior al nuevo. Este proceso puede tomar un tiempo; sin embargo, después de hacer clic en Crear, puedes salir de la consola de Google Cloud .
Para ver el progreso de la transferencia, haz lo siguiente:
Abre la página Transferencia en la consola de Google Cloud .
Abrir la página de Transferencias
Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas del Servicio de transferencia de almacenamiento en la consola de Google Cloud , consulta Solución de problemas.
Una vez que se completa la transferencia, no necesitas hacer nada para borrar los objetos de tu bucket anterior si durante la configuración seleccionaste la casilla de verificación Borrar archivos de la fuente después de la transferencia. Sin embargo, puedes borrar tu bucket anterior, lo que debes hacer por separado.
gcloud CLI
Instala Google Cloud CLI
Si aún no lo hiciste, instala Google Cloud CLI.
Luego, llama a gcloud init para inicializar la herramienta y especificar el ID del proyecto y la cuenta de usuario. Consulta
Inicializa gcloud CLI para obtener más detalles.
gcloud init
Otorga acceso al agente de servicio a tus buckets
Debes otorgar al agente de servicio del Servicio de transferencia de almacenamiento los roles necesarios en los buckets de origen y de destino antes de crear una transferencia. Consulta
Configura el acceso a una fuente: Cloud Storage
y
Configura el acceso a un receptor: Cloud Storage.
Por ejemplo, para otorgar un rol en el bucket de destino, usa
gcloud storage buckets add-iam-policy-binding:
gcloud storage buckets add-iam-policy-binding gs://bucket_name \ --member=serviceAccount:project-12345678@storage-transfer-service. \ --role=roles/storage.admin
Para obtener instrucciones sobre cómo usar la consola de Google Cloud o la API, consulta Usa los permisos de IAM en la documentación de Cloud Storage.
Crea el trabajo de transferencia
Para crear un nuevo trabajo de transferencia, usa el comando gcloud transfer jobs create.
Cuando creas un trabajo nuevo, se inicia la transferencia especificada, a menos que se indique un programa o
--do-not-run.
gcloud transfer jobs create SOURCE DESTINATION
Reemplaza lo siguiente:
SOURCE es la fuente de datos para esta transferencia, en el formato
gs://BUCKET_NAME.DESTINATION es tu bucket nuevo, con el formato
gs://BUCKET_NAME.
Las opciones adicionales incluyen:
Información del trabajo: puedes especificar
--namey--description.Programa: Especifica
--schedule-starts,--schedule-repeats-every, y--schedule-repeats-untilo--do-not-run.Condiciones de objetos: Usa condiciones para determinar qué objetos se transfieren. Estos incluyen
--include-prefixesy--exclude-prefixes, y las condiciones basadas en el tiempo en--include-modified-[before | after]-[absolute | relative].Opciones de transferencia: Especifica si deseas reemplazar los archivos de destino (
--overwrite-when=differentoalways) y si deseas borrar ciertos archivos durante o después de la transferencia (--delete-from=destination-if-uniqueosource-after-transfer). Especifica qué valores de metadatos se deben conservar (--preserve-metadata) y, de manera opcional, puedes configurar una clase de almacenamiento en los objetos transferidos (--custom-storage-class).Notificaciones: Configura las notificaciones de Pub/Sub para transferencias con
--notification-pubsub-topic,--notification-event-typesy--notification-payload-format.
Para ver todas las opciones, ejecuta gcloud transfer jobs create --help.
Por ejemplo, para transferir todos los objetos con el prefijo folder1, haz lo siguiente:
gcloud transfer jobs create gs://old-bucket gs://new-bucket \
--include-prefixes="folder1/"
REST
En este ejemplo, aprenderás cómo mover archivos desde un bucket de Cloud Storage a otro.
Por ejemplo, puedes replicar datos en un bucket en otra ubicación.
Realiza la solicitud con transferJobs create:
POST https://storagetransfer./v1/transferJobs { "description": "YOUR_DESCRIPTION", "status": "ENABLED", "projectId": "PROJECT_ID", "schedule": { "scheduleStartDate": { "day": DAY, "month": MONTH, "year": YEAR }, "startTimeOfDay": { "hours": 1, "minutes": 1 }, "scheduleEndDate": { "day": DAY, "month": MONTH, "year": YEAR } }, "transferSpec": { "gcsDataSource": { "bucketName": "GCS_SOURCE_NAME" }, "gcsDataSink": { "bucketName": "GCS_SINK_NAME" }, "transferOptions": { "deleteObjectsFromSourceAfterTransfer": true } } }
Respuesta:
200 OK { "name": "transferJobs/JOB_ID", "description": "YOUR_DESCRIPTION", "projectId": "PROJECT_ID", "transferSpec": { "gcsDataSource": { "bucketName": "GCS_SOURCE_NAME" }, "gcsDataSink": { "bucketName": "GCS_SINK_NAME" }, "transferOptions": { "deleteObjectsFromSourceAfterTransfer": true } }, "schedule": { "scheduleStartDate": { "day": DAY, "month": MONTH, "year": YEAR }, "scheduleEndDate": { "day": DAY, "month": MONTH, "year": YEAR }, "startTimeOfDay": { "hours": 1, "minutes": 1 } }, "status": "ENABLED", "creationTime": "2026-01-01T01:01:00.000000000Z", "lastModificationTime": "2026-01-01T01:01:00.000000000Z" }
Bibliotecas cliente
En los siguientes ejemplos, se crea un trabajo de transferencia diario que mueve objetos que no se modificaron durante 30 días desde un bucket de Cloud Storage de origen a un bucket de Cloud Storage de Nearline.
También puedes usar bibliotecas cliente para replicar datos en un bucket en otra ubicación.
Para obtener más información sobre las bibliotecas cliente del Servicio de transferencia de almacenamiento, consulta Comienza a usar las bibliotecas cliente del Servicio de transferencia de almacenamiento.
Java
¿Buscas muestras anteriores? Consulta la Guía de migración del Servicio de transferencia de almacenamiento.
Python
¿Buscas muestras anteriores? Consulta la Guía de migración del Servicio de transferencia de almacenamiento.
Verifica los objetos copiados
Una vez que se complete la transferencia, recomendamos realizar verificaciones adicionales de integridad de los datos.
Verifica que los objetos se hayan copiado correctamente mediante la verificación de los metadatos en los objetos, como las sumas de verificación y el tamaño.
Verifica que se haya copiado la versión correcta de los objetos. El Servicio de transferencia de almacenamiento ofrece una opción lista para usar que permite verificar que los objetos sean copias. Si habilitaste el registro, visualiza los registros para verificar si todos los objetos se copiaron de forma correcta, incluidos sus campos de metadatos correspondientes.
Comienza a usar el bucket de destino
Una vez que se complete y verifique la migración, actualiza todas las aplicaciones o cargas de trabajo existentes para que usen el nombre del bucket de destino. Consulta los registros de acceso a los datos en los registros de auditoría de Cloud para asegurarte de que tus operaciones modifiquen y lean objetos de forma correcta.
Borra el bucket original
Una vez que todo funcione bien, borra el bucket original.
El Servicio de transferencia de almacenamiento ofrece la opción de borrar objetos después de transferirlos
especificando deleteObjectsFromSourceAfterTransfer: true en la
configuración del trabajo o seleccionando la opción en la consola de Google Cloud .
Programa la eliminación de objetos
Para programar la eliminación de tus objetos en una fecha posterior, usa una combinación de un
trabajo de transferencia programado y la opción
deleteObjectsUniqueInSink = true.
El trabajo de transferencia debe configurarse para transferir un bucket vacío al bucket que contiene tus objetos. Esto hace que el Servicio de transferencia de almacenamiento enumere los objetos y comience a borrarlos. Como las eliminaciones son una operación de solo metadatos, el trabajo de transferencia solo está vinculado a las QPS. Para acelerar el proceso, divide la transferencia en varios trabajos, cada uno con un conjunto distinto de prefijos.
Como alternativa, Google Cloud ofrece un programador de trabajo cron administrado. Para obtener más información, consulta Programa el trabajo de transferencia de Google Cloud STS con Cloud Scheduler.