Acquisizione in blocco di oggetti personalizzati

Puoi importare i record degli oggetti personalizzati in blocco utilizzando due metodi: SFTP e Importazione del magazzino dati (DWH).  Entrambi i metodi ti consentono di caricare i record grezzi in un'origine dati, che poi puoi connettere a un tipo di oggetto personalizzato nell'interfaccia utente di Klaviyo.

Questo articolo spiega come funziona ogni metodo, come formattare i tuoi file e cosa aspettarsi durante e dopo l'importazione.

Prima di iniziare

Per familiarizzare con gli oggetti personalizzati, consulta Primi passi con gli oggetti personalizzati e la panoramica di API degli oggetti personalizzati.

Ci sono alcune parti della funzionalità degli oggetti personalizzati da tenere a mente quando si configura l'acquisizione/sincronizzazione in blocco:

• Un origine dati di oggetti personalizzati è uno schema flessibile definito dall’utente. Un record dell’origine dati rappresenta un record in un’origine dati. Tieni presente che questi elementi persistono in Klaviyo, consentendoti di creare in futuro schemi/oggetti diversi a partire dai record dell’origine dati che hai caricato in passato.
• Un oggetto personalizzato è costituito da uno schema di oggetto e da uno schema di mappatura tra un'origine dati e l'oggetto.
• È possibile mappare diversi oggetti personalizzati su un'unica origine dati utilizzando la stessa mappatura o mappature di campi diverse.

Per importare oggetti personalizzati da SFTP, hai bisogno dell'ID della fonte dei dati in cui desideri creare i record della fonte dei dati. Puoi crearlo tramite API o nell'interfaccia utente web quando crei un nuovo oggetto personalizzato. Nota: questa opzione può essere creata automaticamente anche durante il primo ciclo di sincronizzazione di un magazzino dati per gli oggetti personalizzati.

Metodo 1: importazione SFTP

Origine dei dati

Identifica l'ID dell'origine dati degli oggetti personalizzati che vuoi indirizzare con l'importazione e crea un file config.json con l'ID, come questo:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Struttura della directory

Dalla root SFTP, crea una nuova cartella in /imports/custom_objects/. Il nome della cartella non influisce sul modo in cui i dati vengono elaborati.

Copia il file config.json, che contiene data_source_id, nella nuova cartella.

Inserisci i file di dati che vuoi caricare nella nuova cartella. I file *.csv e *.jsonl verranno elaborati.

{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

I file inseriti direttamente in custom_objects/ senza una sottodirectory verranno rifiutati. Ogni importazione di oggetti personalizzati deve trovarsi all'interno di una sottocartella con nome.

Formati file supportati

JSONL è fortemente consigliato quando i tuoi record contengono dati o matrici nidificati.

Formattazione CSV

• La prima riga deve essere una riga di intestazione. I nomi delle colonne devono corrispondere alla definizione dell'origine dati.
• Il JSON nidificato all'interno di una cella CSV deve essere racchiuso tra virgolette doppie e le virgolette interne devono essere precedute dal carattere di escape con virgolette doppie (ad esempio, "").
• Le celle vuote vengono trattate come campi assenti, non come valori Null.

Esempio di file CSV:

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

Formattazione JSONL

• Ogni riga deve essere un oggetto JSON valido ({...}).
• Le linee che non sono oggetti (ad esempio, matrici o primitive) vengono saltate e conteggiate come errori.
• Le righe vuote vengono ignorate in silenzio.
• Gli oggetti nidificati e le matrici vengono attraversati e conservati per intero.

Esempio di 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"]}}

Cosa succede durante l'importazione

1. Klaviyo rileva il percorso della sottodirectory e determina che il tipo di risorsa è custom_objects.
2. Klaviyo verifica se nell'account esiste un'origine dati di oggetti personalizzati con data_source_id in config.json.
3. I record vengono estratti ed elaborati in lotti con un massimo di 500 record per lotto.
4. Ogni batch viene scritto nella fonte dei dati tramite la stessa pipeline utilizzata dal API in blocco.
5. Ricevi una notifica di completamento (via e-mail o in prodotto) al termine del processo.

Gestione degli errori

• Le righe non valide (CSV in formato non valido o righe JSONL non analizzabili) vengono saltate. Il processo continua a elaborare il resto del file.
• La notifica di completamento include un conteggio delle righe saltate e un riepilogo degli errori riscontrati.
• Se la cartella non ha .config.json o l'ID origine dati nella configurazione non è valido, il file non verrà elaborato. Per riprovare, devi caricare di nuovo il file con un nome diverso. I file vecchi verranno rimossi dopo 30 giorni.

Metodo 2: Importazione del magazzino dati

Panoramica

Se utilizzi Snowflake, Databricks o BigQuery, puoi configurare la sincronizzazione di un magazzino dati per importare direttamente gli oggetti personalizzati. Il flusso di configurazione è lo stesso di profili ed eventi: collega il tuo magazzino, seleziona una tabella o una vista e scegli Oggetto personalizzato come tipo di risorsa.

Configurazione della sincronizzazione

1. Vai su Integrazioni > Magazzino dati e apri la connessione al tuo magazzino dati.
2. Crea una nuova sincronizzazione dell'importazione o modificane una esistente.
3. Alla voce Tipo di risorsa, seleziona Oggetto personalizzato.
4. Seleziona l'origine dati a cui vuoi indirizzare i record.
   1. Per un'origine dati esistente: i nomi delle colonne del magazzino dati devono corrispondere alla definizione dell'origine dati.
   2. Se non esiste ancora alcuna origine dati, ne verrà creata una automaticamente alla prima esecuzione di sincronizzazione denominata "Sincronizzazione dati: {sync_name}". Puoi modificare questo nome come desideri. Tieni presente che non sarai in grado di configurare nuovi oggetti finché non sarà stato importato almeno un record (per stabilire lo schema della fonte dei dati).
5. Salva e attiva la sincronizzazione.

Comportamento di sincronizzazione

• I record vengono elaborati in lotti fino a 500 per chiamata.
• Le righe non riuscite vengono scritte in un file di errore scaricabile con dettagli a livello di riga (ad esempio, valori non validi, identificatori mancanti).
• Ogni esecuzione di sincronizzazione genera una voce di registro visualizzabile nella scheda Registri della sincronizzazione, con dettagli sull'estrazione, la trasformazione, l'avanzamento del caricamento e qualsiasi errore.

Dopo l'importazione: se si utilizza una fonte di dati esistente

Se uno o più oggetti personalizzati sono già configurati con tale origine dati, verranno creati dai nuovi record della fonte dati proprio come se si aggiungessero i record della fonte dati tramite API.

Se non ci sono ancora oggetti personalizzati che utilizzano quella fonte di dati, utilizza la procedura guidata Nuovo oggetto per creare un nuovo oggetto e seleziona la fonte di dati utilizzata nella tua sincronizzazione. Assicurati che almeno un record sia stato importato in modo da stabilire lo schema dell'origine dati.