Esta página se ha traducido con Cloud Translation API.

Transferir datos de un sistema de archivos a Cloud Storage

En esta página se explica cómo crear tareas de transferencia entre un sistema de archivos (local o en la nube) y Cloud Storage.

Las transferencias de sistemas de archivos a Cloud Storage se basan en agentes, lo que significa que instalará agentes de software en una máquina con acceso a su sistema de archivos para coordinar la transferencia.

Configurar permisos

Antes de crear una transferencia, debe configurar los permisos de las siguientes entidades:

	La cuenta de usuario que se usa para crear la transferencia. Esta es la cuenta con la que se ha iniciado sesión en la consola Google Cloud o la cuenta que se ha especificado al autenticar la CLI de `gcloud`. La cuenta de usuario puede ser una cuenta de usuario normal o una cuenta de servicio gestionada por el usuario.
	La cuenta de servicio gestionada por Google, también conocida como agente de servicio, que usa el Servicio de transferencia de Storage. Esta cuenta se identifica generalmente por su dirección de correo, que tiene el formato `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com`.
	La cuenta de agente de transferencia que proporciona Google Cloud permisos a los agentes de transferencia. Las cuentas de agente de transferencia usan las credenciales del usuario que las instala o las credenciales de una cuenta de servicio gestionada por el usuario para autenticarse.

Consulta las instrucciones en Permisos de transferencia basados en agentes.

Instalar agentes en un grupo de agentes

Las transferencias basadas en agentes usan agentes de software para coordinar las transferencias. Estos agentes deben instalarse en un equipo que tenga acceso al sistema de archivos implicado en la transferencia.

No incluyas información sensible, como información personal identificable (IPI) o datos de seguridad, en el nombre del grupo de agentes ni en el prefijo del ID de agente. Los nombres de recursos pueden propagarse a los nombres de otros recursos de Google Cloud y pueden exponerse a sistemas internos de Google fuera de tu proyecto.

Crea un grupo de agentes. Usa tu cuenta de usuario para realizar esta acción.
Instala agentes en el grupo de agentes. Usa tu cuenta de agente de transferencias para realizar esta acción.

Te recomendamos que empieces con 3 agentes en tu grupo de agentes de origen. Una vez que la transferencia esté en curso, monitoriza la velocidad de transferencia. Puedes añadir más agentes al grupo mientras la transferencia esté en curso.

Recomendamos una VM por agente, cada una con un mínimo de 4 CPUs y 8 GiB de RAM.

Opciones de transferencia

Las siguientes funciones del Servicio de transferencia de Storage están disponibles para las transferencias de sistemas de archivos a Cloud Storage.

Transferir archivos específicos mediante un manifiesto

Puedes enviar una lista de archivos para que el Servicio de transferencia de Storage actúe sobre ellos. Para obtener más información, consulta Transferir archivos u objetos específicos mediante un archivo de manifiesto.

Especificar una clase de almacenamiento

Puedes especificar la clase de almacenamiento de Cloud Storage que quieras usar para tus datos en el segmento de destino. Consulta las opciones de StorageClass para obtener información sobre REST o usa la marca --custom-storage-class con la CLI de Google Cloud.

Ten en cuenta que se ignorarán los ajustes de la clase de almacenamiento si el Autoclass está habilitado en el cubo de destino. Si Autoclass está habilitado, los objetos transferidos al segmento se asignan inicialmente al almacenamiento Estándar.

Preservación de metadatos

Al transferir archivos de sistemas de archivos, el Servicio de transferencia de Storage puede conservar determinados atributos como metadatos personalizados. Si estos archivos se vuelven a escribir en un sistema de archivos más adelante, el Servicio de transferencia de Storage puede convertir los metadatos conservados en atributos POSIX.

Consulta la sección Transferencias del sistema de archivos POSIX del artículo Conservación de metadatos para obtener información sobre qué metadatos se pueden conservar y cómo configurar la transferencia.

Gestionar el ancho de banda de la red

