Transfira entre contentores do Cloud Storage

O Serviço de transferência de armazenamento pode ser usado para transferir grandes quantidades de dados entre contentores do Cloud Storage, no mesmo Google Cloud projeto ou entre projetos diferentes.

As migrações de contentores são úteis em vários cenários. Podem ser usadas para consolidar dados de projetos separados, mover dados para uma localização de cópia de segurança ou alterar a localização dos seus dados.

Quando usar o Serviço de transferência de armazenamento

Google Cloud oferece várias opções para transferir dados entre contentores de armazenamento na nuvem. Recomendamos as seguintes diretrizes:

  • Transferir menos de 1 TB: use o gcloud. Para ver instruções, consulte o artigo Mova e mude o nome dos contentores.

  • Transferir mais de 1 TB: use o Serviço de transferência de armazenamento. O serviço de transferência de armazenamento é uma opção de transferência gerida que oferece segurança, fiabilidade e desempenho imediatos. Elimina a necessidade de otimizar e manter scripts, e processar novas tentativas.

Este guia aborda as práticas recomendadas ao transferir dados entre contentores do Cloud Storage através do Serviço de transferência de armazenamento.

Defina uma estratégia de transferência

O aspeto da sua estratégia de transferência depende da complexidade da sua situação. Certifique-se de que inclui as seguintes considerações no seu plano.

Escolha um nome do contentor

Para mover os seus dados para um contentor de armazenamento com uma localização diferente, escolha uma das seguintes abordagens:

  • Novo nome do contentor. Atualize as suas aplicações para apontarem para um contentor de armazenamento com um nome diferente.
  • Manter nome do contentor. Substituir o contentor de armazenamento para manter o nome atual, o que significa que não tem de atualizar as suas aplicações.

Em ambos os casos, deve planear o tempo de inatividade e dar aos utilizadores um aviso adequado de que o tempo de inatividade se aproxima. Reveja as seguintes explicações para compreender que escolha é mais adequada para si.

Nome do novo contentor

Com um novo nome do contentor, tem de atualizar todo o código e os serviços que usam o seu contentor atual. A forma como o faz depende da forma como as suas aplicações são criadas e implementadas.

Para determinadas configurações, esta abordagem pode ter menos tempo de inatividade, mas requer mais trabalho para garantir uma transição sem problemas. Envolve os seguintes passos:

  1. Copiar os seus dados para um novo contentor de armazenamento.
  2. A iniciar o período de descanso.
  3. Atualizar as suas aplicações para apontarem para o novo contentor.
  4. Verificar se tudo funciona como esperado e se todos os sistemas e contas relevantes têm acesso ao contentor.
  5. Eliminar o contentor original.
  6. Terminar o período de descanso.

Manter o nome do contentor

Use esta abordagem se preferir não alterar o código para apontar para um novo nome do contentor. Envolve os seguintes passos:

  1. Copiar os seus dados para um contentor de armazenamento temporário.
  2. A iniciar o período de descanso.
  3. Eliminar o contentor original.
  4. Criar um novo contentor com o mesmo nome do contentor original.
  5. Copiar os dados para o novo contentor a partir do contentor temporário.
  6. Eliminar o contentor temporário.
  7. Verificar se tudo funciona como esperado e se todos os sistemas e contas relevantes têm acesso ao contentor.
  8. Terminar o período de descanso.

Minimize o tempo de inatividade

O Serviço de transferência de armazenamento não bloqueia as leituras nem as escritas nos contentores de origem ou de destino durante uma transferência.

Se optar por bloquear manualmente as leituras/escritas no seu contentor, pode minimizar o tempo de inatividade transferindo os dados em dois passos: inicialização e sincronização.

  1. Transferência inicial: faça uma transferência em massa sem bloquear a leitura/escrita na origem.

  2. Transferência de sincronização: após a conclusão da primeira execução, bloqueie a leitura/escrita no contentor de origem e faça outra transferência. As transferências do Serviço de transferência de armazenamento são incrementais por predefinição, pelo que esta segunda transferência só transfere os dados que foram alterados durante a transferência inicial.

