Transfira de um sistema de ficheiros para o Cloud Storage

Esta página mostra como criar tarefas de transferência entre um sistema de ficheiros (nas instalações ou na nuvem) e o Cloud Storage.

As transferências de sistemas de ficheiros para o Cloud Storage são transferências baseadas em agentes, o que significa que instala agentes de software numa máquina com acesso ao seu sistema de ficheiros para orquestrar a transferência.

Configure autorizações

Antes de criar uma transferência, tem de configurar as autorizações para as seguintes entidades:

	A conta de utilizador que está a ser usada para criar a transferência. Esta é a conta com sessão iniciada na consola ou a conta especificada quando se autentica na CLI `gcloud`. Google Cloud A conta de utilizador pode ser uma conta de utilizador normal ou uma conta de serviço gerida pelo utilizador.
	A conta de serviço gerida pela Google, também conhecida como agente de serviço, usada pelo Serviço de Transferência de Armazenamento. Geralmente, esta conta é identificada pelo respetivo endereço de email, que usa o formato [e-mail].
	A conta de agente de transferência que concede Google Cloud autorizações aos agentes de transferência. As contas de agente de transferência usam as credenciais do utilizador que as instala ou as credenciais de uma conta de serviço gerida pelo utilizador para autenticar.

Consulte as autorizações de transferência baseadas em agentes para ver instruções.

Instale agentes num conjunto de agentes

As transferências baseadas em agentes usam agentes de software para orquestrar as transferências. Estes agentes têm de ser instalados numa máquina com acesso ao sistema de ficheiros envolvido na transferência.

Não inclua informações confidenciais, como informações de identificação pessoal (IIP) ou dados de segurança, no nome do conjunto de agentes ou no prefixo do ID do agente. Os nomes dos recursos podem ser propagados para os nomes de outros Google Cloud recursos e podem ser expostos a sistemas internos da Google fora do seu projeto.

1. Crie um grupo de agentes. Use a sua conta de utilizador para esta ação.
2. Instale agentes no conjunto de agentes. Use a sua conta de agente de transferência para esta ação.

Recomendamos que comece com 3 agentes no seu conjunto de agentes de origem. Quando a transferência estiver em curso, monitorize a velocidade de transferência. Pode adicionar mais agentes ao conjunto enquanto a transferência estiver em curso.

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

Opções de transferência

As seguintes funcionalidades do Serviço de transferência de armazenamento estão disponíveis para transferências de sistemas de ficheiros para o Cloud Storage.

Transfira ficheiros específicos através de um manifesto

Pode transmitir uma lista de ficheiros para o serviço de transferência de armazenamento agir. Consulte o artigo Transfira ficheiros ou objetos específicos através de um manifesto para ver detalhes.

Especifique a classe de armazenamento

Pode especificar a classe de armazenamento do Cloud Storage a usar para os seus dados no contentor de destino. Consulte as opções StorageClass para ver detalhes do REST ou use a flag --custom-storage-class com a CLI do Google Cloud.

Tenha em atenção que todas as definições da classe de armazenamento são ignoradas se o contentor de destino tiver o Autoclass ativado. Se o Autoclass estiver ativado, os objetos transferidos para o contentor são inicialmente definidos como armazenamento padrão.

Preservação de metadados

Quando transfere ficheiros de sistemas de ficheiros, o Serviço de transferência de armazenamento pode preservar opcionalmente determinados atributos como metadados personalizados. Se estes ficheiros forem posteriormente escritos novamente num sistema de ficheiros, o Serviço de transferência de armazenamento pode converter os metadados preservados novamente em atributos POSIX.

Consulte a secção Transferências do sistema de ficheiros POSIX do artigo Preservação de metadados para ver detalhes sobre os metadados que podem ser preservados e como configurar a transferência.

Faça a gestão da largura de banda da rede

Por predefinição, o serviço de transferência de armazenamento usa toda a largura de banda disponível para transferir ficheiros do seu sistema de ficheiros. Pode 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 ao nível do conjunto de agentes.

Consulte o artigo Gerir a largura de banda da rede para saber mais.

A sua conta de utilizador requer a função Administrador da Transferência de armazenamento (roles/storagetransfer.admin) para definir ou alterar os limites de largura de banda.

Registo

O Serviço de transferência de armazenamento suporta o Cloud Logging para o Serviço de transferência de armazenamento (recomendado), bem como os registos de transferência baseados em agentes.

Crie uma transferência

Não inclua informações confidenciais, como informações de identificação pessoal (IIP) ou dados de segurança, no nome da tarefa de transferência. Os nomes dos recursos podem ser propagados para os nomes de outros Google Cloud recursos e podem ser expostos a sistemas internos da Google fora do seu projeto.

O serviço de transferência de armazenamento oferece várias interfaces através das quais pode criar uma transferência.

Google Cloud consola

1. Aceda à página Serviço de transferência de armazenamento na Google Cloud consola.

   Aceda ao Serviço de transferência de armazenamento

2. Clique em Criar tarefa de transferência. É apresentada a página Criar tarefa de transferência.

3. Escolha Sistema de ficheiros POSIX como origem.

4. Selecione Cloud Storage como o tipo de destino e clique em Passo seguinte.

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

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

