O Serviço de transferência do Cloud Storage pode detectar notificações de eventos em Google Cloud para transferir automaticamente dados que foram adicionados ou atualizados em um bucket do Cloud Storage. Saiba mais sobre os benefícios das transferências baseadas em eventos.
As transferências orientadas por eventos do Cloud Storage usam notificações do Pub/Sub para saber quando os objetos no bucket de origem foram modificados ou adicionados. As exclusões de objetos não são detectadas. Excluir um objeto na origem não exclui o objeto associado no bucket de destino.
As transferências baseadas em eventos sempre usam um bucket do Cloud Storage como destino.
Configurar permissões
Encontre o nome do agente de serviço do Serviço de transferência do Cloud Storage para seu projeto:
Acesse a página de referência de
googleServiceAccounts.get
.Você verá um painel interativo com o título Testar este método.
No painel, em Parâmetros de solicitação, insira o ID do projeto. O projeto especificado aqui precisa ser o projeto que você está usando para gerenciar o Serviço de transferência do Cloud Storage, que pode ser diferente do projeto do bucket de origem.
Clique em Execute.
O e-mail do agente de serviço é retornado como o valor de
accountEmail
. Copie esse valor.O e-mail do agente de serviço tem o formato
project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com
.Conceda esse papel ao
Pub/Sub Subscriber
agente do Serviço de transferência do Cloud Storage.Console do Cloud
Siga as instruções em Como controlar o acesso usando o console do Google Cloud para conceder o papel
Pub/Sub Subscriber
ao serviço de serviço de transferência do Cloud Storage. O papel pode ser concedido no nível do tópico, da assinatura ou do projeto.CLI
gcloud
Siga as instruções em Definir uma política para adicionar a seguinte vinculação:
{ "role": "roles/pubsub.subscriber", "members": [ "serviceAccount:project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com" }
Configurar o Pub/Sub
Verifique se você atende aos Pré-requisitos para usar o Pub/Sub com o Cloud Storage.
Crie uma notificação do Pub/Sub para o bucket de origem do Cloud Storage.
Não é possível gerenciar notificações do Pub/Sub com o Google Cloud console. Use a CLI gcloud ou uma das bibliotecas de cliente disponíveis.
gcloud storage buckets notifications create gs://SOURCE_BUCKET_NAME --topic=TOPIC_NAME
Crie uma assinatura de pull para o tópico. É necessário criar uma assinatura separada para cada job de transferência.
O exemplo a seguir mostra o comando da Google Cloud CLI para criar uma assinatura de pull. Para instruções do console e código da biblioteca de cliente, consulte Criar uma assinatura de pull.
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_NAME --ack-deadline=300
Criar um job de transferência
Use a API REST ou o console do Google Cloud para criar um job de transferência baseado em eventos.
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 Google Cloud e podem ser expostos aos sistemas internos do Google fora do seu projeto.
Console do Cloud
Acesse a página Criar job de transferência no console Google Cloud .
Selecione Cloud Storage como origem e destino.
No Modo de programação, selecione Baseado em eventos e clique em Próxima etapa.
Selecione o bucket de origem dessa transferência.
Na seção Fluxo de eventos, insira o nome da assinatura:
projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID
Se quiser, defina qualquer filtro e clique em Próxima etapa.
Selecione o bucket de destino dessa transferência.
Também é possível digitar um horário de início e de término para a transferência. Se você não especificar um horário, a transferência vai ser iniciada imediatamente e executada até ser interrompida manualmente.
Especifique as opções de transferência. Veja mais informações na página Criar transferências.
Clique em Criar.
Depois de criado, o job de transferência começa a ser executado e um listener de eventos aguarda notificações na assinatura do Pub/Sub. A página de detalhes do job mostra uma operação a cada hora e contém detalhes sobre os dados transferidos em cada job.
REST
Para criar uma transferência baseada em eventos usando a API REST, envie o seguinte objeto JSON para o endpoint transferJobs.create:
transfer_job { "description": "YOUR DESCRIPTION", "status": "ENABLED", "projectId": "PROJECT_ID", "transferSpec" { "gcsDataSource" { "bucketName": "GCS_SOURCE_NAME" }, "gcsDataSink": { "bucketName": "GCS_SINK_NAME" } } "eventStream" { "name": "projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID", "eventStreamStartTime": "2022-12-02T01:00:00+00:00", "eventStreamExpirationTime": "2023-01-31T01:00:00+00:00" } }
O eventStreamStartTime
e o eventStreamExpirationTime
são opcionais.
Se o horário de início for omitido, a transferência começará imediatamente. Se o horário de
término for omitido, a transferência continuará até que seja interrompida manualmente.
Bibliotecas de cliente
Go
Para saber como instalar e usar a biblioteca de cliente do Serviço de transferência do Cloud Storage, consulte Bibliotecas de clientes do Serviço de transferência do Cloud Storage. Para mais informações, consulte a Documentação de referência da API Go do Serviço de transferência do Cloud Storage.
Para autenticar o Serviço de transferência do Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Serviço de transferência do Cloud Storage, consulte Bibliotecas de clientes do Serviço de transferência do Cloud Storage. Para mais informações, consulte a Documentação de referência da API Java do Serviço de transferência do Cloud Storage.
Para autenticar o Serviço de transferência do Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Serviço de transferência do Cloud Storage, consulte Bibliotecas de clientes do Serviço de transferência do Cloud Storage. Para mais informações, consulte a Documentação de referência da API Node.js do Serviço de transferência do Cloud Storage.
Para autenticar o Serviço de transferência do Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Serviço de transferência do Cloud Storage, consulte Bibliotecas de clientes do Serviço de transferência do Cloud Storage. Para mais informações, consulte a Documentação de referência da API Python do Serviço de transferência do Cloud Storage.
Para autenticar o Serviço de transferência do Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Monitorar uma transferência baseada em eventos
Quando você cria uma transferência orientada a eventos, o Serviço de transferência do Cloud Storage cria um job de transferência. Quando o horário de início é alcançado, uma operação de transferência começa a ser executada e um listener de eventos aguarda notificações da fila do Pub/Sub.
A operação de transferência é executada com um status de in progress
por aproximadamente
24 horas. Após 24 horas, a operação é concluída e uma nova é iniciada.
Uma nova operação é criada a cada 24 horas até que o horário de término do job de transferência seja alcançado ou até que o job seja interrompido manualmente.
Se uma transferência de arquivo estiver em andamento quando a operação estiver programada para ser concluída, a operação atual permanecerá em andamento até que o arquivo seja totalmente transferido. Uma nova operação é iniciada, e as duas são executadas simultaneamente até que a antiga seja concluída. Todos os eventos detectados durante esse período são processados pela nova operação.
Para conferir a operação atual e as concluídas:
Console do Google Cloud
Acesse a página Serviço de transferência do Cloud Storage no Google Cloud console.
Na lista de jobs, selecione a guia Todos ou Entre nuvens.
Clique no ID do job da transferência. A coluna Modo de programação identifica todas as transferências baseadas em eventos em comparação com as transferências em lote.
Selecione a guia Operações. Os detalhes são mostrados para a operação atual, e as operações concluídas são listadas na tabela Histórico de execução. Clique em qualquer operação concluída para conferir mais detalhes.
gcloud
Para monitorar o andamento de um job em tempo real, use
gcloud transfer jobs monitor
. A resposta mostra a operação atual, o horário de início do job, a quantidade de dados transferidos, os bytes ignorados e as contagens de erros.
gcloud transfer jobs monitor JOB_NAME
Para recuperar o nome da operação atual:
gcloud transfer jobs describe JOB_NAME --format="value(latestOperationName)"
Para listar as operações atuais e concluídas:
gcloud transfer operations list --job-names=JOB_NAME
Para conferir detalhes sobre uma operação:
gcloud transfer operations describe OPERATION_NAME