Otimize a velocidade de transferência

Ao estimar a duração de uma tarefa de transferência, considere os possíveis estrangulamentos. Por exemplo, se a origem tiver milhares de milhões de ficheiros pequenos, a velocidade de transferência vai estar limitada pelo QPS. Se os tamanhos dos objetos forem grandes, a largura de banda pode ser o fator limitativo.

Os limites de largura de banda são definidos ao nível da região e são atribuídos de forma justa a todos os projetos. Se estiver disponível largura de banda suficiente, o Serviço de transferência de armazenamento pode concluir cerca de 1000 tarefas por trabalho de transferência por segundo. Neste caso, pode acelerar uma transferência dividindo a tarefa em várias tarefas de transferência pequenas, por exemplo, usando prefixos de inclusão e exclusão para transferir determinados ficheiros.

Nos casos em que a localização, a classe de armazenamento e a chave de encriptação são iguais, o serviço de transferência de armazenamento não cria uma nova cópia dos bytes. Em vez disso, cria uma nova entrada de metadados que aponta para o blob de origem. Como resultado, as cópias da mesma localização e classe de um grande conjunto de dados são concluídas muito rapidamente e estão apenas limitadas pelo QPS.

As eliminações também são operações apenas de metadados. Para estas transferências, a paralelização da transferência dividindo-a em várias tarefas pequenas pode aumentar a velocidade.

Preserve os metadados

Os seguintes metadados de objetos são preservados quando transfere dados entre contentores do Cloud Storage com o serviço de transferência de armazenamento:

  • Metadados personalizados criados pelo utilizador.
  • Campos de metadados de chave fixa do Cloud Storage, como Cache-Control, Content-Disposition, Content-Type e Custom-Time.
  • Tamanho do objeto.
  • O número de geração é preservado como um campo de metadados personalizado com a chave x-goog-reserved-source-generation, que pode editar ou remover posteriormente.

Os seguintes campos de metadados podem ser preservados opcionalmente durante a transferência através da API:

  • LCAs (acl)
  • Classe de armazenamento (storageClass)
  • CMEK (kmsKey)
  • Retenção temporária (temporaryHold)
  • Hora de criação do objeto (customTime)

Consulte a TransferSpec referência da API para mais detalhes.

Os seguintes campos de metadados não são preservados:

  • Última atualização (updated)
  • etag
  • componentCount

Se for preservado, o tempo de criação do objeto é armazenado como um campo personalizado, customTime. A hora de updated do objeto é reposta após a transferência, pelo que o tempo que o objeto passou na respetiva classe de armazenamento também é reposto. Isto significa que um objeto no armazenamento Coldline, após a transferência, tem de existir novamente durante 90 dias no destino para evitar cobranças de eliminação antecipada.

Pode aplicar as suas políticas de ciclo de vida baseadas em createTime usando customTime. Os valores customTime existentes são substituídos.

Para mais detalhes sobre o que é e o que não é preservado, consulte o artigo Preservação de metadados.

Processe objetos com versões

Se quiser transferir todas as versões dos seus objetos de armazenamento e não apenas a mais recente, tem de usar a CLI ou a API REST para transferir os seus dados, juntamente com a funcionalidade de manifesto do serviço de transferência de armazenamento.gcloud

Para transferir todas as versões de objetos:

  1. Liste os objetos do contentor e copie-os para um ficheiro JSON:

    gcloud storage ls --all-versions --recursive --json [SOURCE_BUCKET] > object-listing.json

    Normalmente, este comando apresenta cerca de 1000 objetos por segundo.

  2. Divida o ficheiro JSON em dois ficheiros CSV, um com as versões não atuais e outro com as versões ativas:

    jq -r '.[] | select( .type=="cloud_object" and (.metadata | has("timeDeleted") | not)) | [.metadata.name, .metadata.generation] | @csv' object-listing.json > live-object-manifest.csv
