Criar e gerenciar transferências de dados com a gcloud

Nesta página, mostramos como usar a ferramenta de linha de comando gcloud para configurar e gerenciar jobs de transferência.

Antes de começar

Faça o seguinte antes de criar um job de transferência:

  1. Confira se você tem acesso ao Serviço de transferência do Cloud Storage verificando se recebeu um dos seguintes papéis:

    • roles/owner
    • roles/editor
    • roles/storagetransfer.admin
    • roles/storagetransfer.user
    • Um papel personalizado que inclui, no mínimo, permissões roles/storagetransfer.user.

      Para mais informações sobre como adicionar e visualizar permissões no nível do projeto, consulte Como usar permissões do IAM com projetos.

    Para mais informações, consulte Como solucionar problemas de acesso.

    Para mais informações sobre papéis e permissões do IAM no serviço de transferência do Cloud Storage, consulte Controle de acesso usando papéis e permissões do IAM.

  2. Como configurar o acesso a origens de dados e coletores.

Configurar a ferramenta gcloud

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

Também é necessário instalar os componentes alpha para gcloud:

gcloud components install alpha

Em seguida, chame gcloud init para inicializar a ferramenta e especificar o ID do projeto e a conta do usuário. Consulte Como inicializar o SDK do Cloud para mais detalhes.

gcloud init

Neste documento, $PROJECT_ID é usado no exemplo de código para se referir ao nome exclusivo do seu projeto. É possível usar essa variável nos exemplos se você atribuir primeiro seu próprio ID do projeto à variável:

PROJECT_ID=$(gcloud config get-value project) && echo $PROJECT_ID

Criar um job de transferência

Para transferências entre nuvens

Para criar um novo job de transferência, use o comando gcloud alpha 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 alpha transfer jobs create \
  SOURCE DESTINATION \
    --source-creds-file=SOURCE_CREDS_FILE \
    --do-not-run

Em que:

  • SOURCE é a fonte de dados dessa transferência; O formato de cada origem é:

    • s3://BUCKET_NAME/FOLDER_PATH para um bucket do Amazon S3.
    • https://myaccount.blob.core.windows.net/CONTAINER_NAME para um contêiner do Microsoft Azure Storage.
    • gs://BUCKET_NAME para um bucket do Cloud Storage.
    • https://PATH_TO_URL_LIST para uma lista de URLs. URLs de HTTP também são aceitos.
  • DESTINATION é sempre um bucket do Cloud Storage, no formato gs://BUCKET_NAME.

  • --source-creds-file especifica o caminho relativo para um arquivo local na máquina que inclui credenciais da AWS ou do Azure para a origem da transferência. Para informações sobre formatação de arquivos de credenciais, consulte a referência do TransferSpec.

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

As opções adicionais incluem:

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

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

  • Condições de objeto: use condições para determinar quais objetos são transferidos. Eles incluem include-prefixes e exclude-prefixes, além das condições baseadas em tempo em include-modified-[before | after]-[absolute | relative].

  • Opções de substituição e exclusão: 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).

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

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

Por exemplo, para criar um job de transferência diário para mover dados modificados no último dia de s3://my-s3-bucket para um bucket do Cloud Storage chamado my-storage-bucket, execute:

gcloud alpha transfer jobs create \
  s3://my-s3-bucket gs://my-storage-bucket \
  --source-creds-file=/examplefolder/creds.txt \
  --include-modified-after-relative=1d \
  --schedule-repeats-every=1d`

Para transferências locais ou no sistema de arquivos

Se a transferência for de ou para um sistema de arquivos POSIX, incluindo sistemas de nuvem, como Filestore, siga estas instruções.

Primeiro, se você ainda não tiver um pool e agentes para essa transferência:

  1. Criar um pool de agentes:

    gcloud alpha transfer agent-pools create my-agent-pool
    
  2. Instale os agentes de transferência:

    gcloud alpha transfer agents install --pool=my-agent-pool --count=3
    

    Consulte Requisitos e práticas recomendadas do agente para determinar o número ideal de agentes para o ambiente.

    Para executar agentes usando uma chave de conta de serviço, use a opção --creds-file:

    gcloud alpha transfer agents install --pool=my-agent-pool --count=3 \
       --creds-file=/relative/path/to/service-account-key.json
    

    Para uma lista completa de sinalizações opcionais, execute gcloud alpha transfer agents install --help.

Em seguida, use o comando gcloud alpha transfer jobs create.

gcloud alpha transfer jobs create \
  SOURCE DESTINATION \
  --source-agent-pool=projects/$PROJECT_ID/agentPools/my-source-agent-pool \
  --destination-agent-pool=projects/$PROJECT_ID/agentPools/my-destination-agent-pool

Em que:

  • SOURCE e DESTINATION podem ser:

    • Um sistema de arquivos POSIX, no formato posix:///path/to/folder. Precisa ser um caminho absoluto da raiz da máquina host do agente.
    • Um bucket do Cloud Storage, no formato gs://bucket-name.
    • Um bucket do Amazon S3 ou um contêiner do Microsoft Azure Storage.
  • --source-agent-pool especifica o pool de agentes de origem a ser usado para esta transferência.

  • --destination-agent-pool especifica o pool de agentes de destino a ser usado nesta transferência. Para mais detalhes, consulte Fazer o download de dados do Cloud Storage.

Apenas um de --source-agent-pool ou --destination-agent-pool pode ser especificado para uma transferência.

As opções adicionais incluem:

  • 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 substituição e exclusão: 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).

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

As condições de objeto (opções que começam com --include- ou --exclude-) não são compatíveis com transferências que envolvem sistemas de arquivos POSIX.

Por exemplo, para criar um job de transferência para mover dados de um sistema de arquivos local para um bucket do Google Cloud Storage chamado my-unique-bucket, execute:

gcloud alpha transfer jobs create \
  posix:///usr/local/my_dir gs://my-unique-bucket \
  --source-agent-pool=projects/$PROJECT_ID/agentPools/my-agent-pool`

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

