Transferências baseadas em eventos

É possível usar o serviço de transferência de dados do BigQuery para criar transferências baseadas em eventos que carregam dados automaticamente com base em notificações de eventos. Recomendamos o uso de transferências baseadas em eventos se você precisar de ingestão de dados incremental que otimize a eficiência de custos.

Ao configurar transferências baseadas em eventos, pode haver um atraso de alguns minutos entre cada transferência de dados. Se você precisar de disponibilidade imediata de dados, recomendamos o uso da API Storage Write que transmite dados diretamente para o BigQuery com a menor latência possível. A API Storage Write oferece atualizações em tempo real para os casos de uso mais exigentes.

Ao escolher entre os dois, considere se você precisa priorizar a ingestão de lote incremental econômica com transferências baseadas em eventos ou se prefere a flexibilidade da API Storage Write.

Fontes de dados com suporte a transferências baseadas em eventos

O serviço de transferência de dados do BigQuery pode usar transferências baseadas em eventos com as seguintes fontes de dados:

Cloud Storage

Limitações

As transferências baseadas em eventos para o BigQuery estão sujeitas às seguintes limitações:

Depois que uma transferência baseada em eventos é acionada, o serviço de transferência de dados do BigQuery aguarda até 10 minutos antes de acionar a próxima execução de transferência, independentemente de um evento chegar dentro desse período.
As transferências baseadas em eventos não oferecem suporte a parâmetros de execução para o URI de origem ou o caminho de dados.
A mesma assinatura do Pub/Sub não pode ser reutilizada por várias configurações de transferência baseadas em eventos.

Configurar uma transferência baseada em eventos do Cloud Storage

As transferências baseadas em eventos do Cloud Storage usam notificações do Pub/Sub para saber quando os objetos no bucket de origem foram modificados ou adicionados. Ao usar o modo de transferência incremental, a exclusão de um objeto no bucket de origem não exclui os dados associados na tabela de destino do BigQuery.

Antes de começar

Antes de configurar uma transferência baseada em eventos do Cloud Storage, siga estas etapas:

Ative a API Pub/Sub para o projeto que recebe notificações.

Ativar a API
Se você for o administrador do Cloud Storage (roles/storage.admin) e do Pub/Sub (roles/pubsub.admin), poderá prosseguir para Criar uma configuração de transferência baseada em eventos.
Se você não for o administrador do Cloud Storage (roles/storage.admin) e do Pub/Sub (roles/pubsub.admin), peça ao administrador para conceder os papéis roles/storage.admin e roles/pubsub.admin ou para concluir a configuração do Pub/Sub () e as permissões do agente de serviço () nas seções a seguir e usar a assinatura do Pub/Sub pré-configurada para criar uma configuração de transferência baseada em eventos ().
Permissões detalhadas necessárias para configurar notificações de configuração de transferência baseadas em eventos:
- Se você planeja criar tópicos e assinaturas para publicar notificações, é necessário ter as permissões pubsub.topics.create e pubsub.subscriptions.create.
- Se você planeja usar tópicos e assinaturas novos ou atuais, é necessário ter as seguintes permissões. Se você já criou tópicos e assinaturas no Pub/Sub, provavelmente já tem essas permissões.
- É necessário ter as seguintes permissões no bucket do Cloud Storage em que você quer configurar notificações do Pub/Sub.
  - storage.buckets.get
  - storage.buckets.update
- O papel predefinido do IAM pubsub.admin e storage.admin tem todas as permissões necessárias para configurar uma transferência baseada em eventos do Cloud Storage. Para mais informações, consulte Controle de acesso do Pub/Sub.

Configurar notificações do Pub/Sub no Cloud Storage

Verifique se você atendeu aos pré-requisitos para usar o Pub/Sub com o Cloud Storage.
Aplique uma configuração de notificação ao bucket do Cloud Storage:
```
gcloud storage buckets notifications create gs://BUCKET_NAME --topic=TOPIC_NAME --event-types=OBJECT_FINALIZE
```
Substitua:
- BUCKET_NAME: o nome do bucket do Cloud Storage em que você quer acionar eventos de notificação de arquivo
- TOPIC_NAME: o nome do tópico do Pub/Sub em que você quer receber os eventos de notificação de arquivo
Também é possível adicionar uma configuração de notificação usando outros métodos além da CLI gcloud. Para mais informações, consulte Aplicar uma configuração de notificação.

Verifique se a notificação do Pub/Sub está configurada corretamente para o Cloud Storage. Use o comando gcloud storage buckets notifications list:

gcloud storage buckets notifications list gs://BUCKET_NAME

Se a operação for bem-sucedida, a resposta será semelhante a esta:

etag: '132'
id: '132'
kind: storage#notification
payload_format: JSON_API_V1
selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/notificationConfigs/132
topic: //pubsub.googleapis.com/projects/my-project/topics/my-bucket

