Bulkopname aangepaste objecten

Je kunt aangepaste objectrecords op twee manieren in bulk importeren: SFTP en import uit datawarehouse (DWH).  Met beide methoden kun je onbewerkte records in een gegevensbron laden, die je vervolgens koppelt aan een aangepast objecttype in de UI van Klaviyo.

In dit artikel wordt beschreven hoe elke methode werkt, hoe je je bestanden kunt indelen en wat je kunt verwachten tijdens en na het importeren.

Voordat je van start gaat

Maak jezelf vertrouwd met aangepaste objecten. Bekijk Aan de slag met aangepaste objecten en het overzicht van de API voor aangepaste objecten.

Er zijn een paar onderdelen van de aangepaste objecten waarmee je rekening moet houden bij het configureren van bulkopname/-synchronisatie:

• Een gegevensbron voor aangepaste objecten Data Source is een flexibel, door de gebruiker gedefinieerd schema. Een Data Source Record is een record in een gegevensbron. Let op: deze blijven bewaard in Klaviyo, zodat je in de toekomst verschillende schema's/objecten kunt maken op basis van Data Source Records die je in het verleden hebt geladen.
• Een aangepast object zelf bestaat uit een objectschema en een toewijzingsschema tussen een gegevensbron en het object.
• Verschillende aangepaste objecten kunnen worden toegewezen aan een enkele gegevensbron, met behulp van dezelfde of verschillende veldtoewijzingen.

Als je aangepaste objecten vanuit SFTP wilt importeren, heb je de ID nodig van de gegevensbron waar je gegevensbronrecords wilt maken. Je kunt dit aanmaken via API of in de web-UI wanneer je een nieuw aangepast object maakt. Merk op dat dit ook automatisch kan worden aangemaakt tijdens de eerste synchronisatiecyclus van een datawarehouse-synchronisatie voor aangepaste objecten.

Methode 1: SFTP-import

Gegevensbron

Identificeer de gegevensbron-ID voor aangepaste objecten die je met de import wilt targeten en maak een config.json -bestand met de ID, zoals dit:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Directorystructuur

Maak vanuit de SFTP-hoofdmap een nieuwe map aan in /imports/custom_objects/. De naam van de map heeft geen invloed op hoe de gegevens worden verwerkt.

Kopieer je config.json -bestand, dat data_source_id bevat, naar de nieuwe map.

Plaats de gegevensbestanden die je wilt uploaden in de nieuwe map. *.csv en *.jsonl bestanden worden verwerkt.

{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

Bestanden die direct onder custom_objects/ worden geplaatst zonder submap, worden geweigerd. Elke import van een aangepast object moet in een benoemde submap staan.

Ondersteunde bestandsindelingen

JSONL wordt sterk aanbevolen als je records geneste gegevens of reeksen bevatten.

Csv-opmaak

• De eerste rij moet een koptekstrij zijn. Kolomnamen moeten overeenkomen met de definitie van de gegevensbron.
• Geneste JSON binnen een CSV-cel moet tussen dubbele aanhalingstekens staan en interne aanhalingstekens moeten worden geëscaped met dubbele aanhalingstekens (bijv. "").
• Lege cellen worden behandeld als ontbrekende velden, niet als lege waarden.

Voorbeeld van 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-opmaak

• Elke regel moet een geldig JSON-object ({...}) zijn.
• Regels die geen object zijn (zoals reeksen of primitieven) worden overgeslagen en geteld als fouten.
• Lege regels worden stilzwijgend genegeerd.
• Geneste objecten en reeksen worden doorgegeven en volledig opgeslagen.

Voorbeeld van 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"]}}

Wat gebeurt er tijdens het importeren

1. Klaviyo detecteert het subdirectorypad en bepaalt dat het resourcetype custom_objects is.
2. Klaviyo controleert of er in het account een gegevensbron voor aangepaste objecten bestaat met de data_source_id in config.json.
3. Records worden uitgepakt en verwerkt in batches van maximaal 500 records per batch.
4. Elke batch wordt naar de gegevensbron geschreven via dezelfde pipeline die wordt gebruikt door de Bulk-API.
5. Je ontvangt een voltooiingsmelding (e-mail of in het product) wanneer de taak is voltooid.

Foutafhandeling

• Ongeldige rijen (verkeerd ingedeelde csv of niet-parseerbare JSONL-regels) worden overgeslagen. De taak gaat verder met het verwerken van de rest van het bestand.
• De voltooiingsmelding bevat het aantal overgeslagen rijen en een samenvatting van alle opgetreden fouten.
• Als de map geen .config.json heeft of de gegevensbron-ID in de configuratie ongeldig is, wordt het bestand niet verwerkt. Om het opnieuw te proberen, moet je het bestand opnieuw uploaden met een andere naam. Oude bestanden worden na 30 dagen verwijderd.

Methode 2: datawarehouse importeren

Overzicht

Als je Snowflake, Databricks of BigQuery gebruikt, kun je een datawarehouse-synchronisatie configureren om aangepaste objecten rechtstreeks te importeren. De instellingsflow is hetzelfde als voor profiel en gebeurtenissen — koppel je magazijn, selecteer een tabel of weergave en kies Aangepast object als type bron.

De synchronisatie configureren

1. Ga naar Integraties > datawarehouse en open je warehouseverbinding.
2. Maak een nieuwe importsynchronisatie of bewerk een bestaande.
3. Selecteer onder Resourcetype Aangepast object.
4. Selecteer de gegevensbron waarnaar je records wilt routeren.
   1. Voor een bestaande gegevensbron: de kolomnamen van het datawarehouse moeten overeenkomen met de definitie van de gegevensbron.
   2. Als er nog geen gegevensbron bestaat, wordt er bij de eerste synchronisatie automatisch een aangemaakt met de naam 'Gegevenssynchronisatie: {sync_name}'. Je kunt deze naam naar wens wijzigen. Merk op dat je geen nieuwe objecten kunt configureren totdat er ten minste één record is geïmporteerd (om het schema van de gegevensbron vast te stellen).
5. Sla op en activeer de synchronisatie.

Synchronisatiegedrag

• Records worden verwerkt in batches van maximaal 500 per aanroep.
• Mislukte rijen worden weggeschreven naar een downloadbaar foutbestand met details op rijniveau (zoals misvormde waarden, ontbrekende identificatoren).
• Elke synchronisatie-uitvoering genereert een logboekvermelding dat kan worden bekeken op het tabblad Logboeken van de synchronisatie, met details over extraheren, transformatie, voortgang van het laden en eventuele fouten.

Na het importeren: bij gebruik van een bestaande gegevensbron

Als een of meer aangepaste objecten al met die gegevensbron zijn geconfigureerd, worden ze gemaakt op basis van de nieuwe gegevensbronrecords, net zoals ze zouden doen als je records van de gegevensbron via API zou toevoegen.

Als er nog geen aangepaste objecten die gegevensbron gebruiken, gebruik dan de wizard Nieuw object om een nieuw object te maken en selecteer de gegevensbron die je in je synchronisatie hebt gebruikt. Zorg ervoor dat ten minste één record is geïmporteerd, zodat het schema van de gegevensbron bepaald wordt.