Massenaufnahme benutzerdefinierter Objekte

Du kannst benutzerdefinierte Objektdatensätze gebündelt mit zwei Methoden importieren: SFTP und Data-Warehouse-Import (DWH).  Mit beiden Methoden kannst du Rohdatensätze in eine Datenquelle laden, die du dann mit einem benutzerdefinierten Objekttyp in der Klaviyo-Benutzeroberfläche verbindest.

In diesem Artikel erfährst du, wie die einzelnen Methoden funktionieren, wie du deine Dateien formatierst und was du während und nach dem Import erwarten kannst.

Bevor du anfängst

Mach dich mit benutzerdefinierten Objekten vertraut. Sieh dir Erste Schritte mit benutzerdefinierten Objekten und die Übersicht zur API für benutzerdefinierte Objekte an.

Bei der Konfiguration der Massenaufnahme/-synchronisierung solltest du einige Aspekte der Funktion für benutzerdefinierte Objekte beachten:

• Eine Datenquelle für benutzerdefinierte Objekte ist ein flexibles, benutzerdefiniertes Schema. Ein Datensatz der Datenquelle stellt einen Datensatz in einer Datenquelle dar. Beachte, dass diese in Klaviyo bestehen bleiben, sodass du künftig aus Datensatzaufzeichnungen der Datenquelle, die du in der Vergangenheit geladen hast, unterschiedliche Schemas/Objekte erstellen kannst.
• Ein benutzerdefiniertes Objekt selbst besteht aus einem Objektschema und einem Zuordnungsschema zwischen einer Datenquelle und dem Objekt.
• Unterschiedliche benutzerdefinierte Objekte können einer einzelnen Datenquelle zugeordnet werden, wobei entweder dieselbe oder unterschiedliche Feldzuordnungen verwendet werden.

Um benutzerdefinierte Objekte aus SFTP zu importieren, benötigst du die ID der Datenquelle, in der du Datenquellendatensätze erstellen möchtest. Du kannst dies über API oder in der Web-Benutzeroberfläche erstellen, wenn du ein neues benutzerdefiniertes Objekt erstellst. Beachte, dass dies auch automatisch während des ersten Synchronisierungszyklus einer Data-Warehouse-Synchronisierung für benutzerdefinierte Objekte erstellt werden kann.

Methode 1: SFTP-Import

Datenquelle

Identifiziere die Datenquellen-ID der benutzerdefinierten Objekte, auf die du den Import ausrichten möchtest, und erstelle eine config.json -Datei mit der ID, etwa so:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Verzeichnisstruktur

Erstelle vom SFTP-Root aus einen neuen Ordner in /imports/custom_objects/. Der Name des Ordners hat keinen Einfluss darauf, wie die Daten verarbeitet werden.

Kopiere deine Datei config.json, die data_source_id enthält, in den neuen Ordner.

Lege die Datendateien, die du hochladen möchtest, im neuen Ordner ab. *.csv - und *.jsonl -Dateien werden verarbeitet.

