Zbiorcze pozyskiwanie obiektów niestandardowych

Możesz zbiorczo zaimportować rekordy niestandardowych obiektów przy użyciu dwóch metod: SFTP oraz import z hurtowni danych.  Obie metody umożliwiają ładowanie rekordów nieprzetworzonych do źródła danych, które następnie łączy się z niestandardowym typem obiektu w interfejsie użytkownika Klaviyo.

Z tego artykułu dowiesz się, jak działają poszczególne metody, jak formatować pliki oraz czego można się spodziewać podczas importu i po nim.

Kilka słów na początek

Zapoznaj się z obiektami niestandardowymi. Zobacz Pierwsze kroki z obiektami niestandardowymi oraz omówienie API obiektów niestandardowych.

Podczas konfigurowania funkcji zbiorczego pozyskiwania/synchronizacji należy pamiętać o kilku elementach obiektów niestandardowych:

• Źródło danych obiektów niestandardowych to elastyczny, zdefiniowany przez użytkownika schemat. Rekord źródła danych reprezentuje rekord w źródle danych. Pamiętaj, że pozostają one w Klaviyo, co pozwala w przyszłości tworzyć różne schematy/obiekty na podstawie rekordów źródła danych, które wczytano wcześniej.
• Sam obiekt niestandardowy składa się ze schematu obiektu oraz schematu mapowania między źródłem danych a obiektem.
• Do jednego źródła danych można zmapować różne obiekty niestandardowe przy użyciu tego samego lub różnych mapowań pól.

Aby zaimportować obiekty niestandardowe z SFTP, będziesz potrzebować identyfikatora źródła danych, w którym chcesz utworzyć rekordy źródła danych. Można to utworzyć za pośrednictwem interfejsu API lub w internetowym interfejsie użytkownika podczas tworzenia nowego obiektu niestandardowego. Pamiętaj, że ta opcja może być również utworzona automatycznie podczas pierwszej synchronizacji w hurtowniach danych dla obiektów niestandardowych.

Metoda 1: import SFTP

Źródło danych

Zidentyfikuj identyfikator źródła danych obiektów niestandardowych, który chcesz objąć importem, i utwórz plik config.json z tym identyfikatorem, na przykład tak:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Struktura katalogów

W katalogu głównym SFTP utwórz nowy folder w /imports/custom_objects/. Nazwa folderu nie wpływa na sposób przetwarzania danych.

Skopiuj plik config.json, który zawiera data_source_id, do nowego folderu.

Umieść pliki danych, które chcesz przesłać, w nowym folderze. Pliki *.csv i *.jsonl zostaną przetworzone.