Storage Transfer Service utiliza de forma predeterminada todo el ancho de banda disponible para transferir archivos desde tu sistema de archivos. Puedes establecer un límite de ancho de banda para evitar que una transferencia afecte a otro tráfico de red. Los límites de ancho de banda se aplican a nivel de grupo de agentes.

Consulta más información en el artículo Gestionar el ancho de banda de una red.

Tu cuenta de usuario requiere el rol Administrador de Transferencia de Almacenamiento (roles/storagetransfer.admin) para definir o cambiar los límites de ancho de banda.

Almacenamiento de registros

El Servicio de transferencia de Storage admite Cloud Logging para el Servicio de transferencia de Storage (opción recomendada) y registros de transferencia basados en agentes.

Crear una transferencia

No incluyas información sensible, como información personal identificable (IPI) o datos de seguridad, en el nombre del trabajo de transferencia. Los nombres de recursos pueden propagarse a los nombres de otros recursos de Google Cloud y pueden exponerse a sistemas internos de Google fuera de tu proyecto.

El Servicio de transferencia de Storage ofrece varias interfaces para crear una transferencia.

Google Cloud consola

Ve a la página Storage Transfer Service de la Google Cloud consola.

Ir al Servicio de transferencia de Storage
Haz clic en Crear tarea de transferencia. Se muestra la página Crear una tarea de transferencia.
Elige Sistema de archivos POSIX como fuente.
Seleccione Cloud Storage como tipo de destino y haga clic en Paso siguiente.
Selecciona un grupo de agentes o Crear grupo de agentes y sigue las instrucciones para crear uno.
Especifica la ruta completa del directorio del sistema de archivos.
Haz clic en Siguiente paso.
En el campo Segmento o carpeta, introduce el nombre del segmento de destino y, opcionalmente, el de la carpeta. También puedes hacer clic en Examinar para seleccionar un segmento de la lista de segmentos de tu proyecto. Para crear un nuevo contenedor, haz clic en Crear nuevo contenedor.
Haz clic en Siguiente paso.
Elige las opciones de programación.

Nota: Storage Transfer Service muestra las programaciones de los trabajos de transferencia en tu zona horaria local, pero almacena esas horas en tiempo universal coordinado (UTC). Si te afecta el horario de verano, es posible que el horario de las tareas de transferencia cambie cuando empiece o termine.
Haz clic en Siguiente paso.
Elige la configuración del trabajo de transferencia.
- En el campo Descripción, introduce una descripción de la transferencia. Como práctica recomendada, introduce una descripción significativa y única para poder distinguir los trabajos.
- En Opciones de metadatos, utilice las opciones predeterminadas o actualice uno o varios valores. Para obtener más información, consulta Conservación de metadatos.
- En Cuándo sobrescribir, seleccione una de las siguientes opciones:
  - Nunca: Storage Transfer Service omite la transferencia de los archivos de la fuente que tengan el mismo nombre que un archivo presente en el destino.
  - Si es diferente: sobrescribe los archivos de destino si el archivo de origen con el mismo nombre tiene valores de ETag o de suma de comprobación diferentes.
  - Siempre: siempre sobrescribe los archivos de destino cuando el archivo de origen tiene el mismo nombre, aunque sean idénticos.
- En Cuándo eliminar, selecciona una de las siguientes opciones:
  - Nunca: no elimina nunca los archivos del origen ni del destino.
  - Eliminar archivos del origen cuando se hayan transferido: elimina los archivos del origen cuando se hayan transferido al destino. Si no se transfiere un archivo de origen (por ejemplo, porque ya existe en el destino), no se elimina.
    
    Importante: Si no tienes una copia de seguridad local, esta opción es una acción irreversible.
  - Eliminar los archivos en el destino si tampoco están en el origen: si los archivos del segmento de Cloud Storage de destino no están en el origen, elimínelos del segmento de Cloud Storage.
    
    Esta opción asegura que el segmento de destino de Cloud Storage coincida exactamente con el de origen.
