Massinmatning av anpassade objekt

Du kan massimportera anpassade objektposter med hjälp av två metoder: SFTP och Import av datalager (DWH).  Med båda metoderna kan du läsa in råa poster i en datakälla, som du sedan ansluter till en anpassad objekttyp i Klaviyo UI.

Den här artikeln beskriver hur varje metod fungerar, hur du formaterar dina filer och vad du kan förvänta dig under och efter importen.

Innan du börjar

Bekanta dig med anpassade objekt. Se Komma igång med anpassade objekt och översikten Custom Objects API.

Det finns några delar av funktionen Anpassade objekt att tänka på när du konfigurerar massinmatning/synkronisering:

• En Data Source för anpassade objekt Data Source är ett flexibelt, användardefinierat schema. En Data Source Record representerar en post i en Data Source. Observera att dessa finns kvar i Klaviyo, så att du kan skapa olika scheman/objekt i framtiden från Data Source Records som du har läst in tidigare.
• Ett anpassat objekt består av ett objektschema och ett mappningsschema mellan en datakälla och objektet.
• Olika anpassade objekt kan mappas till en enda datakälla, med antingen samma eller olika fältmappningar.

För att importera anpassade objekt från SFTP behöver du ID:t för den datakälla där du vill skapa datakällposter. Du kan skapa detta via API eller i webbgränssnittet när du skapar ett nytt anpassat objekt. Observera att detta också kan skapas automatiskt under den första synkroniseringscykeln för en datalagersynkronisering för anpassade objekt.

Metod 1: SFTP-import

Datakälla

Identifiera data käll-ID:t för anpassade objekt som du vill rikta importen mot och skapa en config.json -fil med ID:t, så här:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Katalogstruktur

Skapa en ny mapp i /imports/custom_objects/ från SFTP-roten. Mappens namn påverkar inte hur data bearbetas.

Kopiera din config.json -fil, som innehåller data_source_id, till den nya mappen.

Placera datafilerna som du vill ladda upp i den nya mappen. *.csv av *.jsonl filer kommer att bearbetas.

{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

Filer som placeras direkt under custom_objects/ utan en underkatalog kommer att avvisas. Varje import av anpassade objekt måste ligga i en namngiven undermapp.

Filformat som stöds

JSONL rekommenderas starkt när dina poster innehåller inbäddade data eller arrayer.

CSV-formatering

• Den första raden måste vara en rubrik. Kolumnnamnen måste motsvara datakällans definition.
• Inbäddad JSON i en CSV-cell måste vara inom dubbla citattecken och interna citattecken måste föregås av dubbla citattecken (t.ex. "").
• Tomma celler behandlas som frånvarofält, inte som nollvärden.

Exempel på 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-formatering

• Varje rad måste vara ett giltigt JSON-objekt ({...}).
• Rader som inte är objekt (till exempel arrayer eller primitiver) hoppas över och räknas som fel.
• Tomma rader ignoreras tyst.
• Kapslade objekt och arrayer skickas igenom och lagras i sin helhet.

Exempel på 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"]}}

Vad händer under importen

1. Klaviyo identifierar sökvägen till underkatalogen och avgör att resurstypen är custom_objects.
2. Klaviyo kontrollerar om det finns en datakälla för anpassade objekt med data_source_id i config.json i Kontot.
3. Registren extraheras och behandlas i omgångar om upp till 500 poster per omgång.
4. Varje batch skrivs till datakällan via samma pipeline som används av bulk-API:et.
5. Du får ett meddelande om slutförande (e-post eller i produkten) när jobbet är klart.

Felhantering

• Ogiltiga rader (felformaterade CSV-rader eller JSONL-rader som inte kan tolkas) hoppas över. Jobbet fortsätter att behandla resten av filen.
• Meddelandet om slutförande innehåller ett antal överhoppade rader och en sammanfattning av eventuella fel som uppstått.
• Om mappen inte har någon .config.json eller om datakällans ID i konfigurationen är ogiltigt kommer filen inte att behandlas. För att försöka igen måste du ladda upp filen igen med ett annat namn. Gamla filer kommer att tas bort efter 30 dagar.

Metod 2: Import av datalager

Översikt

Om du använder Snowflake, Databricks eller BigQuery kan du konfigurera en datalagersynkronisering för att importera anpassade objekt direkt. Konfigurationsflödet är detsamma som för profiler och händelser – anslut ditt lager, välj en tabell eller vy och välj Anpassat objekt som resurstyp.

Konfigurera synkroniseringen

1. Gå till Integrationer > Datalager och öppna din lageranslutning.
2. Skapa en ny importsynkronisering eller redigera en befintlig.
3. Under Resurstyp väljer du Anpassat objekt.
4. Välj den datakälla som du vill skicka posterna till.
   1. För en befintlig datakälla: Datalagerkolumnnamn måste matcha datakälldefinitionen.
   2. Om det ännu inte finns någon datakälla skapas en automatiskt vid den första synkroniseringskörningen med namnet ”Datasynkronisering: {sync_name}”. Du kan ändra detta namn efter behov. Observera att du inte kommer att kunna konfigurera nya objekt förrän minst en post har importerats (för att upprätta datakällschemat).
5. Spara och aktivera synkroniseringen.

Synkroniseringsbeteende

• Posterna behandlas i omgångar på upp till 500 per samtal.
• Misslyckade rader skrivs till en nedladdningsbar felfil med detaljer på radnivå (t.ex. felformaterade värden, saknade identifierare).
• Varje synkroniseringskörning genererar en loggpost som kan visas på fliken Loggar i synkroniseringen, med information om extrahering, transformation, inläsningsförlopp och eventuella fel.

Efter import: om du använder en befintlig datakälla

Om ett eller flera anpassade objekt redan är konfigurerade med den datakällan skapas de från de nya datakällposterna precis som de skulle ha varit om du lade till datakällposter via API.

Om inga anpassade objekt ännu använder denna datakälla kan du använda guiden Nytt objekt för att skapa ett nytt objekt och välja den datakälla som används i din synkronisering. Se till att minst en post har importerats så att datakällschemat har upprättats.