{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

Dateien, die direkt unter custom_objects/ ohne Unterverzeichnis abgelegt werden, werden abgelehnt. Jeder Import benutzerdefinierter Objekte muss sich in einem benannten Unterordner befinden.

Unterstützte Dateiformate

JSONL wird dringend empfohlen, wenn deine Datensätze verschachtelte Daten oder Arrays enthalten.

CSV-Formatierung

• Die erste Zeile muss eine Kopfzeile sein. Spaltennamen müssen der Datenquellendefinition entsprechen.
• Verschachteltes JSON innerhalb einer CSV-Zelle muss in doppelte Anführungszeichen gesetzt werden und interne Anführungszeichen müssen mit doppelten Anführungszeichen maskiert werden (z. B. "").
• Leere Zellen werden als fehlende Felder behandelt, nicht als Nullwerte.

Beispiel-CSV:

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

JSONL-Formatierung

• Jede Zeile muss ein gültiges JSON-Objekt ({...}) sein.
• Zeilen, die keine Objekte sind (z. B. Arrays oder Primitive), werden übersprungen und als Fehler gezählt.
• Leere Zeilen werden stumm ignoriert.
• Verschachtelte Objekte und Arrays werden durchlaufen und vollständig gespeichert.

Beispiel-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"]}}

Was passiert beim Import?

1. Klaviyo erkennt den Unterverzeichnispfad und stellt fest, dass der Ressourcentyp custom_objects ist.
2. Klaviyo prüft, ob im Konto eine Datenquelle für benutzerdefinierte Objekte mit der data_source_id in config.json vorhanden ist.
3. Die Datensätze werden in Batches von bis zu 500 Datensätzen pro Batch extrahiert und verarbeitet.
4. Jeder Batch wird über dieselbe Pipeline, die von der Bulk-API verwendet wird, in die Datenquelle geschrieben.
5. Du erhältst eine Fertigstellungsbenachrichtigung (E-Mail oder im Produkt), wenn der Auftrag beendet ist.

Fehlerbehandlung

• Ungültige Zeilen (falsch formatierte CSV- oder nicht analysierbare JSONL-Zeilen) werden übersprungen. Der Auftrag verarbeitet den Rest der Datei weiter.
• Die Abschlussbenachrichtigung enthält die Anzahl der übersprungenen Zeilen und eine Zusammenfassung aller aufgetretenen Fehler.
• Wenn der Ordner keine .config.json hat oder die Datenquellen-ID in der Konfiguration ungültig ist, wird die Datei nicht verarbeitet. Um es erneut zu versuchen, musst du die Datei noch einmal mit einem anderen Namen hochladen. Alte Dateien werden nach 30 Tagen entfernt.

Methode 2: Data-Warehouse-Import

Übersicht

Wenn du Snowflake, Databricks oder BigQuery verwendest, kannst du eine Data-Warehouse-Synchronisierung so konfigurieren, dass benutzerdefinierte Objekte direkt importiert werden. Der Einrichtungs-Flow ist derselbe wie für Profile und Ereignisse: Verbinde dein Warehouse, wähle eine Tabelle oder Ansicht und wähle als Ressourcentyp Benutzerdefiniertes Objekt.

Synchronisierung konfigurieren

1. Gehe zu Integrationen > Data Warehouse und öffne deine Warehouse-Verbindung.
2. Erstelle eine neue Import-Synchronisierung oder bearbeite eine bestehende.
3. Wähle unter Ressourcentyp die Option Benutzerdefiniertes Objekt aus.
4. Wähle die Datenquelle aus, an die du Datensätze weiterleiten möchtest.
   1. Für eine vorhandene Datenquelle müssen die Namen der Data-Warehouse-Spalten mit der Datenquellendefinition übereinstimmen.
   2. Wenn noch keine Datenquelle vorhanden ist, wird beim ersten Synchronisierungslauf automatisch eine Datenquelle mit dem Namen „Datensynchronisierung: {sync_name}“ erstellt. Du kannst diesen Namen nach Bedarf ändern. Beachte, dass du neue Objekte erst konfigurieren kannst, wenn mindestens ein Datensatz importiert wurde (um das Datenquellenschema einzurichten).
5. Speichere und aktiviere die Synchronisierung.

Verhalten synchronisieren

• Datensätze werden in Batches von bis zu 500 pro Aufruf verarbeitet.
• Fehlgeschlagene Zeilen werden in eine herunterladbare Fehlerdatei mit Details auf Zeilenebene geschrieben (z. B. falsch formatierte Werte, fehlende Kennungen).
• Jeder Synchronisierungslauf generiert einen Protokolleintrag, der auf der Registerkarte „ Protokolle“ der Synchronisierung angezeigt wird und Details zu Extraktion, Transformation, Ladefortschritt und Fehlern enthält.

Nach dem Importieren: bei Verwendung einer vorhandenen Datenquelle

Wenn ein oder mehrere benutzerdefinierte Objekte bereits mit dieser Datenquelle konfiguriert sind, werden sie aus den neuen Datenquellendatensätzen erstellt, genauso wie wenn du Datenquellendatensätze über API hinzugefügt hast.

Wenn noch keine benutzerdefinierten Objekte diese Datenquelle verwenden, kannst du mit dem Assistenten für neue Objekte ein neues Objekt erstellen und die Datenquelle auswählen, die bei deiner Synchronisierung verwendet wird. Vergewissere dich, dass mindestens ein Datensatz importiert wurde, um das Datenquellenschema einzurichten.