Transferir de um sistema de arquivos para o Cloud Storage

Nesta página, mostramos como criar jobs de transferência entre um sistema de arquivos (no local ou na nuvem) e o Cloud Storage.

As transferências de sistemas de arquivos para o Cloud Storage são baseadas em agentes, o que significa que você vai instalar agentes de software em uma máquina com acesso ao sistema de arquivos para organizar a transferência.

Pré-requisitos

Antes de configurar a transferência, verifique se você configurou o seguinte:

Instalar agentes em um pool de agentes

As transferências baseadas em agente usam agentes de software para orquestrar transferências. Esses agentes precisam ser instalados em uma máquina com acesso ao sistema de arquivos envolvido na transferência.

Não inclua informações sensíveis, como informações de identificação pessoal (PII, na sigla em inglês) ou dados de segurança no nome do pool de agentes ou no prefixo do ID do agente. Os nomes dos recursos podem ser propagados para os nomes de outros recursos do Google Cloud e podem ser expostos aos sistemas internos do Google fora do seu projeto.
  1. Crie um pool de agentes.
  2. Instale agentes no pool de agentes.

Recomendamos começar com três agentes no pool de origem. Quando a transferência estiver em andamento, monitore a velocidade. É possível adicionar mais agentes ao pool durante o processo.

Recomendamos uma VM por agente, cada uma com pelo menos 4 CPUs e 8 GiB de RAM.

Opções de transferência

Os seguintes recursos do Serviço de transferência do Cloud Storage estão disponíveis para transferências de sistemas de arquivos para o Cloud Storage.

Transferir arquivos específicos usando um manifesto
É possível transmitir uma lista de arquivos para o Serviço de transferência do Cloud Storage. Consulte Transferir arquivos ou objetos específicos usando um manifesto para mais detalhes.
Especificar classe de armazenamento
É possível especificar a classe de armazenamento do Cloud Storage a ser usada para os dados no bucket de destino. Consulte as opções de StorageClass para detalhes sobre REST ou use a flag --custom-storage-class com a Google Cloud CLI.

As configurações de classe de armazenamento serão ignoradas se o bucket de destino tiver a classe automática ativada. Se a classe automática estiver ativada, os objetos transferidos para o bucket serão inicialmente definidos como Standard Storage.

Preservação de metadados

Ao transferir arquivos de sistemas de arquivos, o Serviço de transferência do Cloud Storage pode preservar determinados atributos como metadados personalizados. Se esses arquivos forem posteriormente gravados em um sistema de arquivos, o Serviço de transferência do Cloud Storage poderá converter os metadados preservados de volta em atributos POSIX.

Consulte a seção Transferências do sistema de arquivos POSIX de Preservação de metadados para saber quais metadados podem ser preservados e como configurar sua transferência.

Gerenciar a largura de banda da rede
Por padrão, o Serviço de transferência do Cloud Storage usa toda a largura de banda disponível para transferir arquivos do seu sistema de arquivos. É possível definir um limite de largura de banda para evitar que uma transferência afete outro tráfego de rede. Os limites de largura de banda são aplicados no nível do pool de agentes.

Consulte Gerenciar largura de banda da rede para saber mais.

Sua conta de usuário precisa do papel Administrador de transferências do Cloud Storage (roles/storagetransfer.admin) para definir ou alterar limites de largura de banda.

Logging
O Serviço de transferência do Cloud Storage é compatível com o Cloud Logging para o Serviço de transferência do Cloud Storage (recomendado), bem como com os registros de transferência baseados em agente.

Criar uma transferência

Não inclua informações sensíveis, como informações de identificação pessoal (PII, na sigla em inglês) ou dados de segurança no nome do job de transferência. Os nomes dos recursos podem ser propagados para os nomes de outros recursos do Google Cloud e podem ser expostos aos sistemas internos do Google fora do seu projeto.

O Serviço de transferência do Cloud Storage oferece várias interfaces para criar uma transferência.

