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 agente, o que significa que você instalará agentes de software em uma máquina com acesso ao seu sistema de arquivos para orquestrar a transferência.

Configurar permissões

Antes de criar uma transferência, você precisa configurar permissões para as entidades a seguir:

	A conta de usuário usada para criar a transferência Essa é a conta conectada ao console do Google Cloud ou a conta especificada ao autenticar na CLI "gcloud". A conta de usuário pode ser uma conta de usuário normal ou uma conta de serviço gerenciado pelo usuário.
	A conta serviço gerenciado pelo Google, também conhecida como agente de serviço, usada pelo Serviço de transferência do Cloud Storage. Essa conta geralmente é identificada pelo endereço de e-mail, que usa o formato [e-mail].
	A conta do agente de transferência que fornece permissões do Google Cloud para agentes de transferência. As contas do agente de transferência usam as credenciais do usuário que as instala ou de uma conta de serviço gerenciado pelo usuário para fazer a autenticação.

Consulte Permissões de transferência baseadas em agente para mais instruções.

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) ou dados de segurança, no nome do pool ou no prefixo de 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. Use sua conta de usuário para essa ação.
2. Instale agentes no pool de agentes. Use sua conta do agente de transferência para essa ação.

Recomendamos começar com três agentes no pool de agentes de origem. Monitore a velocidade da transferência quando a transferência estiver em andamento. É possível adicionar mais agentes ao pool enquanto a transferência está em andamento.

Recomendamos uma VM por agente, cada uma com no mínimo 4 CPUs e 8 GiB de RAM.

Opções de transferência

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

Transferir arquivos específicos usando um manifesto

Você pode transmitir uma lista de arquivos para o Serviço de transferência do Cloud Storage realizar ações. Para mais detalhes, consulte Transferir arquivos ou objetos específicos usando um manifesto.

Especificar a classe de armazenamento

É possível especificar a classe de armazenamento do Cloud Storage a ser usada para seus dados no bucket de destino. Consulte as opções de StorageClass para ver detalhes de REST ou use a sinalização --custom-storage-class com a Google Cloud CLI.

Todas as configurações da 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 gravados posteriormente 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 em Preservação de metadados para detalhes sobre 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 impedir 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 exige o papel Administrador de transferências do Storage (roles/storagetransfer.admin) para definir ou alterar os limites de largura de banda.

Geração de registros

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 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 fornece 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 a 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 Criar novo bucket.

9. Clique em Próxima etapa.

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

    Observação: o Serviço de transferência do Cloud Storage exibe as programações de jobs de transferência no fuso horário local, mas armazena esses horários no Tempo Universal Coordenado (UTC). Se você estiver em um local com horário de verão, poderá ocorrer uma alteração na programação dos jobs de transferência no início ou no fim do horário de verã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 que seja significativa e única para que você possa diferenciar 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 todos os arquivos da origem que tenham 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 soma de verificação 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.

        Importante: se você não tiver backup local, essa opção será uma ação não reversível.

      • 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 Ativar a geração de registros no Cloud Storage e/ou Ativar a geração de registros no Cloud Logging. Para mais informações, consulte Registros de transferência do sistema de arquivos e Cloud Logging para o Serviço de transferência do Cloud Storage.

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

Em que:

• SOURCE é um caminho absoluto da raiz do sistema de arquivos. Ele é prefixado com posix://. Portanto, o valor final incluirá 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. Observe que nem todas as opções são compatíveis com transferências baseadas em agente. As opções não aceitas contêm uma observação sobre esse efeito no texto de ajuda.

REST

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

Quando você configura ou edita jobs de transferência usando a API Storage Transfer Service, 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}")