Ingestion en masse d’objets personnalisés

Vous pouvez importer des enregistrements d’objets personnalisés en masse à l’aide de deux méthodes : SFTP et Importation depuis un entrepôt de données (DWH).  Les deux méthodes vous permettent de charger des enregistrements bruts dans une source de données, que vous connectez ensuite à un type d’objet personnalisé dans l’interface utilisateur de Klaviyo.

Cet article explique le fonctionnement de chaque méthode, comment formater vos fichiers et à quoi vous attendre pendant et après l’importation.

Avant de commencer

Familiarisez-vous avec les objets personnalisés ; consultez Démarrer avec les objets personnalisés et la présentation de l’ API des objets personnalisés.

La fonctionnalité d’objets personnalisés comporte plusieurs éléments à garder à l’esprit lors de la configuration de l’ingestion/synchronisation en masse :

• Une source de données d’objets personnalisés est un schéma flexible, défini par l’utilisateur. Un enregistrement de source de données représente un enregistrement dans une source de données. Notez que ceux-ci persistent dans Klaviyo, ce qui vous permet de créer différents schémas/objets à l’avenir à partir des enregistrements de source de données que vous avez chargés par le passé.
• Un objet personnalisé se compose lui-même d’un schéma d’objet et d’un schéma de mappage entre une source de données et l’objet.
• Différents objets personnalisés peuvent être mappés à une source de données unique, en utilisant le même mappage ou des mappages de champs différents.

Pour importer des objets personnalisés à partir de SFTP, vous aurez besoin de l’identifiant de la source de données où vous souhaitez créer les enregistrements de la source de données. Vous pouvez le créer via API ou dans l’interface utilisateur web lors de la création d’un nouvel objet personnalisé. Notez que cette option peut également être créée automatiquement lors du premier cycle de synchronisation d’un entrepôt de données pour les objets personnalisés.

Méthode 1 : importation SFTP

Source des données

Identifiez l’ID de la source de données d’objets personnalisés que vous souhaitez cibler avec l’importation, puis créez un fichier config.json avec l’ID, comme ceci :

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Structure de l’annuaire

Depuis la racine SFTP, créez un nouveau dossier dans /imports/custom_objects/. Le nom du dossier n’a aucune incidence sur la manière dont les données sont traitées.

Copiez votre fichier config.json, qui contient data_source_id, dans le nouveau dossier.

Placez les fichiers de données que vous souhaitez importer dans le nouveau dossier. Les fichiers *.csv et *.jsonl seront traités.

{company_id}/
  imports/
    profiles/           
    events/             
    custom_objects/     
      pets/            ← User-defined folder
     config.json        ← Configuration file with data_source_id
     pet_records.csv    ← CSV file to process
     pet_records.jsonl    ← JSONL file to process

Les fichiers placés directement sous custom_objects/ sans sous-répertoire seront rejetés. Chaque importation d’objet personnalisé doit se trouver dans un sous-dossier nommé.

Formats de fichiers pris en charge

JSONL est fortement recommandé lorsque vos enregistrements contiennent des données ou des tableaux imbriqués.

Formatage CSV

• La première ligne doit être une ligne d’en-tête. Les noms des colonnes doivent correspondre à la définition de la source de données.
• Le JSON imbriqué dans une cellule CSV doit être entre guillemets doubles, et les guillemets internes doivent être échappés avec des guillemets doubles (p. ex., "").
• Les cellules vides sont traitées comme des champs absents, et non comme des valeurs nulles.

Exemple de fichier CSV :

subscription_id,product_name,status,start_date
sub_001,Premium Plan,active,2025-01-15
sub_002,Basic Plan,inactive,2024-06-01

Formatage JSONL

• Chaque ligne doit être un objet JSON valide ({...}).
• Les lignes qui ne sont pas des objets (par exemple, des tableaux ou des primitives) sont ignorées et comptabilisées comme des erreurs.
• Les lignes vides sont silencieusement ignorées.
• Les objets imbriqués et les tableaux sont transmis et stockés en totalité.

