Aangepaste objecten importeren via SFTP en datawarehouse-synchronisatie

Wat je leert

Je kunt aangepaste objectrecords in bulk importeren via 2 methoden: SFTP en import uit datawarehouse. Beide methoden laden onbewerkte records in een gegevensbron. Je kunt de geïmporteerde records gebruiken met een nieuw aangepast object of een bestaand object dat is geconfigureerd met die gegevensbron.

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

Bekijk vóór het importeren Aan de slag met aangepaste objecten en het overzicht van API voor aangepaste objecten.

Houd deze concepten in gedachten wanneer je een import instelt:

• Een gegevensbron voor custom objects slaat de onbewerkte gegevens op die je importeert. Een gegevensbronrecord is een afzonderlijk record in die gegevensbron. Deze records blijven bewaard in Klaviyo, zodat je eerder geïmporteerde gegevens kunt gebruiken om extra custom objects te configureren.
• 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.

Voor SFTP heb je de ID nodig van een bestaande gegevensbron in je account. Je kunt een gegevensbron maken via de API of terwijl je een nieuw aangepast object in Klaviyo configureert. Voor import uit datawarehouse kun je een gegevensbron maken of een bestaande selecteren tijdens het instellen van de synchronisatie.

Methode 1: SFTP-import

Voeg vóór het uploaden een openbare SSH-sleutel toe aan Klaviyo en verbind je SFTP-client met de inloggegevens die Klaviyo verstrekt. Zie Gegevens importeren via SFTP.

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

1. 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.
2. Kopieer je config.json -bestand, dat data_source_id bevat, naar de nieuwe map.
3. Upload je gegevensbestanden naar dezelfde map nadat je het configuratiebestand hebt geüpload. *.csv en *.jsonl bestanden worden verwerkt.

{company_id}/imports/custom_objects/pets/
  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 koprij zijn. Gebruik kolomnamen waarnaar wordt verwezen door je aangepaste-objecttoewijzingen.
• Als een CSV-cel JSON-tekst bevat, zet je de cel tussen dubbele aanhalingstekens en verdubbel je elk intern aanhalingsteken (bijv. ""). De waarde wordt geïmporteerd als een string. Gebruik JSONL om geneste objecten of arrays te behouden.
• Lege CSV-cellen worden geïmporteerd als lege tekenreeksen.

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 objecten zijn (bijv. arrays of primitieven) worden overgeslagen en meegeteld als overgeslagen rijen.
• 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. Klaviyo haalt records uit het bestand en schrijft ze vervolgens in batches van maximaal 500 naar de gegevensbron.
4. Records worden aan de gegevensbron toegevoegd via hetzelfde ingestieproces voor aangepaste objecten dat wordt gebruikt voor records die via de API worden verzonden.
5. Je ontvangt een voltooiingsmelding (e-mail of in het product) wanneer de taak is voltooid.

Foutafhandeling

• Klaviyo slaat CSV-rijen met een onjuist aantal kolommen en ongeldige JSONL-regels over en gaat vervolgens verder met verwerken. Als een deel van een CSV-bestand niet kan worden geparsed, worden alle rijen in dat deel overgeslagen.
• Controleer de voltooiingsmelding voor het aantal verwerkte en overgeslagen rijen. Ongeldige JSONL-regels worden meegeteld als overgeslagen rijen; er wordt geen downloadbaar foutbestand op rijniveau gemaakt voor JSONL-bestanden.
• 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: import uit datawarehouse

Overzicht

Als je Snowflake, Databricks of BigQuery gebruikt, kun je een datawarehousesynchronisatie configureren om rechtstreeks aangepaste objectrecords te importeren. Verbind je warehouse, selecteer een tabel of weergave en kies Aangepaste objecten als het gegevensobjecttype. Kies vervolgens de Klaviyo-gegevensbron die de records ontvangt.

Voordat je begint, koppel je datawarehouse aan Klaviyo en zorg je ervoor dat de tabel of weergave die je wilt synchroniseren toegankelijk is. Bekijk voor vereisten voor abonnementen en handleidingen voor het maken van een verbinding Inzicht in import uit datawarehouse in Klaviyo.

De synchronisatie configureren

1. Ga naar Gegevensbeheer > Synchroniseren en open je datawarehouseverbinding.
2. Klik op Bron toevoegen om een nieuwe synchronisatie te maken. Om een synchronisatie te bewerken, open je het rijmenu en selecteer je Bewerken.
3. Voer een synchronisatie- naam in en selecteer de warehousetabel of -weergave bij gegevensbron. Selecteer onder typen gegevensobjecten aangepaste objecten.
4. Kies de cadans. Voor automatische imports selecteer je Geplande uitvoering en configureer je het schema. Selecteer Handmatig voor imports die je zelf start. Als je een nieuwe sync maakt, klik je op Volgende.
5. Selecteer onder Detectie van wijzigingen een kolom in Detectie van nieuwe rijen die aangeeft wanneer elke rij is toegevoegd of gewijzigd. De kolom moet een datetime-waarde bevatten of een waarde die kan worden omgezet naar een datetime.
6. Kies onder Gegevensbron voor aangepast object de Gegevensbronmodus:
   • Synchroniseren met bestaande gegevensbron: selecteer de bestemming onder Selecteer een gegevensbron. Zorg ervoor dat de kolomnamen van het magazijn overeenkomen met de broneigenschapnamen die worden gebruikt in je aangepaste objecttoewijzingen. Als je de gegevensbron wijzigt, worden toekomstige gesynchroniseerde records omgeleid naar die bron.
   • Nieuwe gegevensbron maken: voer een unieke naam van de gegevensbron in. Klaviyo stelt Data Sync: {table_name} voor, wat je kunt wijzigen. De gegevensbron wordt gemaakt wanneer je de synchronisatie opslaat.
7. Klik op Klaar om de synchronisatie te maken, of op Opslaan als je een bestaande synchronisatie bewerkt. Een nieuwe synchronisatie is actief zodra deze is opgeslagen. Als je zelf een import wilt starten, open je de synchronisatie en klik je op Synchronisatie uitvoeren.

Synchronisatiegedrag

• Records worden verwerkt in batches van maximaal 500 per aanroep.
• Import uit datawarehouse voor aangepaste objecten levert geen downloadbaar foutenbestand op rijniveau op.
• Open het tabblad Uitvoeringen van de sync om de uitvoeringsstatus en verwerkingsvoortgang te controleren. Open Logboeken voor details over synchronisatiefouten.

Na het importeren

Als een of meer aangepaste objecten al actief zijn met die gegevensbron, worden de geïmporteerde records verwerkt met behulp van de mappingen van die objecten, net zoals dat zou gebeuren als je records van de gegevensbron via de API zou toevoegen.

Als er nog geen aangepast object gebruikmaakt van de gegevensbron, kun je er een maken met de geïmporteerde records. Door eerst minstens 1 record te importeren, kun je de velden ervan bekijken tijdens het mappen. Selecteer bij het maken van het object de gegevensbron die voor deze import is gebruikt. Volg Aan de slag met aangepaste objecten om het object verder te configureren en te publiceren.