Se usó la API de Cloud Translation para traducir esta página.

Transfiere de un sistema de archivos a Cloud Storage

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

Las transferencias de sistemas de archivos a Cloud Storage están basadas en agentes, lo que significa que instalarás agentes de software en una máquina con acceso a tu sistema de archivos para organizar la transferencia.

Configura permisos

Antes de crear una transferencia, debes configurar permisos para las siguientes entidades:

	La cuenta de usuario que se usa para crear la transferencia. Esta es la cuenta con la que se accedió a la consola de Google Cloud o la cuenta que se especifica cuando se realiza la autenticación en la CLI de “gcloud”. La cuenta de usuario puede ser una cuenta de usuario normal o una cuenta de servicio administrada por el usuario.
	La cuenta de servicio administrada por Google, también conocida como el agente de servicio, que usa el Servicio de transferencia de almacenamiento. Por lo general, esta cuenta se identifica por su dirección de correo electrónico, que usa el formato `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com`.
	La cuenta de agente de transferencia que proporciona permisos de Google Cloud para los agentes de transferencia. Las cuentas del agente de transferencia usan las credenciales del usuario que las instala o las credenciales de una cuenta de servicio administrada por el usuario para autenticarse.

Consulta Permisos de transferencia basados en agentes para obtener instrucciones.

Instala agentes en un grupo de agentes

Las transferencias basadas en agentes usan agentes de software para organizar las transferencias. Estos agentes deben instalarse en una máquina con acceso al sistema de archivos involucrado en la transferencia.

No incluyas información sensible, como información de identificación personal (PII) o datos de seguridad en el nombre del grupo de agentes o en el prefijo de ID del agente. Los nombres de los recursos se pueden propagar a los nombres de otros recursos de Google Cloud y se pueden exponer 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 transferencia para esta acción.

Recomendamos comenzar con 3 agentes en tu grupo de agentes de origen. Una vez que la transferencia está en curso, supervisa la velocidad de la transferencia. Puedes agregar más agentes al grupo mientras la transferencia está en curso.

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

Opciones de transferencia

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

Cómo transferir archivos específicos con un manifiesto

Puedes pasar una lista de archivos para que actúe el Servicio de transferencia de almacenamiento. Para obtener más información, consulta Cómo transferir objetos o archivos específicos con un manifiesto.

Especifica la clase de almacenamiento

Puedes especificar la clase de almacenamiento de Cloud Storage que se usará para tus datos en el bucket de destino. Consulta las opciones de StorageClass para obtener detalles de REST o usa la marca --custom-storage-class con Google Cloud CLI.

Ten en cuenta que cualquier configuración de clase de almacenamiento se ignora si el bucket de destino tiene habilitada la Clase automática. Si la Clase automática está habilitada, los objetos transferidos al bucket se configuran inicialmente en Standard Storage.

Conservación de metadatos

Cuando se transfieren archivos desde sistemas de archivos, el Servicio de transferencia de almacenamiento puede conservar de manera opcional ciertos atributos como metadatos personalizados. Si estos archivos se vuelven a escribir en un sistema de archivos, el Servicio de transferencia de almacenamiento puede volver a convertir los metadatos conservados en atributos POSIX.

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

Administra el ancho de banda de red

Según la configuración predeterminada, el Servicio de transferencia de almacenamiento usa 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 del grupo de agentes.

Consulta Cómo administrar el ancho de banda de red para obtener más información.

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

Logging

El Servicio de transferencia de almacenamiento es compatible con Cloud Logging para el Servicio de transferencia de almacenamiento (recomendado), así como con registros de transferencia basados en agentes.

Crear una transferencia

No incluyas información sensible, como información de identificación personal (PII) o datos de seguridad en el nombre de tu trabajo de transferencia. Los nombres de los recursos se pueden propagar a los nombres de otros recursos de Google Cloud y se pueden exponer a sistemas internos de Google fuera de tu proyecto.

El Servicio de transferencia de almacenamiento proporciona varias interfaces para crear una transferencia.

Consola de Google Cloud

Ve a la página Servicio de transferencia de almacenamiento en la consola de Google Cloud.

Ir al Servicio de transferencia de almacenamiento
Haz clic en Crear trabajo de transferencia. Se muestra la página Crea un trabajo de transferencia.
Elige Sistema de archivos POSIX como origen.
Selecciona Cloud Storage como el tipo de destino y haz clic en Paso siguiente.
Selecciona un grupo de agentes existente o selecciona Crear grupo de agentes y sigue las instrucciones para crear un grupo nuevo.
Especifica la ruta completamente calificada del directorio del sistema de archivos.
Haz clic en Próximo paso.
En el campo Bucket o carpeta, ingresa el bucket de destino y el nombre de la carpeta (opcional) o haz clic en Explorar para seleccionar un bucket de una lista de buckets existentes en tu proyecto actual. Para crear un bucket nuevo, haz clic en Crear bucket nuevo.
Haz clic en Próximo paso.
Elige tus opciones de programación.