Editar uma configuração de transferência

Para editar uma configuração de transferência existente, use o comando gcloud alpha transfer jobs update.

gcloud alpha transfer jobs update \
  JOB_NAME \
  [options]

Em que:

  • JOB_NAME é o nome exclusivo do job a ser atualizado.

  • As opções que podem ser atualizadas são listadas executando gcloud alpha transfer jobs update --help.

Por exemplo, para atualizar a origem e o destino de um job e remover a descrição dele, execute o seguinte comando:

gcloud alpha transfer jobs update \
  JOB_NAME \
  --source=gs://new-bucket-1 \
  --destination=gs://new-bucket-2 \
  --clear-description

Para desativar um job de transferência:

gcloud alpha transfer jobs update JOB_NAME --status=disabled

Executar um job de transferência a partir de uma configuração existente

Para executar uma transferência a partir de uma configuração existente, use gcloud alpha transfer jobs run:

gcloud alpha transfer jobs run JOB_NAME

A sinalização --no-async opcional pode ser especificada para bloquear outras tarefas no seu terminal até que a operação de transferência seja concluída.

Monitorar um job de transferência

Para monitorar o andamento de um job em tempo real, use gcloud alpha transfer jobs monitor.

gcloud alpha transfer jobs monitor JOB_NAME

A resposta mostra a operação atual, o horário de início do job e a quantidade de dados transferidos. Bytes e erros ignorados também são contados.

Ver detalhes do job de transferência

Para visualizar os detalhes do job de transferência, use gcloud alpha transfer jobs describe:

gcloud alpha transfer jobs describe JOB_NAME

Para ver a operação mais recente desse job, transmita o valor de latestOperationName para o comando operations describe:

gcloud alpha transfer operations describe OPERATION_NAME

Para listar todas as operações de transferência de um job, use o comando gcloud alpha transfer operations list:

gcloud alpha transfer operations list --job-names=JOB_NAME

Para ver as operações de vários jobs, liste-os, separados por vírgulas, como o valor de --job-names. Omita --job-names para ver as operações de todos os jobs.

Pausar um job de transferência

Você pode pausar uma transferência em andamento. Quando você pausa a transferência, o estado do job é mantido, e é possível retomá-lo mais tarde. Enquanto uma transferência estiver pausada, a programação não acionará o job para ser executada novamente.

Para pausar um job de transferência, transmita o nome da operação atual do job para gcloud alpha transfer operations pause.

gcloud alpha transfer operations pause OPERATION_NAME

Para retomar um job de transferência pausado anteriormente, que reinicia o job no mesmo local em que estava quando foi pausado, use gcloud alpha transfer operations resume.

gcloud alpha transfer operations resume OPERATION_NAME

Desativar um job de transferência

Desativar um job de transferência impede que o job inicie outras operações programadas ou as operações iniciadas manualmente no console. Isso não impede que um job seja iniciado manualmente com a API ou com o comando gcloud jobs run.

Para desativar um job de transferência, atualize o status dele para disabled.

gcloud alpha transfer jobs update JOB_NAME --status=disabled

Para reativar um job, defina --status=enabled.

Excluir um job de transferência

É possível excluir jobs de transferência que não são mais necessários. A exclusão de um job faz o seguinte:

  • Interrompe todas as transferências existentes que fazem parte do job.
  • Interrompe as transferências recorrentes que fazem parte do job.
  • Apaga os detalhes de configuração do job.

A exclusão de um job é permanente. Depois de excluir o job, ele será removido da lista. As informações do job de transferência são totalmente excluídas do serviço de transferência do Cloud Storage após 30 dias.

Para excluir um job de transferência, use gcloud alpha transfer jobs delete.

gcloud alpha transfer jobs delete JOB_NAME