Transferências baseadas em eventos

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

Quando você configura transferências com base em eventos, pode haver um atraso de alguns minutos entre cada transferência de dados. Se você precisar de disponibilidade imediata dos dados, recomendamos usar a 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 as duas, considere se você precisa priorizar a ingestão incremental de lotes com bom custo-benefício com transferências orientadas a eventos ou se prefere a flexibilidade da API Storage Write.

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

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

Limitações

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

  • Depois que uma transferência orientada a eventos é acionada, o serviço de transferência de dados do BigQuery espera até 10 minutos antes de acionar a próxima execução de transferência, mesmo que um evento chegue nesse período.
  • As transferências orientadas por eventos não têm 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 orientada a eventos do Cloud Storage, siga estas etapas:

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

    Ativar a API

  2. Se você for administrador do Cloud Storage (roles/storage.admin) e do Pub/Sub (roles/pubsub.admin), prossiga para Criar uma configuração de transferência orientada a eventos.

  3. 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 as etapas configurar o Pub/Sub e configurar as permissões do agente de serviço nas seções a seguir e use a assinatura pré-configurada do Pub/Sub para criar uma configuração de transferência orientada por eventos.

  4. Permissões detalhadas necessárias para configurar notificações de configuração de transferências orientadas por eventos:

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

  1. Verifique se você atende aos Pré-requisitos para usar o Pub/Sub com o Cloud Storage.

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

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

  4. Criar uma assinatura de pull no tópico:

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_NAME

    Substitua SUBSCRIPTION_ID pelo nome ou ID da sua nova assinatura de pull do Pub/Sub.

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

Configurar permissões do agente de serviço

  1. Encontre o nome do agente do serviço de transferência de dados do BigQuery para seu projeto:

    1. Acessar a página AM e administrador

      Acessar IAM e administrador

    2. Marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.

    3. O agente 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 do serviço de transferência de dados do BigQuery.

      Verifique se a conta de serviço tem o papel de agente de serviço.

    Para mais informações sobre os agentes de serviço, consulte Agentes de serviço.

  2. Conceda o papel pubsub.subscriber ao agente do serviço de transferência de dados do BigQuery.

    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 agente 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 hospeda os recursos de transferência criados e faturados.

    Atribuição de uso da cota:quando o agente do serviço de transferência de dados do BigQuery acessa a assinatura do Pub/Sub, o uso da cota é cobrado do projeto do usuário.

  3. Verifique se o agente do serviço de transferência de dados do BigQuery recebeu o papel pubsub.subscriber:

    1. No console Google Cloud , acesse a página Pub/Sub.

      Ir para o Pub/Sub

    2. Selecione a assinatura do Pub/Sub que você usou na transferência orientada por 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 pubsub.subscriber.

    Verifique se o agente de serviço tem pubsub.subscirber na assinatura.

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

Para criar uma transferência do Cloud Storage baseada em eventos, crie uma transferência do Cloud Storage e selecione Baseada em eventos como 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 as funções ou concluir as notificações do Pub/Sub nas configurações do Cloud Storage e as configurações de permissão do agente de serviço necessárias antes de criar a transferência orientada por eventos.