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 (seja no local ou na nuvem) e no 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 orquestrar a transferência.

Configurar permissões

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

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

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

Instalar agentes em um pool de agentes

As transferências baseadas em agentes 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 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. Use sua conta de usuário para essa ação.
2. Instalar agentes no pool de agentes. Use sua conta do agente de transferência para esta ação.

Recomendamos começar com três agentes no pool de agentes de origem. Depois que a transferência estiver em andamento, monitore a velocidade de transferência; é possível adicionar mais agentes no pool enquanto a transferência estiver em andamento.

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 de sistemas de arquivos para o Cloud Storage.

Transferir arquivos específicos usando um manifesto

Você pode transmitir uma lista de arquivos para que o Serviço de transferência do Cloud Storage realize ações. Consulte Transfira arquivos específicos ou objetos usando um manifesto para ver mais detalhes.

Especificar a 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 StorageClass para detalhes do REST ou use a flag --custom-storage-class com a CLI do Google Cloud.

Todas as configurações de classe de armazenamento são ignoradas se o bucket de destino tiver a Classe automática ativada. Se A classe automática está ativada, os objetos transferidos para o bucket são é definida como Standard Storage.

Preservação de metadados

Ao transferir arquivos de sistemas de arquivos, o Serviço de transferência do Cloud Storage pode como opção, é possível preservar determinados atributos como metadados personalizados. Se esses arquivos são gravados posteriormente em um sistema de arquivos, o Serviço de transferência do Cloud Storage pode os metadados preservados de volta aos atributos POSIX.

Consulte a seção Transferências do sistema de arquivos POSIX de Preservação de metadata para saber quais metadados podem ser preservados e como configurar a 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. Você pode definir um limite de largura de banda para impedir que uma transferência afete outro tráfego de rede. Limites de largura de banda são aplicadas no nível do pool de agentes.

Consulte Gerenciar largura de banda de rede para saber mais.

Sua conta de usuário precisa do papel Administrador de transferência 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 oferece suporte a Cloud Logging para o Serviço de transferência do Cloud Storage (recomendado), bem como baseado em agente registros de transferência.

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 mostra as programações dos 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 significativa e exclusiva para que você possa distinguir os jobs.

    • Em Opções de metadados, use as opções padrão, ou atualizar 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 Storage pula 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 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 Ative a geração de registros no Cloud Logging. Consulte Registros de transferência do sistema de arquivos e Cloud Logging para 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

Em que:

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

• DESTINATION é o nome de um bucket do Cloud Storage e, opcionalmente, um caminho de pasta seguido por um caractere de barra inclinada. 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. opções não suportadas contêm uma observação sobre isso no texto de ajuda.

REST

O exemplo a seguir mostra como usar o Storage Transfer Service pela API REST.

Ao configurar ou editar os 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}")