Comment exporter les données Klaviyo vers Databricks

Objectif de cet article

Découvrez comment configurer Databricks comme destination de synchronisation sortante afin que Klaviyo écrive en continu vos données de profil, d’événement et d’indicateur dans des tables Delta au sein de votre propre espace de travail Databricks. Une fois connecté, votre équipe data peut joindre les données Klaviyo au reste de votre lakehouse pour l’analyse, la modélisation et le reporting.

Vous cherchez plutôt à importer des données dans Klaviyo depuis Databricks ? Voir Connexion de Klaviyo et Databricks.

Avant de commencer

Assurez-vous d’avoir les éléments suivants :

• Un espace de travail Databricks avec Unity Catalog activé. Les espaces de travail utilisant uniquement le metastore Hive ne sont pas pris en charge. Si vous utilisez le metastore Hive, envisagez la fédération du metastore Hive.
• Un entrepôt SQL qui prend en charge VARIANT colonnes et des tables temporaires à portée de session afin que Klaviyo puisse écrire des données. Les entrepôts SQL sans serveur sont recommandés ; les entrepôts Classic et Pro peuvent prendre plusieurs minutes à démarrer, ce qui peut retarder les synchronisations.
• Autorisation de créer des schémas, des tables et des autorisations dans le catalogue que vous utiliserez (ou l’aide d’un administrateur Databricks).
• Autorisation de gérer les intégrations dans Klaviyo.
• Adresses IP sortantes de Klaviyo ajoutées à la liste d’autorisation, si votre espace de travail limite le trafic entrant avec des listes d’accès IP :
  • 184.72.183.187/32
  • 52.206.71.52/32
  • 3.227.146.32/32
  • 44.198.39.11/32
  • 35.172.58.121/32
  • 3.228.37.244/32
  • 54.88.219.8/32
  • 3.214.211.176/32

Étape 1 : créez un schéma pour les données Klaviyo

Dans Databricks, les schémas se trouvent dans un catalogue. Créez un schéma dédié pour contenir les tables dans lesquelles Klaviyo écrit. Les exemples SQL de cet article utilisent main comme catalogue et KLAVIYO_EXPORT comme schéma. Si vous utilisez des noms différents, remplacez-les dans tous les exemples SQL, puis saisissez ces mêmes noms dans Klaviyo à l’étape 5.

USE CATALOG main;  -- or your organization's designated catalog
CREATE SCHEMA IF NOT EXISTS KLAVIYO_EXPORT;

Étape 2 : créer les tables de destination

Exécutez le script suivant dans le schéma que vous avez créé à l’étape 1. Klaviyo écrit dans 3 tables :

• klaviyo_profile: une ligne par profil, y compris les champs standard, l’emplacement et les propriétés personnalisées.
• klaviyo_event: Une ligne par événement (par exemple, Commande passée ou E-mail ouvert), lié à un profil et à un indicateur.
• klaviyo_metric: Une ligne par indicateur, utilisée pour rechercher le nom de l’indicateur et l’intégration source pour chaque événement.

Les propriétés de profil personnalisées et les propriétés d’événement sont stockées dans les colonnes VARIANT, afin que vous puissiez interroger directement du JSON imbriqué sans gérer des centaines de colonnes individuelles.

USE SCHEMA main.KLAVIYO_EXPORT;

