O Serviço de transferência do Cloud Storage pode detectar notificações de eventos no 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
Além das
permissões necessárias para todos os jobs de transferência,
as transferências orientadas a eventos exigem o papel Pub/Sub Subscriber.
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..Conceda esse papel ao
Pub/Sub Subscriberagente 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 Subscriberao 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
gcloudSiga 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." }
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 console do Google Cloud . 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 por pull no 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 por pull. Para instruções do console e código da biblioteca de cliente, consulte Criar uma assinatura por pull.
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_NAME --ack-deadline=300
Criar um job de transferência
Use o console do Google Cloud , a Google Cloud CLI ou a API REST para criar um job de transferência baseado em eventos.
Console do Google Cloud
Acesse a página Criar job de transferência no console do 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_IDSe 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 a transferência de dados em cada job.
gcloud
Para criar um job de transferência orientado por eventos usando a Google Cloud CLI, use
o comando gcloud transfer jobs create com a
flag --event-stream-name:
gcloud transfer jobs create \
gs://SOURCE_BUCKET \
gs://DESTINATION_BUCKET \
--event-stream-name=projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID \
--event-stream-starts=EVENT_STREAM_STARTS \
--event-stream-expires=EVENT_STREAM_EXPIRES
Substitua os marcadores de posição pelos valores reais:
- SOURCE_BUCKET: o nome do bucket do Cloud Storage de origem.
- DESTINATION_BUCKET: o bucket do Cloud Storage de destino.
- PROJECT_NAME: o projeto que contém a assinatura do Pub/Sub.
- SUBSCRIPTION_ID: o ID da assinatura do Pub/Sub que você criou (por exemplo,
my-subscription). - EVENT_STREAM_STARTS: quando começar a detectar eventos
usando o formato de data e hora %Y-%m-%dT%H:%M:%S%z (por exemplo,
2020-04-12T06:42:12+04:00). Se não for definido, o job começará a ser executado e detectará eventos após o envio bem-sucedido do comando de criação de job. - EVENT_STREAM_EXPIRES: quando parar de detectar eventos. Se não for definido, o job continuará até ser interrompido manualmente.
Para uma lista completa de campos compatíveis, consulte a referência de gcloud transfer jobs create.
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 por eventos, o Serviço de transferência do Cloud Storage cria um job de transferência. Quando o horário de início é atingido, 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 o status 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 atingido ou até que o job seja interrompido manualmente.
Se uma transferência de arquivos estiver em andamento quando a operação estiver programada para ser concluída, a operação atual vai continuar em andamento até que o arquivo seja completamente transferido. Uma nova operação é iniciada, e as duas operações 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 ver 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 console do Google Cloud .
Na lista de jobs, selecione a guia Todos ou Cloud para Cloud.
Clique no ID da tarefa da sua transferência. A coluna Modo de programação identifica todas as transferências orientadas por 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 ver 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 ver detalhes sobre uma operação:
gcloud transfer operations describe OPERATION_NAME