Nota: El Servicio de transferencia de almacenamiento muestra los programas de trabajos de transferencia en tu zona horaria local, pero almacena esas horas en hora universal coordinada (UTC). Si te ves afectado por el horario de verano (DST), es posible que experimentes un cambio en el programa del trabajo de transferencia cuando comience o finalice el DST.
Haz clic en Próximo paso.
Elige la configuración del trabajo de transferencia.
- En el campo Descripción, ingresa una descripción de la transferencia. Como práctica recomendada, ingresa una descripción que sea significativa y única para que puedas diferenciar los trabajos.
- En Opciones de metadatos, usa las opciones predeterminadas o actualiza uno o más valores. Consulta Conservación de metadatos para obtener más detalles.
- En Cuándo reemplazar, selecciona una de las siguientes opciones:
  - Nunca: El Servicio de transferencia de almacenamiento omite la transferencia de archivos de la fuente que tengan el mismo nombre que un archivo presente en el destino.
  - Si es diferente: Reemplaza los archivos de destino si el archivo de origen con el mismo nombre tiene diferentes ETags o valores de suma de verificación.
  - Siempre: Siempre escribe archivos de destino cuando el archivo de origen tiene el mismo nombre, incluso si son idénticos.
- En Cuándo borrar, selecciona una de las siguientes opciones:
  - Nunca: Nunca borres archivos de origen o de destino.
  - Borrar archivos de la fuente después de la transferencia: Borra los archivos de la fuente después de transferirlos al destino.
    
    Importante: Si no tienes una copia de seguridad local, esta opción es una acción no reversible.
  - Borra los archivos del destino si no están también en el origen: Si los archivos en el bucket de Cloud Storage de destino no están también en el origen, borra los archivos del bucket de Cloud Storage.
    
    Esta opción garantiza que el bucket de destino de Cloud Storage coincida exactamente con tu fuente.
- Selecciona si deseas Habilitar el registro en Cloud Storage o Habilitar el registro en Cloud Logging. Consulta Registros de transferencia del sistema de archivos y Cloud Logging para el Servicio de transferencia de almacenamiento si deseas obtener más información.
Para crear tu trabajo de transferencia, haz clic en Crear.

`gcloud`

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

Para crear un nuevo trabajo de transferencia, usa el comando gcloud transfer jobs create. La creación de un trabajo nuevo inicia la transferencia especificada, a menos que se especifique un programa o --do-not-run.

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

Aquí:

SOURCE es una ruta de acceso absoluta desde la raíz del sistema de archivos. Tiene el prefijo posix://, por lo que el valor final incluirá 3 barras diagonales. Por ejemplo, posix:///tmp/data/.
DESTINATION es uno del nombre de un bucket de Cloud Storage y, de manera opcional, una ruta de acceso a la 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.

Las opciones adicionales incluyen:

--do-not-run evita que el Servicio de transferencia de almacenamiento ejecute el trabajo cuando se envía el comando. A fin de ejecutar el trabajo, actualízalo para agregar un programa o usa jobs run para iniciarlo de forma manual.
--manifest-file especifica la ruta a un archivo CSV en Cloud Storage, que contiene una lista de archivos para transferir de tu fuente. Para formatear archivos de manifiesto, consulta Transfiere archivos o objetos específicos con un manifiesto.
Información del trabajo: puedes especificar --name y --description.
Programa: Especifica --schedule-starts, --schedule-repeats-every, y --schedule-repeats-until o --do-not-run.
Opciones de transferencia: Especifica si deseas reemplazar los archivos de destino (--overwrite-when=different o always) y si deseas borrar ciertos archivos durante o después de la transferencia (--delete-from=destination-if-unique o source-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).

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 son compatibles con las transferencias basadas en agentes. Las opciones no compatibles contienen una nota a este efecto en su texto de ayuda.

REST

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

Cuando configuras o editas los trabajos de transferencia con la API del Servicio de transferencia de almacenamiento, la hora debe estar en UTC. Para obtener más información sobre cómo especificar la programación de un trabajo de transferencia, consulta Programa.

Para mover archivos de un sistema de archivos POSIX a un bucket 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, el trabajo de transferencia debe iniciarse con una solicitud transferJobs.run.

Para verificar 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 cliente

En los siguientes ejemplos, se muestra cómo usar el Servicio de transferencia de almacenamiento de manera programática con Go, Java, Node.js y Python.

Cuando configuras o editas los trabajos de transferencia de manera programática, la hora debe estar en UTC. Para obtener más información sobre cómo especificar la programación de un trabajo de transferencia, consulta Programa.

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.

Para mover archivos de un sistema de archivos POSIX a un bucket 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}")