Carregue dados do Klaviyo para o BigQuery

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: para receber apoio técnico ou enviar feedback sobre esta funcionalidade, contacte [e-mail].

Pode carregar dados do Klaviyo para o BigQuery através do conetor do Serviço de transferência de dados do BigQuery para o Klaviyo. Com o Serviço de transferência de dados do BigQuery, pode agendar tarefas de transferência recorrentes que adicionam os seus dados mais recentes do Klaviyo ao BigQuery.

Antes de começar

As secções seguintes descrevem os pré-requisitos que tem de cumprir antes de criar uma transferência de dados do Klaviyo.

Pré-requisitos do Klaviyo

Tem de ter uma chave de API privada só de leitura para permitir que o conector do Klaviyo transfira dados para o BigQuery. Para mais informações, consulte o artigo Crie uma chave privada.

Pré-requisitos do BigQuery

• Verifique se concluiu todas as ações necessárias para ativar o Serviço de transferência de dados do BigQuery.
• Crie um conjunto de dados do BigQuery para armazenar os seus dados.

Funções do BigQuery necessárias

Para obter as autorizações de que precisa para criar uma transferência de dados do Serviço de transferência de dados do BigQuery, peça ao seu administrador para lhe conceder a função do IAM de administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar uma transferência de dados do Serviço de transferência de dados do BigQuery. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar uma transferência de dados do Serviço de transferência de dados do BigQuery:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Para mais informações, consulte o artigo Conceda acesso ao bigquery.admin.

Se pretender configurar notificações de execução de transferências para o Pub/Sub, certifique-se de que tem a autorização pubsub.topics.setIamPolicyIAM. As autorizações do Pub/Sub não são necessárias se configurar apenas notificações por email. Para mais informações, consulte o artigo Notificações de execução do Serviço de transferência de dados do BigQuery.

Configure uma transferência de dados do Klaviyo

Adicione dados do Klaviyo ao BigQuery configurando uma configuração de transferência através de uma das seguintes opções:

Consola

1. Aceda à página Transferências de dados na Google Cloud consola.

   Aceda a Transferências de dados

2. Clique em Criar transferência.

3. Na secção Tipo de origem, para Origem, escolha Klaviyo – Pré-visualização.

4. Na secção Detalhes da origem de dados, faça o seguinte:

   • Para a chave da API privada, introduza a sua chave da API privada. Para mais informações, consulte os pré-requisitos do Klaviyo.
   • Opcional: para a Data de início, especifique uma data de início para que os novos registos sejam incluídos na transferência de dados. A transferência de dados inclui apenas registos criados a partir desta data, inclusive. O valor predefinido é 3 meses antes da data de execução da transferência.
   • Para transferir objetos do Klaviyo, clique em Procurar para selecionar quaisquer objetos a transferir para o conjunto de dados de destino do BigQuery. Também pode introduzir manualmente quaisquer objetos a incluir na transferência de dados neste campo.

5. Na secção Definições de destino, para Conjunto de dados, escolha o conjunto de dados que criou para armazenar os seus dados.

6. Na secção Nome da configuração de transferência, em Nome a apresentar, introduza um nome para a transferência de dados.

7. Na secção Opções de agendamento:

   • Na lista Frequência de repetição, selecione uma opção para especificar a frequência com que esta transferência de dados é executada. Para especificar uma frequência de repetição personalizada, selecione Personalizado. Se selecionar A pedido, esta transferência é executada quando aciona manualmente a transferência.
   • Se aplicável, selecione Começar agora ou Começar à hora definida e indique uma data de início e um tempo de apresentação.

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

   • Para ativar as notificações por email, clique no botão Notificação por email. Quando ativa esta opção, o administrador da transferência recebe uma notificação por email quando uma execução da transferência falha.
   • Para ativar as notificações de execução de transferências do Pub/Sub para esta transferência, clique no botão ativar/desativar Notificações do Pub/Sub. Pode selecionar o nome do tópico ou clicar em Criar um tópico para criar um.

9. Clique em Guardar.

bq

Introduza o comando bq mk e forneça a flag de criação de 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 o seguinte:

• PROJECT_ID (opcional): o ID do seu Google Cloud projeto. Se --project_id não for fornecido para especificar um projeto em particular, é usado o projeto predefinido.
• DATA_SOURCE: a origem de dados: klaviyo.
• NAME: o nome a apresentar da configuração de transferência de dados. O nome da transferência pode ser qualquer valor que lhe permita identificar a transferência se precisar de a modificar mais tarde.
• DATASET: o conjunto de dados de destino para a configuração de transferência.

• PARAMETERS: os parâmetros da configuração de transferência criada no formato JSON. Por exemplo: --params='{"param":"param_value"}'. Seguem-se os parâmetros para 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 da API privada da conta do Klaviyo.
  • connector.startDate: (opcional) uma data de início para novos registos a incluir na transferência de dados, no formato YYYY-MM-DD. Apenas os registos criados nesta data ou após esta data são incluídos na transferência de dados. O valor predefinido é 3 meses antes da data de execução da transferência.

O comando seguinte cria uma transferência de dados do Klaviyo no projeto predefinido.

    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 guarda a configuração da transferência, o conetor do Klaviyo aciona automaticamente uma execução da transferência de acordo com a opção de agendamento. Com cada execução de transferência, o conetor do Klaviyo transfere todos os dados disponíveis do Klaviyo para o BigQuery.

Para executar manualmente uma transferência de dados fora do seu agendamento normal, pode iniciar uma execução de preenchimento.

Mapeamento de tipos de dados

A tabela seguinte mapeia os tipos de dados do Klaviyo para os tipos de dados do BigQuery correspondentes:

Tipo de dados do Klaviyo	Tipo de dados do BigQuery
String	STRING
Text	STRING
Integer	INTEGER
Boolean	BOOLEAN
Date (YYYY-MM-DD HH:MM:SS)	TIMESTAMP
List	ARRAY

Preços

Não existe custo para transferir dados do Klaviyo para o BigQuery enquanto esta funcionalidade estiver em pré-visualização.

Resolva problemas de configuração da transferência

Se estiver a ter problemas com a configuração da transferência de dados, consulte Problemas de transferência do Klaviyo.

O que se segue?

• Para uma vista geral do Serviço de transferência de dados do BigQuery, consulte o artigo O que é o Serviço de transferência de dados do BigQuery.
• Para obter informações sobre a utilização de transferências, incluindo a obtenção de informações sobre uma configuração de transferência, a apresentação de configurações de transferência e a visualização do histórico de execução de uma transferência, consulte o artigo Faça a gestão de transferências.