jq -r '.[] | select( .type=="cloud_object" and (.metadata | has("timeDeleted"))) | [.metadata.name, .metadata.generation] | @csv' object-listing.json > non-current-object-manifest.csv

  3. Ative o controlo de versões de objetos no contentor de destino.

  4. Transfira primeiro as versões não atuais transmitindo o ficheiro de manifesto non-current-object-manifest.csv como o valor do campo transferManifest.

  5. Em seguida, transfira as versões dinâmicas da mesma forma, especificando live-object-manifest.csv como o ficheiro de manifesto.

Configure as opções de transferência

Seguem-se algumas das opções disponíveis quando configura a transferência:

  • Registo: o Cloud Logging fornece registos detalhados de objetos individuais, o que lhe permite verificar o estado da transferência e realizar verificações adicionais de integridade de dados.

  • Filtragem: pode usar prefixos de inclusão e exclusão para limitar os objetos nos quais o Storage Transfer Service opera. Esta opção pode ser usada para dividir uma transferência em várias tarefas de transferência para que possam ser executadas em paralelo. Consulte o artigo Otimize a velocidade de transferência para mais informações.

  • Opções de transferência: Pode configurar a transferência para substituir os itens existentes no contentor de destino, para eliminar objetos no destino que não existam no conjunto de transferência ou para eliminar objetos transferidos da origem.

Transfira os seus dados

Depois de definir a estratégia de transferência, pode fazer a transferência propriamente dita.

Crie um novo contentor

Antes de iniciar a transferência, crie um contentor de armazenamento. Consulte location_considerations para obter ajuda na escolha de uma localização de contentor adequada.

Pode querer copiar alguns dos metadados do contentor quando criar o novo contentor. Consulte o artigo Obtenha metadados do contentor para saber como apresentar os metadados do contentor de origem, para que possa aplicar as mesmas definições ao seu novo contentor.

Copie objetos para o novo contentor

Pode copiar objetos do contentor de origem para um novo contentor através daGoogle Cloud consola, da gcloudCLI, da API REST ou das bibliotecas cliente. A abordagem que escolher depende da sua estratégia de transferência.

As instruções seguintes destinam-se ao exemplo de utilização básico de transferência de objetos de um contentor para outro e devem ser modificadas para se adequarem às suas necessidades.

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.

Google Cloud consola

Use o Serviço de transferência do Cloud Storage a partir da Google Cloud consola:

  1. Abra a página de transferência na Google Cloud consola.

    Abra a página Transferir

  2. Clique em Criar tarefa de transferência.

  3. Siga as instruções passo a passo e clique em Passo seguinte à medida que conclui cada passo:

    • Comece a usar o Google Cloud Storage como Tipo de origem e Tipo de destino.

    • Escolha uma origem: introduza diretamente o nome do contentor pretendido ou clique em Procurar para encontrar e selecionar o contentor pretendido.

    • Escolha um destino: introduza diretamente o nome do contentor pretendido ou clique em Procurar para encontrar e selecionar o contentor pretendido.

    • Escolha as definições: selecione a opção Eliminar ficheiros da origem após a transferência.

    • Opções de agendamento: pode ignorar esta secção.

  4. Depois de concluir o passo a passo, clique em Criar.

    Isto inicia o processo de cópia de objetos do seu contentor antigo para o novo. Este processo pode demorar algum tempo. No entanto, depois de clicar em Criar, pode sair da Google Cloud consola.

    Para ver o progresso da transferência:

    Abra a página de transferência na Google Cloud consola.

    Abra a página Transferir

    Para saber como obter informações detalhadas sobre erros relacionados com operações falhadas do serviço de transferência de armazenamento na Google Cloud consola, consulte a secção Resolução de problemas.

  5. Após a conclusão da transferência, não tem de fazer nada para eliminar os objetos do seu contentor antigo se tiver selecionado a caixa de verificação Eliminar objetos de origem após a conclusão da transferência durante a configuração. No entanto, pode querer eliminar o seu antigo contentor, o que tem de fazer separadamente.