Exemple JSONL :

{"subscription_id": "sub_001", "product_name": "Premium Plan", "status": "active", "start_date": "2025-01-15"}
{"subscription_id": "sub_002", "product_name": "Basic Plan", "status": "inactive", "start_date": "2024-06-01", "metadata": {"source": "shopify", "tags": ["vip", "annual"]}}

Que se passe-t-il lors de l’importation

1. Klaviyo détecte le chemin du sous-répertoire et détermine que le type de ressource est custom_objects.
2. Klaviyo vérifie si une source de données d’objets personnalisés avec le/la data_source_id dans config.json existe dans le compte.
3. Les enregistrements sont extraits et traités par lots jusqu’à 500 enregistrements par lot.
4. Chaque lot est écrit dans la source de données via le même pipeline utilisé par l’API en masse.
5. Vous recevez une notification d’achèvement (par e-mail ou dans le produit) à la fin de la tâche.

Gestion des erreurs

• Les lignes non valides (lignes CSV mal formées ou JSONL non analysables) sont ignorées. La tâche continue de traiter le reste du fichier.
• La notification d’achèvement comprend un nombre de lignes ignorées et un résumé des erreurs rencontrées.
• Si le dossier ne contient aucun .config.json ou si l’ID de la source de données dans la configuration n’est pas valide, le fichier ne sera pas traité. Pour réessayer, vous devez téléverser à nouveau le fichier avec un nom différent. Les anciens fichiers seront supprimés au bout de 30 jours.

Méthode 2 : Importation depuis un entrepôt de données

Vue d’ensemble

Si vous utilisez Snowflake, Databricks ou BigQuery, vous pouvez configurer une synchronisation d’entrepôt de données pour importer directement des objets personnalisés. Le flux de configuration est le même que pour les profils et les événements : connectez votre entrepôt, sélectionnez un tableau ou une vue, et choisissez Objet personnalisé comme type de ressource.

Configuration de la synchronisation

1. Accédez à Intégrations > Entrepôt de données et ouvrez la connexion à votre entrepôt.
2. Créez une nouvelle synchronisation d’importation ou modifiez une synchronisation existante.
3. Sous Type de ressource, sélectionnez Objet personnalisé.
4. Sélectionnez la source de données vers laquelle vous souhaitez diriger les enregistrements.
   1. Pour une source de données existante : les noms des colonnes de l’entrepôt de données doivent correspondre à la définition de la source de données.
   2. Si aucune source de données n’existe encore, une source sera créée automatiquement lors de la première synchronisation et nommée « Synchronisation des données : {sync_name} ». Vous pouvez modifier ce nom à votre guise. Notez que vous ne pourrez pas configurer de nouveaux objets tant qu’au moins un enregistrement n’aura pas été importé (afin d’établir le schéma de la source de données).
5. Enregistrez et activez la synchronisation.

Comportement de synchronisation

• Les enregistrements sont traités par lots allant jusqu’à 500 par appel.
• Les lignes qui ont échoué sont écrites dans un fichier d’erreur téléchargeable avec des détails au niveau des lignes (par exemple, des valeurs mal formées, des identifiants manquants).
• Chaque exécution de synchronisation génère une entrée de journal visible dans l’onglet Journaux de la synchronisation, avec des détails sur l’extraction, la transformation, la progression du chargement et toute erreur.

Après importation : si vous utilisez une source de données existante

Si un ou plusieurs objets personnalisés sont déjà configurés avec cette source de données, ils seront créés à partir des nouveaux enregistrements de source de données, comme si vous aviez ajouté des enregistrements de source de données via API.

Si aucun objet personnalisé n’utilise encore cette source de données, utilisez l’assistant Nouvel objet pour créer un nouvel objet et sélectionner la source de données utilisée dans votre synchronisation. Assurez-vous qu’au moins un enregistrement a été importé afin que le schéma de la source de données soit établi.