- Selecciona si quieres Habilitar el registro en Cloud Storage o Habilitar el registro en Cloud Logging. Consulta más información en Registros de transferencia del sistema de archivos y Cloud Logging para el Servicio de transferencia de Storage.
Para crear la tarea de transferencia, haz clic en Crear.

`gcloud`

Antes de usar los comandos gcloud, instala Google Cloud CLI.

Para crear una tarea de transferencia, usa el comando gcloud transfer jobs create. Al crear una tarea, se inicia la transferencia especificada, a menos que se indique una programación o un --do-not-run.

gcloud transfer jobs create \
  posix:///SOURCE \
  gs://DESTINATION/ \
  --source-agent-pool=SOURCE_POOL_NAME

Donde:

SOURCE es una ruta absoluta desde la raíz del sistema de archivos. Tiene el prefijo posix://, por lo que el valor final incluirá tres barras diagonales. Por ejemplo, posix:///tmp/data/.
DESTINATION es el nombre de un segmento de Cloud Storage y, opcionalmente, una ruta de carpeta seguida de una barra diagonal. Por ejemplo, gs://example-bucket/data/.
--source-agent-pool especifica el grupo de agentes de origen que se usará para esta transferencia.

Entre las opciones adicionales se incluyen:

--do-not-run impide que el Servicio de transferencia de Storage ejecute el trabajo al enviar el comando. Para ejecutar el trabajo, actualízalo para añadir una programación o usa jobs run para iniciarlo manualmente.
--manifest-file especifica la ruta a un archivo CSV de Cloud Storage que contiene una lista de archivos que se van a transferir desde la fuente. Para obtener información sobre el formato del archivo de manifiesto, consulta el artículo Transferir archivos u objetos específicos mediante un manifiesto.
Información del trabajo: puedes especificar --name y --description.
Programación: especifica --schedule-starts, --schedule-repeats-every y --schedule-repeats-until, o --do-not-run.
Opciones de transferencia: especifica si quieres sobrescribir los archivos de destino (--overwrite-when=different o always) y si quieres eliminar determinados archivos durante o después de la transferencia (--delete-from=destination-if-unique o source-after-transfer); especifica qué valores de metadatos quieres conservar (--preserve-metadata) y, opcionalmente, define una clase de almacenamiento para los objetos transferidos (--custom-storage-class).

Para ver todas las opciones, ejecuta gcloud transfer jobs create --help o consulta la documentación de referencia de gcloud. Ten en cuenta que no todas las opciones se admiten en las transferencias basadas en agentes. Las opciones no admitidas incluyen una nota en este sentido en su texto de ayuda.

REST

En el siguiente ejemplo se muestra cómo usar el Servicio de transferencia de Storage a través de la API REST.

Cuando configure o edite tareas de transferencia mediante la API Storage Transfer Service, la hora debe estar en UTC. Para obtener más información sobre cómo especificar la programación de una tarea de transferencia, consulta Programación.

Para mover archivos de un sistema de archivos POSIX a un segmento de Cloud Storage, usa transferJobs.create con un posixDataSource:

POST https://storagetransfer.googleapis.com/v1/transferJobs
{
 "name":"transferJobs/sample_transfer",
 "description": "My First Transfer",
 "status": "ENABLED",
 "projectId": "my_transfer_project_id",
 "schedule": {
     "scheduleStartDate": {
         "year": 2022,
         "month": 5,
         "day": 2
     },
     "startTimeOfDay": {
         "hours": 22,
         "minutes": 30,
         "seconds": 0,
         "nanos": 0
     }
     "scheduleEndDate": {
         "year": 2022,
         "month": 12,
         "day": 31
     },
     "repeatInterval": {
         "259200s"
     },
 },
 "transferSpec": {
     "posixDataSource": {
          "rootDirectory": "/bar/",
     },
     "sourceAgentPoolName": "my_example_pool",
     "gcsDataSink": {
          "bucketName": "destination_bucket"
          "path": "foo/bar/"
     },
  }
}

El campo schedule es opcional. Si no se incluye, la tarea de transferencia debe iniciarse con una solicitud transferJobs.run.