CLI gcloud

Instale a CLI gcloud

Se ainda não o fez, instale a ferramenta de linhas de comando gcloud.

Em seguida, chame gcloud init para inicializar a ferramenta e especificar o ID do projeto e a conta de utilizador. Consulte o artigo Inicializar o SDK do Google Cloud para ver mais detalhes.

gcloud init

Adicione a conta de serviço à pasta de destino

Tem de adicionar a conta de serviço do serviço de transferência de armazenamento ao seu contentor de destino antes de criar uma transferência. Para o fazer, use gcloud storage buckets add-iam-policy-binding:

gcloud storage buckets add-iam-policy-binding gs://bucket_name \
--member=serviceAccount:project-12345678@storage-transfer-service.iam.gserviceaccount.com \
--role=roles/storage.admin

Para ver instruções sobre como usar a Google Cloud consola ou a API, consulte o artigo Use autorizações de IAM na documentação do Cloud Storage.

Crie a tarefa de transferência

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 SOURCE DESTINATION

Onde:

  • SOURCE é a origem de dados desta transferência, no formato gs://BUCKET_NAME.

  • DESTINATION é o seu novo contentor, no formato gs://BUCKET_NAME.

As opções adicionais incluem:

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

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

  • Condições de objetos: use condições para determinar que objetos são transferidos. Estes incluem --include-prefixes e --exclude-prefixes, e as condições baseadas no tempo em --include-modified-[before | after]-[absolute | relative].

  • 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).

  • Notificações: configure as notificações do Pub/Sub para transferências com --notification-pubsub-topic, --notification-event-types e --notification-payload-format.

Para ver todas as opções, execute gcloud transfer jobs create --help.

Por exemplo, para transferir todos os objetos com o prefixo folder1:

gcloud transfer jobs create gs://old-bucket gs://new-bucket \
  --include-prefixes="folder1/"

REST

Neste exemplo, vai aprender a mover ficheiros de um contentor do Cloud Storage para outro. Por exemplo, pode mover dados para um contentor noutra localização.

Pedido através de transferJobs create:

POST https://storagetransfer.googleapis.com/v1/transferJobs
{
  "description": "YOUR DESCRIPTION",
  "status": "ENABLED",
  "projectId": "PROJECT_ID",
  "schedule": {
      "scheduleStartDate": {
          "day": 1,
          "month": 1,
          "year": 2025
      },
      "startTimeOfDay": {
          "hours": 1,
          "minutes": 1
      },
      "scheduleEndDate": {
          "day": 1,
          "month": 1,
          "year": 2025
      }
  },
  "transferSpec": {
      "gcsDataSource": {
          "bucketName": "GCS_SOURCE_NAME"
      },
      "gcsDataSink": {
          "bucketName": "GCS_SINK_NAME"
      },
      "transferOptions": {
          "deleteObjectsFromSourceAfterTransfer": true
      }
  }
}

Resposta:

200 OK
{
  "transferJob": [
      {
          "creationTime": "2015-01-01T01:01:00.000000000Z",
          "description": "YOUR DESCRIPTION",
          "name": "transferJobs/JOB_ID",
          "status": "ENABLED",
          "lastModificationTime": "2015-01-01T01:01:00.000000000Z",
          "projectId": "PROJECT_ID",
          "schedule": {
              "scheduleStartDate": {
                  "day": 1,
                  "month": 1,
                  "year": 2015
              },
              "startTimeOfDay": {
                  "hours": 1,
                  "minutes": 1
              }
          },
          "transferSpec": {
              "gcsDataSource": {
                  "bucketName": "GCS_SOURCE_NAME",
              },
              "gcsDataSink": {
                  "bucketName": "GCS_NEARLINE_SINK_NAME"
              },
              "objectConditions": {
                  "minTimeElapsedSinceLastModification": "2592000.000s"
              },
              "transferOptions": {
                  "deleteObjectsFromSourceAfterTransfer": true
              }
          }
      }
  ]
}