{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

Pliki umieszczone bezpośrednio w custom_objects/ bez podkatalogu zostaną odrzucone. Każdy import obiektu niestandardowego musi znajdować się w nazwanym podfolderze.

Obsługiwane formaty plików

Zdecydowanie zaleca się używanie formatu JSONL, jeśli Twoje rekordy zawierają dane zagnieżdżone lub tablice.

Formatowanie pliku CSV

• Pierwszy wiersz musi być wierszem nagłówka. Nazwy kolumn muszą odpowiadać definicji źródła danych.
• Zagnieżdżony kod JSON w komórce CSV musi być ujęty w podwójny cudzysłów, a wewnętrzne cudzysłowy muszą być poprzedzone podwójnym cudzysłowem (np. "").
• Puste komórki są traktowane jako brakujące pola, a nie wartości null.

Przykładowy plik CSV:

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

Formatowanie JSONL

• Każdy wiersz musi być prawidłowym obiektem JSON ({...}).
• Linie, które nie są obiektami (np. tablice lub prymitywy), są pomijane i liczone jako błędy.
• Puste wiersze są dyskretnie ignorowane.
• Zagnieżdżone obiekty i tablice są przekazywane i przechowywane w całości.

Przykładowy kod 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"]}}

Co dzieje się podczas importu

1. Klaviyo wykrywa ścieżkę podkatalogu i określa, że typ zasobu to custom_objects.
2. Klaviyo sprawdza, czy na koncie istnieje źródło danych obiektów niestandardowych z data_source_id w config.json.
3. Rekordy są wyodrębniane i przetwarzane w partiach po maksymalnie 500 rekordów.
4. Każda partia jest zapisywana w źródle danych za pośrednictwem tego samego potoku, którego używa zbiorczy interfejs API.
5. Po zakończeniu zadania otrzymasz powiadomienie o zakończeniu (e-mailem lub w usłudze).

Obsługa błędów

• Nieprawidłowe wiersze (nieprawidłowy plik CSV lub wiersze JSONL, których nie można przeanalizować), są pomijane. Zadanie kontynuuje przetwarzanie pozostałej części pliku.
• Powiadomienie o ukończeniu zawiera liczbę pominiętych wierszy i podsumowanie wszelkich napotkanych błędów.
• Jeśli folder nie ma .config.json lub identyfikator źródła danych w konfiguracji jest nieprawidłowy, plik nie zostanie przetworzony. Aby spróbować ponownie, musisz przesłać plik jeszcze raz pod inną nazwą. Stare pliki zostaną usunięte po 30 dniach.

Metoda 2: import z hurtowni danych

Przegląd

Jeśli korzystasz z platform Snowflake, Databricks lub BigQuery, możesz skonfigurować synchronizację danych bezpośrednio w celu bezpośredniego importu obiektów niestandardowych hurtownię danych. Konfiguracja sekwencji jest taka sama jak w przypadku profilu i zdarzeń – połącz hurtownię, wybierz tabelę lub widok oraz obiekt niestandardowy jako typ zasobu.

Konfigurowanie synchronizacji

1. Wybierz system integracje > hurtownia danych i otwórz połączenie z hurtownią.
2. Utwórz nową synchronizację importu lub edytuj istniejącą.
3. W sekcji Typ zasobu wybierz opcję Obiekt niestandardowy.
4. Wybierz źródło danych, do którego chcesz przekierować rekordy.
   1. W przypadku istniejącego źródła danych: hurtownia danych: nazwy kolumn muszą być zgodne z definicjami źródła danych.
   2. Jeśli żadne źródło danych nie istnieje, zostanie ono utworzone automatycznie przy pierwszej synchronizacji i nazwie „Synchronizacja danych: {sync_name}”. Nazwę tę można dowolnie modyfikować. Pamiętaj, że konfigurowanie nowych obiektów będzie możliwe dopiero po zaimportowaniu co najmniej jednego rekordu (w celu ustanowienia schematu źródła danych).
5. Zapisz i aktywuj synchronizację.

Zachowanie synchronizacji

• Rekordy są przetwarzane partiami po 500 na wywołanie.
• Wiersze z błędami są zapisywane w możliwym do pobrania pliku błędów ze szczegółami na poziomie wiersza (np. zniekształconymi wartościami, brakującymi identyfikatorami).
• Każda synchronizacja generuje wpis w dzienniku, który można wyświetlić na karcie Dzienniki synchronizacji. Zawiera on szczegóły dotyczące wyodrębniania, przekształcania, postępu ładowania i wszelkich błędów.

Po zaimportowaniu: w przypadku korzystania z istniejącego źródła danych

Jeśli dla tego źródła danych skonfigurowano już jeden lub więcej obiektów niestandardowych, zostaną one utworzone na podstawie rekordów nowego źródła danych tak samo, jak w przypadku dodawania rekordów źródła danych za pośrednictwem interfejsu API.

Jeśli żaden obiekt niestandardowych nie korzysta jeszcze z tego źródła danych, użyj Kreatora nowego obiektu, aby utworzyć nowy obiekt i wybrać źródło danych używane w synchronizacji. Upewnij się, że zaimportowano co najmniej jeden rekord, aby ustanowić schemat źródła danych.