Para comprobar el estado de tu transferencia después de crear un trabajo, usa transferJobs.get:

GET https://storagetransfer.googleapis.com/v1/transferJobs/sample_transfer?project_id=my_transfer_project_id

Bibliotecas de cliente

En los siguientes ejemplos se muestra cómo usar Storage Transfer Service de forma programática con Go, Java, Node.js y Python.

Cuando configures o edites tareas de transferencia mediante programación, la hora debe estar en UTC. Para obtener más información sobre cómo especificar la programación de una tarea de transferencia, consulta Programación.

Para obtener más información sobre las bibliotecas de cliente del Servicio de transferencia de Storage, consulta el artículo Empezar a usar las bibliotecas de cliente del Servicio de transferencia de Storage.

Para mover archivos de un sistema de archivos POSIX a un segmento de Cloud Storage, sigue estos pasos:

Go


import (
	"context"
	"fmt"
	"io"

	storagetransfer "cloud.google.com/go/storagetransfer/apiv1"
	"cloud.google.com/go/storagetransfer/apiv1/storagetransferpb"
)

func transferFromPosix(w io.Writer, projectID string, sourceAgentPoolName string, rootDirectory string, gcsSinkBucket string) (*storagetransferpb.TransferJob, error) {
	// Your project id
	// projectId := "myproject-id"

	// The agent pool associated with the POSIX data source. If not provided, defaults to the default agent
	// sourceAgentPoolName := "projects/my-project/agentPools/transfer_service_default"

	// The root directory path on the source filesystem
	// rootDirectory := "/directory/to/transfer/source"

	// The ID of the GCS bucket to transfer data to
	// gcsSinkBucket := "my-sink-bucket"

	ctx := context.Background()
	client, err := storagetransfer.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storagetransfer.NewClient: %w", err)
	}
	defer client.Close()

	req := &storagetransferpb.CreateTransferJobRequest{
		TransferJob: &storagetransferpb.TransferJob{
			ProjectId: projectID,
			TransferSpec: &storagetransferpb.TransferSpec{
				SourceAgentPoolName: sourceAgentPoolName,
				DataSource: &storagetransferpb.TransferSpec_PosixDataSource{
					PosixDataSource: &storagetransferpb.PosixFilesystem{RootDirectory: rootDirectory},
				},
				DataSink: &storagetransferpb.TransferSpec_GcsDataSink{
					GcsDataSink: &storagetransferpb.GcsData{BucketName: gcsSinkBucket},
				},
			},
			Status: storagetransferpb.TransferJob_ENABLED,
		},
	}

	resp, err := client.CreateTransferJob(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("failed to create transfer job: %w", err)
	}
	if _, err = client.RunTransferJob(ctx, &storagetransferpb.RunTransferJobRequest{
		ProjectId: projectID,
		JobName:   resp.Name,
	}); err != nil {
		return nil, fmt.Errorf("failed to run transfer job: %w", err)
	}
	fmt.Fprintf(w, "Created and ran transfer job from %v to %v with name %v", rootDirectory, gcsSinkBucket, resp.Name)
	return resp, nil
}

Java

import com.google.storagetransfer.v1.proto.StorageTransferServiceClient;
import com.google.storagetransfer.v1.proto.TransferProto;
import com.google.storagetransfer.v1.proto.TransferTypes.GcsData;
import com.google.storagetransfer.v1.proto.TransferTypes.PosixFilesystem;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferJob;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferSpec;
import java.io.IOException;

public class TransferFromPosix {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your project id
    String projectId = "my-project-id";

    // The agent pool associated with the POSIX data source. If not provided, defaults to the
    // default agent
    String sourceAgentPoolName = "projects/my-project-id/agentPools/transfer_service_default";

    // The root directory path on the source filesystem
    String rootDirectory = "/directory/to/transfer/source";

    // The ID of the GCS bucket to transfer data to
    String gcsSinkBucket = "my-sink-bucket";