7. Clique em Passo seguinte.

8. No campo Bucket ou pasta, introduza o bucket de destino e (opcionalmente) o nome da pasta, ou clique em Procurar para selecionar um bucket numa lista de buckets existentes no seu projeto atual. Para criar um novo contentor, clique em Criar novo contentor.

9. Clique em Passo seguinte.

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

    Nota: o Serviço de Transferência de Armazenamento apresenta as programações das tarefas de transferência no seu fuso horário local, mas armazena essas horas no Tempo Universal Coordenado (UTC). Se for afetado pela mudança da hora (DST), pode ver uma alteração na programação da tarefa de transferência quando a DST começa ou termina.

11. Clique em Passo seguinte.

12. Escolha as definições para a tarefa de transferência.

    • No campo Descrição, introduza uma descrição da transferência. Como prática recomendada, introduza uma descrição significativa e exclusiva para poder distinguir os trabalhos.

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

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

      • Nunca: o serviço de transferência de armazenamento ignora a transferência de ficheiros da origem que tenham o mesmo nome que um ficheiro presente no destino.

      • Se for diferente: substitui os ficheiros de destino se o ficheiro de origem com o mesmo nome tiver valores de Etags ou de soma de verificação diferentes.

      • Sempre: substitui sempre os ficheiros de destino quando o ficheiro de origem tem o mesmo nome, mesmo que sejam idênticos.

    • Em Quando eliminar, selecione uma das seguintes opções:

      • Nunca: nunca elimina ficheiros da origem nem do destino.

      • Eliminar ficheiro da origem após a transferência: elimine os ficheiros da origem após a transferência para o destino. Se um ficheiro de origem não for transferido, por exemplo, porque já existe no destino, o ficheiro de origem não é eliminado.

        Importante: se não tiver uma cópia de segurança local, esta opção é uma ação não reversível.

      • Eliminar ficheiros do destino se também não estiverem na origem: se os ficheiros no contentor do Cloud Storage de destino também não estiverem na origem, elimine os ficheiros do contentor do Cloud Storage.

        Esta opção garante que o contentor do Cloud Storage de destino corresponde exatamente à sua origem.

    • Selecione se pretende ativar o registo no Cloud Storage e/ou ativar o registo no Cloud Logging. Consulte os artigos Registos de transferência do sistema de ficheiros e Cloud Logging para o Serviço de transferência de armazenamento para mais informações.

13. Para criar a tarefa de transferência, clique em Criar.

gcloud

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

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

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

Onde:

• SOURCE é um caminho absoluto a partir da raiz do sistema de ficheiros. Tem o prefixo posix://, pelo que o valor final vai incluir 3 barras invertidas. Por exemplo, posix:///tmp/data/.

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

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

As opções adicionais incluem:

• --do-not-run impede que o serviço de transferência de armazenamento execute a tarefa após o envio do comando. Para executar a tarefa, atualize-a para adicionar uma programação ou use jobs run para a iniciar manualmente.

• --manifest-file especifica o caminho para um ficheiro CSV no Cloud Storage que contém uma lista de ficheiros a transferir da sua origem. Para ver a formatação do ficheiro de manifesto, consulte o artigo Transfira ficheiros ou objetos específicos através de um manifesto.

• Informações da tarefa: pode especificar --name e --description.

• Schedule: especifique --schedule-starts, --schedule-repeats-every e --schedule-repeats-until ou --do-not-run.

• Opções de transferência: especifique se quer substituir os ficheiros de destino (--overwrite-when=different ou always) e se quer eliminar determinados ficheiros durante ou após a transferência (--delete-from=destination-if-unique ou source-after-transfer); especifique que valores de metadados preservar (--preserve-metadata); e, opcionalmente, defina 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 gcloud documentação de referência. Tenha em atenção que nem todas as opções são suportadas para transferências baseadas em agentes. As opções não suportadas contêm uma nota a este efeito no respetivo texto de ajuda.

REST

O exemplo seguinte mostra como usar o Serviço de transferência de armazenamento através da API REST.

Quando configura ou edita tarefas de transferência através da API Storage Transfer Service, a hora tem de estar em UTC. Para mais informações sobre como especificar a programação de uma tarefa de transferência, consulte o artigo Programação.

Para mover ficheiros de um sistema de ficheiros POSIX para um contentor 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 estiver incluído, a tarefa de transferência tem de ser iniciada com um pedido transferJobs.run.

Para verificar o estado da transferência depois de criar uma tarefa, use transferJobs.get:

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

Bibliotecas cliente

Os exemplos seguintes mostram como usar o Serviço de transferência de armazenamento através de programação com Go, Java, Node.js e Python.

Quando configura ou edita tarefas de transferência através de programação, a hora tem de estar em UTC. Para mais informações sobre como especificar a programação de uma tarefa de transferência, consulte o artigo Programação.

Para mais informações sobre as bibliotecas de cliente do serviço de transferência de armazenamento, consulte o artigo Introdução às bibliotecas de cliente do serviço de transferência de armazenamento.

Para mover ficheiros de um sistema de ficheiros POSIX para um contentor do Cloud Storage:

Ir

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