Bibliotecas cliente

Neste exemplo, vai aprender a mover ficheiros de um contentor do Cloud Storage para outro. Por exemplo, pode replicar dados para um contentor noutra localizaçã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.

Java

Procura exemplos mais antigos? Consulte o guia de migração do Serviço de transferência de armazenamento. 

import com.google.protobuf.Duration;
import com.google.storagetransfer.v1.proto.StorageTransferServiceClient;
import com.google.storagetransfer.v1.proto.TransferProto.CreateTransferJobRequest;
import com.google.storagetransfer.v1.proto.TransferTypes.GcsData;
import com.google.storagetransfer.v1.proto.TransferTypes.ObjectConditions;
import com.google.storagetransfer.v1.proto.TransferTypes.Schedule;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferJob;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferJob.Status;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferOptions;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferSpec;
import com.google.type.Date;
import com.google.type.TimeOfDay;
import java.io.IOException;
import java.util.Calendar;

public class TransferToNearline {
  /**
   * Creates a one-off transfer job that transfers objects in a standard GCS bucket that are more
   * than 30 days old to a Nearline GCS bucket.
   */
  public static void transferToNearline(
      String projectId,
      String jobDescription,
      String gcsSourceBucket,
      String gcsNearlineSinkBucket,
      long startDateTime)
      throws IOException {

    // Your Google Cloud Project ID
    // String projectId = "your-project-id";

    // A short description of this job
    // String jobDescription = "Sample transfer job of old objects to a Nearline GCS bucket.";

    // The name of the source GCS bucket to transfer data from
    // String gcsSourceBucket = "your-gcs-source-bucket";

    // The name of the Nearline GCS bucket to transfer old objects to
    // String gcsSinkBucket = "your-nearline-gcs-bucket";

    // What day and time in UTC to start the transfer, expressed as an epoch date timestamp.
    // If this is in the past relative to when the job is created, it will run the next day.
    // long startDateTime =
    //     new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2000-01-01 00:00:00").getTime();

    // Parse epoch timestamp into the model classes
    Calendar startCalendar = Calendar.getInstance();
    startCalendar.setTimeInMillis(startDateTime);
    // Note that this is a Date from the model class package, not a java.util.Date
    Date date =
        Date.newBuilder()
            .setYear(startCalendar.get(Calendar.YEAR))
            .setMonth(startCalendar.get(Calendar.MONTH) + 1)
            .setDay(startCalendar.get(Calendar.DAY_OF_MONTH))
            .build();
    TimeOfDay time =
        TimeOfDay.newBuilder()
            .setHours(startCalendar.get(Calendar.HOUR_OF_DAY))
            .setMinutes(startCalendar.get(Calendar.MINUTE))
            .setSeconds(startCalendar.get(Calendar.SECOND))
            .build();

    TransferJob transferJob =
        TransferJob.newBuilder()
            .setDescription(jobDescription)
            .setProjectId(projectId)
            .setTransferSpec(
                TransferSpec.newBuilder()
                    .setGcsDataSource(GcsData.newBuilder().setBucketName(gcsSourceBucket))
                    .setGcsDataSink(GcsData.newBuilder().setBucketName(gcsNearlineSinkBucket))
                    .setObjectConditions(
                        ObjectConditions.newBuilder()
                            .setMinTimeElapsedSinceLastModification(
                                Duration.newBuilder().setSeconds(2592000 /* 30 days */)))
                    .setTransferOptions(
                        TransferOptions.newBuilder().setDeleteObjectsFromSourceAfterTransfer(true)))
            .setSchedule(Schedule.newBuilder().setScheduleStartDate(date).setStartTimeOfDay(time))
            .setStatus(Status.ENABLED)
            .build();

    // Create a Transfer Service client
    StorageTransferServiceClient storageTransfer = StorageTransferServiceClient.create();

    // Create the transfer job
    TransferJob response =
        storageTransfer.createTransferJob(
            CreateTransferJobRequest.newBuilder().setTransferJob(transferJob).build());

    System.out.println("Created transfer job from standard bucket to Nearline bucket:");
    System.out.println(response.toString());
  }
}