    transferFromPosix(projectId, sourceAgentPoolName, rootDirectory, gcsSinkBucket);
  }

  public static void transferFromPosix(
      String projectId, String sourceAgentPoolName, String rootDirectory, String gcsSinkBucket)
      throws IOException {
    TransferJob transferJob =
        TransferJob.newBuilder()
            .setProjectId(projectId)
            .setTransferSpec(
                TransferSpec.newBuilder()
                    .setSourceAgentPoolName(sourceAgentPoolName)
                    .setPosixDataSource(
                        PosixFilesystem.newBuilder().setRootDirectory(rootDirectory).build())
                    .setGcsDataSink(GcsData.newBuilder().setBucketName(gcsSinkBucket).build()))
            .setStatus(TransferJob.Status.ENABLED)
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources,
    // or use "try-with-close" statement to do this automatically.
    try (StorageTransferServiceClient storageTransfer = StorageTransferServiceClient.create()) {

      // Create the transfer job
      TransferJob response =
          storageTransfer.createTransferJob(
              TransferProto.CreateTransferJobRequest.newBuilder()
                  .setTransferJob(transferJob)
                  .build());

      System.out.println(
          "Created a transfer job from "
              + rootDirectory
              + " to "
              + gcsSinkBucket
              + " with "
              + "name "
              + response.getName());
    }
  }
}

Node.js


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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// Your project id
// const projectId = 'my-project'

// The agent pool associated with the POSIX data source. Defaults to the default agent
// const sourceAgentPoolName = 'projects/my-project/agentPools/transfer_service_default'

// The root directory path on the source filesystem
// const rootDirectory = '/directory/to/transfer/source'

// The ID of the GCS bucket to transfer data to
// const gcsSinkBucket = 'my-sink-bucket'

// Creates a client
const client = new StorageTransferServiceClient();

/**
 * Creates a request to transfer from the local file system to the sink bucket
 */
async function transferDirectory() {
  const createRequest = {
    transferJob: {
      projectId,
      transferSpec: {
        sourceAgentPoolName,
        posixDataSource: {
          rootDirectory,
        },
        gcsDataSink: {bucketName: gcsSinkBucket},
      },
      status: 'ENABLED',
    },
  };

  // Runs the request and creates the job
  const [transferJob] = await client.createTransferJob(createRequest);

  const runRequest = {
    jobName: transferJob.name,
    projectId: projectId,
  };

  await client.runTransferJob(runRequest);

  console.log(
    `Created and ran a transfer job from '${rootDirectory}' to '${gcsSinkBucket}' with name ${transferJob.name}`
  );
}

transferDirectory();

Python

from google.cloud import storage_transfer


def transfer_from_posix_to_gcs(
    project_id: str,
    description: str,
    source_agent_pool_name: str,
    root_directory: str,
    sink_bucket: str,
):
    """Create a transfer from a POSIX file system to a GCS bucket."""

    client = storage_transfer.StorageTransferServiceClient()

    # The ID of the Google Cloud Platform Project that owns the job
    # project_id = 'my-project-id'

    # A useful description for your transfer job
    # description = 'My transfer job'

    # The agent pool associated with the POSIX data source.
    # Defaults to 'projects/{project_id}/agentPools/transfer_service_default'
    # source_agent_pool_name = 'projects/my-project/agentPools/my-agent'

    # The root directory path on the source filesystem
    # root_directory = '/directory/to/transfer/source'

    # Google Cloud Storage sink bucket name
    # sink_bucket = 'my-gcs-sink-bucket'

    transfer_job_request = storage_transfer.CreateTransferJobRequest(
        {
            "transfer_job": {
                "project_id": project_id,
                "description": description,
                "status": storage_transfer.TransferJob.Status.ENABLED,
                "transfer_spec": {
                    "source_agent_pool_name": source_agent_pool_name,
                    "posix_data_source": {
                        "root_directory": root_directory,
                    },
                    "gcs_data_sink": {"bucket_name": sink_bucket},
                },
            }
        }
    )

    result = client.create_transfer_job(transfer_job_request)
    print(f"Created transferJob: {result.name}")