Console do Google Cloud

  1. Acesse a página Serviço de transferência do Cloud Storage no console do Google Cloud .

    Acessar o Serviço de transferência do Cloud Storage

  2. Clique em Criar job de transferência. Será exibida a página Criar um job de transferência.

  3. Escolha Sistema de arquivos POSIX como origem.

  4. Selecione Cloud Storage como o tipo de destino e clique em Próxima etapa.

  5. Selecione um pool de agentes atual ou selecione Criar um pool de agentes e siga as instruções para criar um novo pool.

  6. Especifique o caminho totalmente qualificado do diretório do sistema de arquivos.

  7. Clique em Próxima etapa.

  8. No campo Bucket ou pasta, insira o bucket de destino e, opcionalmente, o nome da pasta ou clique em Procurar para selecionar um bucket de uma lista de buckets no seu projeto atual. Para criar um novo bucket, clique em Ícone do bucket Criar novo bucket.

  9. Clique em Próxima etapa.

  10. Escolha as opções de programação.

  11. Clique em Próxima etapa.

  12. Escolha as configurações do job de transferência.

    • No campo Descrição, insira uma descrição da transferência. Como prática recomendada, insira uma descrição significativa e exclusiva para que você possa distinguir os jobs.

    • Em Opções de metadados, use as opções padrão ou atualize um ou mais valores. Consulte Preservação de metadados para mais detalhes.

    • Em Quando substituir, selecione uma destas opções:

      • Nunca: o Serviço de transferência do Cloud Storage ignora a transferência de arquivos da origem que têm o mesmo nome de um arquivo presente no destino.

      • Se diferente: substitui os arquivos de destino se o arquivo de origem com o mesmo nome tiver valores de ETags ou de checksum diferentes.

      • Sempre: sempre grava arquivos de destino quando o arquivo de origem tem o mesmo nome, mesmo que sejam idênticos.

    • Em Quando excluir, selecione uma destas opções:

      • Nunca: nunca exclua arquivos da origem ou do destino.

      • Excluir o arquivo da origem após a transferência: exclua os arquivos da origem após a transferência para o destino. Se um arquivo de origem não for transferido, por exemplo, porque ele já existe no destino, ele não será excluído.

      • Excluir arquivos do destino se eles não estiverem na origem: se os arquivos no bucket do Cloud Storage de destino também não estiverem na origem, exclua os arquivos do Cloud Storage. bucket.

        Essa opção garante que o bucket de destino do Cloud Storage corresponda exatamente à sua origem.

    • Selecione se você quer Ativar a geração de registros no Cloud Storage e/ou Ativar a geração de registros no Cloud Logging. Consulte Registros de transferência do sistema de arquivos e Cloud Logging para o Serviço de Transferência do Cloud Storage para mais informações.

  13. Para criar o job de transferência, clique em Criar.

gcloud

Antes de usar os comandos gcloud, instale a Google Cloud CLI.

Para criar um novo job de transferência, use o comando gcloud transfer jobs create. A criação de um novo job inicia a transferência especificada, a menos que uma programação ou --do-not-run seja especificado.

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

Substitua:

  • SOURCE é um caminho absoluto da raiz do sistema de arquivos. Ele tem o prefixo posix://, então o valor final inclui três barras. Por exemplo, posix:///tmp/data/.

  • DESTINATION é o nome de um bucket do Cloud Storage e, opcionalmente, um caminho de pasta seguido por uma barra final. Por exemplo, gs://example-bucket/data/.

  • --source-agent-pool especifica o pool de agentes de origem a ser usado para esta transferência.

As opções adicionais incluem:

  • --do-not-run impede que o Serviço de transferência do Cloud Storage execute o job após o envio do comando. Para executar o job, atualize-o para adicionar uma programação ou use jobs run para iniciá-lo manualmente.

  • --manifest-file especifica o caminho para um arquivo CSV no Cloud Storage contendo uma lista de arquivos a serem transferidos da sua origem. Para formatar o arquivo de manifesto, consulte Transferir arquivos ou objetos específicos usando um manifesto.

  • Informações do job: é possível especificar --name e --description.

  • Programação: especifique --schedule-starts, --schedule-repeats-every e --schedule-repeats-until ou --do-not-run.

  • Opções de transferência: especifique se você quer substituir os arquivos de destino (--overwrite-when=different ou always) e se quer excluir determinados arquivos durante ou após a transferência (--delete-from=destination-if-unique ou source-after-transfer), especificar quais valores de metadados preservar (--preserve-metadata) e, opcionalmente, definir uma classe de armazenamento em objetos transferidos (--custom-storage-class).

Para ver todas as opções, execute gcloud transfer jobs create --help ou consulte a documentação de referência de gcloud. Nem todas as opções são compatíveis com transferências baseadas em agente. As opções não compatíveis contêm uma observação sobre isso no texto de ajuda.

REST

O exemplo a seguir mostra como usar o Serviço de transferência do Cloud Storage com a API REST.

Ao configurar ou editar os jobs de transferência usando a API Serviço de transferência do Cloud Storage, o horário precisa estar em UTC. Saiba como especificar a programação de um job de transferência em Programação.

Para mover arquivos de um sistema de arquivos POSIX para um bucket do Cloud Storage, use transferJobs.create com um 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/"
     }
  }
}

O campo schedule é opcional. Se não for incluído, o job de transferência precisará ser iniciado com uma solicitação transferJobs.run.

Para verificar o status da transferência após a criação de um job, use transferJobs.get:

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

Bibliotecas de cliente

Veja nas amostras a seguir como usar o Serviço de transferência do Cloud Storage de maneira programática com Go, Java, Node.js e Python.

Ao configurar ou editar jobs de transferência de maneira programática, o horário precisa estar em UTC. Saiba como especificar a programação de um job de transferência em Programação.

Para mais informações sobre as bibliotecas de cliente do Serviço de transferência do Cloud Storage, consulte Primeiros passos com as bibliotecas de cliente do Serviço de transferência do Cloud Storage.

Para mover arquivos de um sistema de arquivos POSIX para um bucket do Cloud Storage:

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}")