Configuração do ambiente e conexão

Visão geral: siga estas etapas para preparar o BigQuery para a Klaviyo. Você vai criar os esquemas necessários (em um conjunto de dados/projeto), configurar uma conta de serviço e uma chave dedicadas, atribuir os privilégios mínimos necessários, verificar a configuração e conectar o BigQuery à Klaviyo.

Para saber mais detalhes sobre como o Data Warehouse Import funciona na Klaviyo — incluindo a estrutura do esquema, as tabelas obrigatórias e os mapeamentos de campos — consulte Como funcionam as importações de data warehouse na Klaviyo.

1) Criar esquemas/conjuntos de dados obrigatórios

No BigQuery, crie dois conjuntos de dados no projeto que você vai usar para o Klaviyo.

CREATE SCHEMA `KLAVIYO_IMPORT_FROM_DWH`;
CREATE SCHEMA `KLAVIYO_TMP`;

• KLAVIYO_IMPORT_FROM_DWH: Tabelas e visualizações criadas neste conjunto de dados estarão disponíveis para leitura/gravação pela Klaviyo.
• KLAVIYO_TMP: Dados temporários ou de teste usados durante operações de sincronização.

2) Criar a conta e a chave do Klaviyo Service

Crie uma conta de serviço do Google (por exemplo, KLAVIYO_DATA_TRANSFER_USER) que a Klaviyo usará exclusivamente para esta integração. Baixe uma chave JSON para esta conta e armazene-a com segurança.

• Vá para IAM e Administrador → Contas de serviço no console do GCP.
• Crie uma nova conta de serviço (ou selecione uma existente dedicada à Klaviyo).
• Na guia Keys, crie uma nova chave do tipo JSON. Mantenha este arquivo de chave seguro — você vai precisar dele ao configurar a conexão no Klaviyo.

3) Atribuir permissões obrigatórias

Conceda à conta de serviço as seguintes funções, com escopo para os dois conjuntos de dados que você criou:

-- Example commands in GCP CLI (replace placeholders):
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:KLAVIYO_DATA_TRANSFER_USER@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataEditor" \
  --condition=None \
  --dataset="KLAVIYO_TMP"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:KLAVIYO_DATA_TRANSFER_USER@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer" \
  --condition=None \
  --dataset="KLAVIYO_IMPORT_FROM_DWH"

4) Verifique sua configuração (opcional)

4.1 Confirme se os conjuntos de dados existem

SELECT schema_name 
FROM `YOUR_PROJECT_ID.INFORMATION_SCHEMA.SCHEMATA`
WHERE schema_name IN ('KLAVIYO_IMPORT_FROM_DWH','KLAVIYO_TMP');

4.2 Confirmar acesso à conta de serviço

Use a chave de conta de serviço para se autenticar com a CLI ou a API do BigQuery e executar uma consulta simples:

bq --project_id=YOUR_PROJECT_ID \
   --dataset_id=KLAVIYO_IMPORT_FROM_DWH \
   query --use_legacy_sql=false \
   'SELECT COUNT(*) FROM `YOUR_PROJECT_ID.KLAVIYO_IMPORT_FROM_DWH.some_table` LIMIT 1'

4.3 Verificar permissões em cada conjunto de dados

SELECT * 
FROM `YOUR_PROJECT_ID.KLAVIYO_IMPORT_FROM_DWH.INFORMATION_SCHEMA.OBJECT_PRIVILEGES`
WHERE grantee = 'KLAVIYO_DATA_TRANSFER_USER@YOUR_PROJECT_ID.iam.gserviceaccount.com';

4.4 Opcional: validar operações de criar/ler

-- Test create in KLAVIYO_TMP
CREATE TABLE `YOUR_PROJECT_ID.KLAVIYO_TMP.test_permissions` (id INT64);
DROP TABLE `YOUR_PROJECT_ID.KLAVIYO_TMP.test_permissions`;

-- Test select in KLAVIYO_IMPORT_FROM_DWH
SELECT * FROM `YOUR_PROJECT_ID.KLAVIYO_IMPORT_FROM_DWH.some_existing_table` LIMIT 1;

Dica: Execute essas verificações usando a mesma conta de serviço e a mesma chave que você fornecerá ao Klaviyo. Guarde uma cópia dos resultados para auditoria.

5) Conectar a Klaviyo ao BigQuery

Depois que seu ambiente do BigQuery estiver configurado, conclua a conexão na Klaviyo.

1. No Klaviyo, navegue até Avançado → Sincronização na barra lateral esquerda.
2. Clique em Criar sincronização.
3. Selecione Importar ou exportar dados para o seu data warehouse.
4. Escolha BigQuery como seu data warehouse.
5. Clique em Conectar-se ao BigQuery.

Quando solicitado, forneça os seguintes detalhes de configuração da conexão:

Depois de conectar: o Klaviyo validará a conexão, testará o acesso aos seus conjuntos de dados e, em seguida, permitirá que você configure sincronizações — tanto para importar dados para o Klaviyo quanto para exportar dados do Klaviyo para o BigQuery.

Próxima etapa: Depois de conectar com sucesso, crie sua primeira sincronização de importação ou exportação na Klaviyo e comece a mover dados para ou do BigQuery.