Carregar dados do Klaviyo no BigQuery

Para programar transferências de dados recorrentes do Klaviyo para o BigQuery, crie uma configuração de transferência para especificar quais objetos de dados serão transferidos e com que frequência programar a transferência de dados. É possível criar uma configuração de transferência usando o console do Google Cloud ou a ferramenta de linha de comando bq. Depois de definir a configuração de transferência, o serviço de transferência de dados do BigQuery transfere os dados mais recentes para uma tabela do BigQuery na programação especificada.

Para saber como funciona uma transferência do Klaviyo, consulte Introdução às transferências de dados do Klaviyo.

Limitações

  • Se o anexo de rede foi criado em um projeto do Google Cloud diferente do projeto do Google Cloud da transferência de dados, é necessário conceder as permissões compute.networkAttachments.get e compute.networkAttachments.update ao agente de serviço que pertence ao projeto do Google Cloud em que a transferência de dados foi criada.

Limitações de transferência incremental

As transferências incrementais do Klaviyo estão sujeitas às seguintes limitações:

  • Só é possível escolher colunas TIMESTAMP como colunas de marca-d'água.
  • A ingestão incremental só é compatível com recursos que têm colunas de marca-d'água válidas.
  • Os valores em uma coluna de marca-d'água precisam aumentar monotonicamente.
  • As transferências incrementais não podem sincronizar operações de exclusão na tabela de origem.
  • Uma única configuração de transferência só pode aceitar ingestão incremental ou completa.
  • Não é possível atualizar objetos na lista asset após a primeira execução de ingestão incremental.
  • Não é possível mudar o modo de gravação em uma configuração de transferência após a primeira execução de ingestão incremental.
  • Não é possível alterar a coluna de marca-d'água ou a chave primária após a primeira execução de ingestão incremental.
  • A tabela de destino do BigQuery é agrupada em cluster usando a chave primária fornecida e está sujeita às limitações de tabelas em cluster.
  • Quando você atualiza uma configuração de transferência para o modo de ingestão incremental pela primeira vez, a primeira transferência de dados após essa atualização transfere todos os dados disponíveis da sua fonte de dados. Todas as transferências de dados incrementais subsequentes vão transferir apenas as linhas novas e atualizadas da fonte de dados.

Antes de começar

As seções a seguir descrevem os pré-requisitos que você precisa cumprir antes de criar uma transferência de dados do Klaviyo.

Pré-requisitos do Klaviyo

Você precisa ter uma chave de API privada somente leitura para permitir que o conector da Klaviyo transfira dados para o BigQuery. Para mais informações, consulte Criar uma chave privada.

Pré-requisitos do BigQuery

Papéis obrigatórios do BigQuery