CREATE TABLE klaviyo_profile (
  id                 STRING NOT NULL,
  external_id        STRING,
  email              STRING,
  phone_number       STRING,
  first_name         STRING,
  last_name          STRING,
  title              STRING,
  organization       STRING,
  properties         VARIANT,
  image              STRING,
  created            TIMESTAMP,
  updated            TIMESTAMP,
  location_address1  STRING,
  location_address2  STRING,
  location_city      STRING,
  location_country   STRING,
  location_latitude  STRING,
  location_longitude STRING,
  location_region    STRING,
  location_zip       STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_event (
  id               STRING NOT NULL,
  metric_id        STRING NOT NULL,
  profile_id       STRING,
  event_properties VARIANT,
  datetime         TIMESTAMP,
  uuid             STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_metric (
  id                   STRING NOT NULL,
  name                 STRING NOT NULL,
  integration_id       STRING,
  integration_name     STRING,
  integration_category STRING,
  created              TIMESTAMP,
  updated              TIMESTAMP,
  PRIMARY KEY (id)
);

Étape 3 : créer un principal de service et un jeton d’accès

Klaviyo s’authentifie auprès de Databricks avec un jeton d’accès personnel (PAT). Nous vous recommandons de créer un principal de service dédié, utilisé uniquement pour cette intégration, plutôt que le compte d’une personne.

1. Créez un principal de service (ou un utilisateur d’espace de travail) pour Klaviyo.
2. Générez un jeton d’accès personnel :
   • Service principal: Demandez à un administrateur d’espace de travail de créer le jeton initial avec la CLI Databricks.
   • Utilisateur de l’espace de travail : Créez un jeton dans l’interface Databricks.
3. Stockez le jeton dans un endroit sécurisé. Vous le collerez dans Klaviyo à l’étape 5.

Si vous avez déjà créé un principal de service pour importer depuis Databricks, vous pouvez le réutiliser. Ajoutez simplement les autorisations d’exportation à l’étape 4.

Étape 4 : octroi des autorisations

Accordez au principal de service Klaviyo l’accès au catalogue, au schéma et à l’entrepôt SQL. Remplacez klaviyo_service_user par l’ID d’application ou le nom d’utilisateur de votre principal de service.

GRANT USE CATALOG ON CATALOG main TO `klaviyo_service_user`;
GRANT USE SCHEMA, SELECT, MODIFY ON SCHEMA main.KLAVIYO_EXPORT TO `klaviyo_service_user`;

Accordez également au principal de service l’autorisation Peut utiliser sur l’entrepôt SQL que vous prévoyez d’utiliser. Dans Databricks, accédez à Entrepôts SQL, sélectionnez votre entrepôt, cliquez sur Autorisations, puis ajoutez le principal de service.

Vérifier votre configuration (facultatif)

En utilisant la même identité et le même jeton que vous donnerez à Klaviyo, confirmez les tables et les autorisations :

SHOW TABLES IN main.KLAVIYO_EXPORT;
SHOW GRANTS ON SCHEMA main.KLAVIYO_EXPORT;

Vous devriez voir les 3 tables, et le principal de service devrait être répertorié avec USE SCHEMA, SELECT et MODIFY.

Étape 5 : connecter Databricks dans Klaviyo

1. Dans Klaviyo, accédez à Avancé > Gestion des données > Synchronisation.
2. Si vous avez déjà une synchronisation, cliquez sur Créer une synchronisation.
3. Sélectionnez Exporter les données vers votre entrepôt de données.
4. Choisissez Databricks, puis cliquez sur Se connecter à Databricks.
5. Saisissez vos détails de connexion :

Cliquez sur Suivant pour configurer votre synchronisation.

Vous pouvez également trouver Databricks dans le marketplace d’applications de Klaviyo en accédant à Intégrations > Découvrir les applications et en recherchant Databricks.

Étape 6 : Configurer la synchronisation de vos données

Choisissez ce que Klaviyo envoie à Databricks et quand il se synchronise.

Objets de données

Choisissez de synchroniser les profils, les événements, ou les deux. Les données d’indicateur sont synchronisées avec les événements, ce qui vous permet de rechercher le nom et la source de l’indicateur de chaque événement.

Intégrations à exclure

Sélectionnez toutes les intégrations dont vous ne souhaitez pas que les événements soient envoyés à Databricks. Cela s’applique uniquement aux données d’événement ; cela n’exclut pas les profils.

Synchronisation sélective

Sélectionnez les indicateurs dont vous souhaitez synchroniser les événements, comme Placed Order. Laissez Synchronisation sélective vide pour synchroniser tous les événements provenant des intégrations que vous n’avez pas exclues. Ce champ n’apparaît que si vous sélectionnez l’objet de données Événements.

Cadence de synchronisation

Sous Tous, choisissez la fréquence de synchronisation des données nouvelles et mises à jour : toutes les 1, 2, 4, 6, 12 ou 24 heures. La valeur par défaut est 1 heure. Définissez la Date de début, l’Heure de début et le Fuseau horaire du calendrier.

Données historiques

Choisissez la quantité de données historiques à envoyer lors de la synchronisation initiale :

• 30 jours
• 90 jours
• 1 an
• Depuis toujours

Étape 7 : passer en revue, connecter, et surveiller votre synchronisation

1. Cliquez sur Suivant pour ouvrir Vérifier. Vérifiez les détails de votre connexion, les données partagées, les intégrations exclues, les indicateurs sélectionnés, et la plage de synchronisation initiale des données.
2. Cliquez sur Connecter. Klaviyo teste la connexion et crée l’exportation si le test réussit.

Lorsque la configuration réussit, Klaviyo affiche un message de confirmation, puis vous ramène à Synchronisation. Votre exportation est activée, et vous pouvez y surveiller son statut de synchronisation.

Si le test de connexion échoue, examinez les détails de l’erreur. Cliquez sur Modifier les identifiants pour corriger les détails de votre connexion, puis cliquez sur Suivant dans les paramètres de données pour revenir à Vérifier, et cliquez à nouveau sur Connecter.

Pour surveiller votre synchronisation, accédez à Advanced > Data management > Syncing, puis cliquez sur Databricks dans la ligne marquée Export. Utilisez ces onglets :

• Historique : Le statut de votre remplissage initial.
• Périodique : Le statut des synchronisations selon la fréquence que vous avez sélectionnée, y compris la fraîcheur des données (le décalage de vos tables Databricks par rapport à Klaviyo).
• Paramètres: consultez et modifiez les détails de votre connexion, la sélection des données, la fréquence de synchronisation, et la plage historique. Cliquez sur Mettre les informations à jour dans la section que vous modifiez pour enregistrer.

Pour en savoir plus sur les statuts de synchronisation, la mise en pause et la reprise des synchronisations, ainsi que l’affichage des journaux d’erreurs, consultez Comprendre la synchronisation des entrepôts de données dans Klaviyo.

Interrogez vos données Klaviyo dans Databricks

Voici quelques exemples pour commencer.

Comptez les événements par nom d’indicateur au cours des 7 derniers jours :

SELECT m.name AS metric, COUNT(*) AS events
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE e.datetime >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY m.name
ORDER BY events DESC;

Lire une propriétés de profil personnalisée à partir de la colonne properties VARIANT :

SELECT id, email, properties:loyalty_tier::STRING AS loyalty_tier
FROM main.KLAVIYO_EXPORT.klaviyo_profile
WHERE properties:loyalty_tier IS NOT NULL;

Obtenir la valeur de commande à partir des événements Placed Order :

SELECT e.profile_id, e.datetime, e.event_properties:`$value`::DOUBLE AS order_value
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE m.name = 'Placed Order';

Résolution de problèmes

Supprimer une exportation Databricks

La suppression de l’exportation empêche les synchronisations futures. Les données déjà écrites dans vos tables Databricks ne sont pas supprimées.

1. Accédez à intégrations dans Klaviyo.
2. Ouvrez le menu à côté de l’intégration d’exportation Databricks et sélectionnez Supprimer l’intégration.
3. Cliquez sur Supprimer l’intégration dans la boîte de dialogue de confirmation.

Ressources supplémentaires

• Connexion de Klaviyo et Databricks (importation)
• Comprendre la synchronisation des entrepôts de données dans Klaviyo
• Démarrer avec Advanced KDP