Criar uma assinatura por pull no tópico:
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_NAME
```
Substitua SUBSCRIPTION_ID pelo nome ou ID da sua nova assinatura por pull do Pub/Sub.

É possível criar uma assinatura por pull usando outros métodos.

**Observação** :a mesma assinatura do Pub/Sub não pode ser reutilizada por várias configurações de transferência baseadas em eventos.

Configurar permissões do agente de serviço

Encontre o nome do agente de serviço do BigQuery Data Transfer Service para seu projeto:
1. Acessar a página IAM e administrador.
  
  Acessar IAM e administrador
2. Marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.
3. O agente de serviço do serviço de transferência de dados do BigQuery é listado com o nome service-<project_number>@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com e recebe o papel de agente de serviço do serviço de transferência de dados do BigQuery (roles/bigquerydatatransfer.serviceAgent).
Consulte Agentes de serviço para mais informações sobre esse assunto.
Conceda o papel de assinante do Pub/Sub (pubsub.subscriber) ao agente de serviço do serviço de transferência de dados do BigQuery.
Console do Cloud
Siga as instruções em Como controlar o acesso usando o Google Cloud console para conceder o papel Pub/Sub Subscriber ao agente de serviço do serviço de transferência de dados do BigQuery. O papel pode ser concedido no nível do tópico, da assinatura ou do projeto.
CLI gcloud
Siga as instruções em Como definir uma política para adicionar a seguinte vinculação:
```
{
  "role": "roles/pubsub.subscriber",
  "members": [
    "serviceAccount:project-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com"
}
```
Substitua PROJECT_NUMBER pelo ID do projeto que está hospedando a transferência em que os recursos são criados e faturados.
Atribuição de uso de cota:quando o agente de serviço do serviço de transferência de dados do BigQuery acessa a assinatura do Pub/Sub, o uso de cota é cobrado do projeto do usuário.
Verifique se o agente do serviço de transferência de dados do BigQuery recebeu o papel de assinante do Pub/Sub (pubsub.subscriber).
1. No Google Cloud console, acesse a página Pub/Sub.
  
  Ir para o Pub/Sub
2. Selecione a assinatura do Pub/Sub que você usou na transferência baseada em eventos.
3. Se o painel de informações estiver oculto, clique em Mostrar painel de informações no canto superior direito.
4. Na guia Permissões, verifique se o agente de serviço do serviço de transferência de dados do BigQuery tem o papel de assinante do Pub/Sub (pubsub.subscriber).

Comandos resumidos para configurar notificações e permissões

Os comandos da Google Cloud CLI a seguir incluem todos os comandos necessários para configurar Notificações e permissões, conforme detalhado nas seções anteriores.

gcloud

PROJECT_ID=project_id
CONFIG_NAME=config_name
RESOURCE_NAME="bqdts-event-driven-${CONFIG_NAME}"
# Create a Pub/Sub topic.
gcloud pubsub topics create "${RESOURCE_NAME}" --project="${PROJECT_ID}"
# Create a Pub/Sub subscription.
gcloud pubsub subscriptions create "${RESOURCE_NAME}" --project="${PROJECT_ID}" --topic="projects/${PROJECT_ID}/topics/${RESOURCE_NAME}"
# Create a Pub/Sub notification.
gcloud storage buckets notifications create gs://"${RESOURCE_NAME}" --topic="projects/${PROJECT_ID}/topics/${RESOURCE_NAME}" --event-types=OBJECT_FINALIZE
# Grant roles/pubsub.subscriber permission to the DTS service agent.
PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format='value(projectNumber)')
gcloud pubsub subscriptions add-iam-policy-binding "${RESOURCE_NAME}"  --project="${PROJECT_ID}"  --member=serviceAccount:service-"${PROJECT_NUMBER}"@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com  --role=roles/pubsub.subscriber

Substitua:

PROJECT_ID: o ID do seu projeto.
CONFIG_NAME: um nome para identificar essa configuração de transferência.

Criar uma configuração de transferência

É possível criar uma transferência baseada em eventos do Cloud Storage criando uma transferência do Cloud Storage e selecionando Baseado em eventos como o Tipo de programação. Como administrador do Cloud Storage (roles/storage.admin) e do Pub/Sub (roles/pubsub.admin), você tem permissões suficientes para que o serviço de transferência de dados do BigQuery configure automaticamente o Cloud Storage para enviar notificações.

Se você não for o administrador do Cloud Storage (roles/storage.admin) e do Pub/Sub (roles/pubsub.admin), peça ao administrador para conceder os papéis ou para concluir as notificações necessárias do Pub/Sub nas configurações do Cloud Storage e as configurações de permissão do agente de serviço antes de criar a transferência baseada em eventos.