Para receber as permissões necessárias para criar uma transferência de dados do serviço de transferência de dados do BigQuery, peça ao administrador para conceder a você o papel do IAM de Administrador do BigQuery (roles/bigquery.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma transferência de dados do serviço de transferência de dados do BigQuery. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para criar uma transferência de dados do serviço de transferência de dados do BigQuery:

  • Permissões do serviço de transferência de dados do BigQuery:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • Permissões do BigQuery:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações, consulte Conceder acesso ao bigquery.admin.

Se você pretende configurar notificações de execução de transferência do Pub/Sub, verifique se tem a permissão pubsub.topics.setIamPolicy do IAM. As permissões do Pub/Sub não serão necessárias caso você configure notificações por e-mail. Para saber mais informações, consulte Notificações de execução do serviço de transferência de dados do BigQuery.

Configurar uma transferência de dados da Klaviyo

Adicione dados do Klaviyo ao BigQuery definindo uma configuração de transferência usando uma das seguintes opções:

Console

  1. Acesse a página "Transferências de dados" no console do Google Cloud .

    Acesse Transferências de dados

  2. Clique em Criar transferência.

  3. Na seção Tipo de origem, em Origem, escolha Klaviyo - Pré-lançamento.

  4. Na seção Detalhes da fonte de dados, faça o seguinte:

    • Em Chave de API privada, insira sua chave de API privada. Para mais informações, consulte Pré-requisitos do Klaviyo.
    • Opcional: em Data de início, especifique uma data de início para que novos registros sejam incluídos na transferência de dados. Somente os registros criados nessa data ou depois dela são incluídos na transferência de dados. O valor padrão é de três meses antes da data de execução da transferência.
    • Em Objetos da Klaviyo para transferência, clique em Procurar para selecionar os objetos a serem transferidos para o conjunto de dados de destino do BigQuery. Nesse campo, também é possível inserir manualmente qualquer objeto para incluir na transferência de dados.

  5. No campo Conjunto de dados da seção Configurações de destino, escolha o conjunto criado para armazenar seus dados.

  6. No campo Nome de exibição da seção Nome de configuração da transferência, insira um nome para a transferência de dados.

  7. Na seção Opções de programação, faça o seguinte:

    • Na lista Frequência de repetição, selecione uma opção para especificar com que frequência essa transferência de dados é executada. Para especificar uma frequência de repetição personalizada, selecione Personalizada. Se você selecionar Sob demanda, essa transferência será executada quando você acionar manualmente a transferência.
    • Se aplicável, selecione Começar agora ou Começar no horário definido e escolha uma data de início e hora de execução.

  8. Opcional: na seção Opções de notificação, faça o seguinte:

    • Para ativar as notificações por e-mail, clique no botão que ativa as Notificações por e-mail. Quando essa opção está ativada, o administrador da transferência recebe uma notificação por e-mail quando uma execução da transferência falha.
    • Para ativar as notificações de execução de transferência do Pub/Sub para essa transferência, clique no botão de alternância Notificações do Pub/Sub. Selecione o nome do tópico ou clique em Criar tópico.

  9. Clique em Salvar.

bq

Insira o comando bq mk e forneça a sinalização de execução da transferência --transfer_config:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Substitua:

  • PROJECT_ID (opcional): o ID do projeto do Google Cloud . Se --project_id não for fornecido para especificar um projeto determinado, o projeto padrão será usado.
  • DATA_SOURCE: a fonte de dados — klaviyo.
  • NAME: o nome de exibição da configuração da transferência de dados. O nome da transferência pode ser qualquer valor que permita identificá-la, caso você precise modificá-la mais tarde.
  • DATASET: o conjunto de dados de destino na configuração de transferência.

  • PARAMETERS é o parâmetro da configuração de transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Confira a seguir os parâmetros de uma transferência de dados do Klaviyo:

    • assets: o caminho para os objetos do Klaviyo a serem transferidos para o BigQuery.
    • connector.authentication.privateApiKey: a chave de API privada da conta do Klaviyo.
    • connector.startDate: (opcional) uma data de início para que novos registros sejam incluídos na transferência de dados, no formato YYYY-MM-DD. Somente os registros criados nessa data ou depois dela são incluídos na transferência de dados. O valor padrão é de três meses antes da data de execução da transferência.
    • ingestionType: (opcional) especifica o método de carregamento de dados. Os valores permitidos são full (substitui todos os dados na tabela de destino) ou incremental (carrega apenas dados novos ou modificados desde a última transferência).
    • writeMode: (opcional) quando ingestionType é definido como incremental, especifica como os dados são gravados na tabela de destino. Os valores permitidos são WRITE_MODE_APPEND (anexa novos registros) ou WRITE_MODE_UPSERT (atualiza os registros atuais e insere novos registros).

O comando a seguir cria uma transferência de dados do Klaviyo no projeto padrão.

    bq mk
        --transfer_config
        --target_dataset=mydataset
        --data_source=klaviyo
        --display_name='My Transfer'
        --params= ' {
            "assets": [ "Events" , "Flows"] ,
            "connector.authentication.privateApiKey" : "pk_123456789123",
            "connector.startDate": "2025-10-20"
            }'
Quando você salva a configuração de transferência, o conector do Klaviyo aciona automaticamente uma execução de transferência de acordo com a opção de programação. A cada execução de transferência, o conector da Klaviyo transfere todos os dados disponíveis da Klaviyo para o BigQuery.

Para executar manualmente uma transferência de dados fora da programação regular, inicie uma execução de preenchimento.

Para ver uma lista de dados incluídos em uma transferência de dados do Klaviyo, consulte a referência do modelo de dados do Klaviyo.

Resolver problemas na configuração da transferência

Se você tiver problemas para configurar a transferência de dados, consulte Problemas de transferência da Klaviyo.

A seguir