Python

Procura exemplos mais antigos? Consulte o guia de migração do Serviço de transferência de armazenamento. 

from datetime import datetime

from google.cloud import storage_transfer
from google.protobuf.duration_pb2 import Duration


def create_daily_nearline_30_day_migration(
    project_id: str,
    description: str,
    source_bucket: str,
    sink_bucket: str,
    start_date: datetime,
):
    """Create a daily migration from a GCS bucket to a Nearline GCS bucket
    for objects untouched for 30 days."""

    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'

    # Google Cloud Storage source bucket name
    # source_bucket = 'my-gcs-source-bucket'

    # Google Cloud Storage destination bucket name
    # sink_bucket = 'my-gcs-destination-bucket'

    transfer_job_request = storage_transfer.CreateTransferJobRequest(
        {
            "transfer_job": {
                "project_id": project_id,
                "description": description,
                "status": storage_transfer.TransferJob.Status.ENABLED,
                "schedule": {
                    "schedule_start_date": {
                        "day": start_date.day,
                        "month": start_date.month,
                        "year": start_date.year,
                    }
                },
                "transfer_spec": {
                    "gcs_data_source": {
                        "bucket_name": source_bucket,
                    },
                    "gcs_data_sink": {
                        "bucket_name": sink_bucket,
                    },
                    "object_conditions": {
                        "min_time_elapsed_since_last_modification": Duration(
                            seconds=2592000  # 30 days
                        )
                    },
                    "transfer_options": {
                        "delete_objects_from_source_after_transfer": True
                    },
                },
            }
        }
    )

    result = client.create_transfer_job(transfer_job_request)
    print(f"Created transferJob: {result.name}")

Valide os objetos copiados

Após a conclusão da transferência, recomendamos que execute verificações adicionais de integridade de dados.

  • Valide se os objetos foram copiados corretamente verificando os metadados dos objetos, como as somas de verificação e o tamanho.

  • Verifique se foi copiada a versão correta dos objetos. O Serviço de transferência de armazenamento oferece uma opção pronta a usar para verificar se os objetos são cópias. Se tiver ativado o registo, veja os registos para verificar se todos os objetos foram copiados com êxito, incluindo os respetivos campos de metadados.

Comece a usar o contentor de destino

Após a conclusão e a validação da migração, atualize todas as aplicações ou cargas de trabalho existentes para que usem o nome do contentor de destino. Verifique os registos de acesso aos dados nos registos de auditoria do Cloud para garantir que as suas operações estão a modificar e a ler objetos corretamente.

Elimine o contentor original

Depois de tudo estar a funcionar bem, elimine o contentor original.

O Storage Transfer Service oferece a opção de eliminar objetos após terem sido transferidos, especificando deleteObjectsFromSourceAfterTransfer: true na configuração da tarefa ou selecionando a opção na consola. Google Cloud

Agende a eliminação de objetos

Para agendar a eliminação dos seus objetos numa data posterior, use uma combinação de uma tarefa de transferência agendada e a opção deleteObjectsUniqueInSink = true.

A tarefa de transferência deve ser configurada para transferir um contentor vazio para o contentor que contém os seus objetos. Isto faz com que o Serviço de transferência de armazenamento liste os objetos e comece a eliminá-los. Como as eliminações são uma operação apenas de metadados, a tarefa de transferência está apenas limitada por QPS. Para acelerar o processo, divida a transferência em várias tarefas, cada uma atuando num conjunto distinto de prefixos.

Em alternativa, Google Cloud oferece um agendador de tarefas cronológicas gerido. Para mais informações, consulte o artigo Agende uma tarefa de transferência do STS do Google Cloud com o Cloud Scheduler.