Łączenie Klaviyo i Snowflake

Na potrzeby tego artykułu używamy terminu "tabela", ale widoki, widoki zmaterializowane i tabele są prawidłowymi obiektami Snowflake, które można importować. Tak długo, jak Klaviyo może uruchomić SELECT col1 FROM nazwa_tabeli na obiekcie, możesz swobodnie używać tego, co wolisz. 

Słowa kluczowe "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" i "OPTIONAL" w tym dokumencie należy interpretować zgodnie z opisem w RFC 2119.

Konfiguracja administratora płatków śniegu

W tej sekcji opisano kroki, które należy wykonać w środowisku Snowflake, aby umożliwić Klaviyo zaimportowanie danych. 

1. Wygeneruj klucz prywatny, uruchamiając następujące polecenie w lokalnym terminalu:

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

2. Wygeneruj klucz publiczny, który odwołuje się do klucza prywatnego, uruchamiając następujące polecenie w terminalu:

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

3. Skopiuj plik rsa_key.pub i wklej go do poniższego skryptu, aby zastąpić wartość zastępczą "GENERATE_PUBLIC_KEY" dla user_rsa_public_key. Poniższy skrypt będzie działał dla użytkowników komputerów Mac lub możesz otworzyć rsa_key.pub w IDE i skopiować całą zawartość pliku, jeśli wolisz. 

# Polecenie terminala Mac, aby zapisać klucz w terminalu i skopiować go do schowka
cat rsa_key.pub | tee /dev/tty | pbcopy

4. Uruchom poniższy skrypt w środowisku Snowflake, aby utworzyć użytkownika usługi dla Klaviyo. Musisz mieć uprawnienia securityadmin i sysadmin, aby ukończyć poniższą konfigurację. Aby sprawdzić, jakie role posiadasz, uruchom SHOW GRANTS TO USER <your_username> i upewnij się, że na liście znajdują się obie role. Skontaktuj się z administratorem systemu, jeśli chcesz dostosować swoją rolę.
   1. Możesz swobodnie aktualizować dowolne zmienne ustawione na początku skryptu.
   2. Podsumowując, będziesz:
      1. Wybierz istniejący magazyn lub utwórz nowy
      2. Wybierz istniejącą bazę danych lub utwórz nową, aby przechowywać nowe schematy.
      3. Utwórz dwa nowe schematy KLAVIYO_TMP i KLAVIYO_IMPORT_FROM_DWH.
      4. Utwórz nową politykę sieciową i zezwól na listę Klaviyo adresów IP.
      5. Utwórz użytkownika i rolę dla Klaviyo
   3. Ten skrypt jest idempotentny (może być bezpiecznie uruchamiany wiele razy), ale nie nadpisze istniejących obiektów o sprzecznych nazwach. 

BEGIN;

-- utwórz zmienne dla użytkownika / hasła / roli / magazynu / bazy danych. 
-- Zmień je na dowolne inne.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; -- wszystkie litery muszą być wielkie, np. 'KLAVIYO_DATA_TRANSFER_ROLE'
SET user_name = 'KLAVIYO_DATA_TRANSFER_USER'; -- wszystkie litery muszą być wielkie, np. 'KLAVIYO_DATA_TRANSFER_USER'
SET warehouse_name = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; -- wszystkie litery muszą być wielkie, np. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'
SET database_name = 'KLAVIYO_DATABASE'; -- wszystkie litery muszą być wielkie, np. 'KLAVIYO_DATABASE'. Jeśli ta baza danych nie istnieje, zostanie utworzona nowa.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; -- wszystkie litery muszą być wielkie, np. 'KLAVIYO_NETWORK_POLICY'
SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; -- wszystkie litery muszą być wielkie, np. 'KLAVIYO_NETWORK_RULE'
/* replace GENERATE_PUBLIC_KEY below with generated public key */

-- DO NOT CHANGE
SET schema_name_tmp = $database_name || '.KLAVIYO_TMP'; -- DO NOT CHANGE
SET schema_name_import = $database_name || '. KLAVIYO_IMPORT_FROM_DWH'; -- NIE ZMIENIAJ
SET full_network_rule_tmp = $schema_name_tmp || '.' || $network_rule; -- NIE ZMIENIAJ
SET full_network_rule_import = $schema_name_import || '.' || $network_rule; -- NIE ZMIENIAJ


-- zmień rolę na sysadmin dla kroków magazynu / bazy danych
USE ROLE sysadmin;

-- utwórz magazyn dla usługi transferu danych
CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($warehouse_name)
 warehouse_size = xsmall
 warehouse_type = standard
 auto_suspend = 60
 auto_resume = true
 initially_suspended = true;

-- utwórz bazę danych dla usługi transferu danych
CREATE DATABASE IF NOT EXISTS IDENTIFIER($database_name);

-- utwórz schematy dla usługi transferu danych
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_tmp);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_import);

-- change role to securityadmin for user / role steps
USE ROLE securityadmin;

-- create network  reguła i polityka dla bazy danych
GRANT USAGE ON DATABASE IDENTIFIER($database_name) TO ROLE securityadmin;
GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE securityadmin;
GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE securityadmin;

-- whitelist Klaviyo ip ranges, for KLAVIYO_TMP schema 
CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_tmp)
 type = IPV4
 value_list = (
 '184.72.183.187/32', '52.206.71.52/32', '3.227.146.32/32', '44.198.39.11/32', '35.172.58.121/32', '3.228.37.244/32', '54.88.219.8/32', '3.214.211.176/32'
 )
 comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
 allowed_network_rule_list = ($full_network_rule_tmp);

-- whitelist Klaviyo ip ranges, for KLAVIYO_IMPORT_FROM_DWH schema 
CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_import)
 type = IPV4
 value_list = (
 '184.72.183.187/32', '52.206.71.52/32', '3.227.146.32/32', '44.198.39.11/32', '35.172.58.121/32', '3.228.37.244/32', '54.88.219.8/32', '3.214.211.176/32'
 )
 comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
allowed_network_rule_list = ($full_network_rule_import);


-- utwórz rolę dla usługi transferu danych
CREATE ROLE IF NOT EXISTS IDENTIFIER($role_name);
GRANT ROLE IDENTIFIER($role_name) TO ROLE sysadmin;

-- utwórz użytkownika dla usługi transferu danych
CREATE USER IF NOT EXISTS IDENTIFIER($user_name)
 type = SERVICE
 network_policy = $network_policy
 default_role = $role_name
 default_warehouse = $warehouse_name
 rsa_public_key = 'GENERATE_PUBLIC_KEY';
GRANT ROLE IDENTIFIER($role_name) TO USER IDENTIFIER($user_name);
ALTER USER IDENTIFIER($user_name) SET NETWORK_POLICY = $network_policy;

-- grant service role access to warehouse
GRANT USAGE
 ON WAREHOUSE IDENTIFIER($warehouse_name)
 TO  ROLE IDENTIFIER($role_name);

-- Przyznaj dostęp serwisowy do bazy danych
GRANT monitorować, USAGE
 ON DATABASE IDENTIFIER($database_name)
 TO ROLE IDENTIFIER($role_name);

-- Przyznaj uprawnienia dla KLAVIYO_TMP 
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);
GRANT monitorować, USAGE, CREATE TABLE, CREATE VIEW, CREATE SEQUENCE, CREATE FUNCTION, CREATE PROCEDURE
 ON SCHEMA IDENTIFIER($schema_name_tmp)
 TO ROLE IDENTIFIER($role_name);
GRANT ALL ON FUTURE TABLES IN SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);

-- Grant privileges for KLAVIYO_IMPORT_FROM_DWH
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE IDENTIFIER($role_name);
GRANT SELECT
 ON FUTURE TABLES
 IN SCHEMA IDENTIFIER($schema_name_import)
 TO ROLE IDENTIFIER($role_name);

COMMIT;

Konfiguracja danych płatka śniegu

Powyżej utworzyłeś dwa nowe schematy. 

• KLAVIYO_TMP będzie używany wyłącznie przez Klaviyo. NIE MOŻESZ modyfikować żadnych tabel utworzonych w tym schemacie. Klaviyo usunie te tabele, gdy nie będą już potrzebne.
• KLAVIYO_IMPORT_FROM_DWH to miejsce, w którym powinieneś sklep internetowy swoje tabele końcowe dla Klaviyo zaimportować. Gdy przejdziesz przez proces tworzenia synchronizacji, wszystkie tabele w tym schemacie zostaną wyświetlone do wyboru. W związku z tym POWINIENEŚ importować tylko tabele końcowe, które chcesz zaimportować, aby uniknąć nieporozumień podczas konfiguracji. 

plan Wszystkie tabele, które chcesz zaimportować do Klaviyo muszą spełniać następujące kryteria. 

Wymagania dotyczące znacznika czasu 

1. Tabele MUSZĄ zawierać pole znacznika czasu, które wskazuje, kiedy wiersz został utworzony lub zaktualizowany. Często będzie to inserted_at lub updated_at. Ustawisz to dla każdej tabeli podczas procesu tworzenia synchronizacji.
   1. Pole znacznika czasu MUSI być monotonicznie rosnące (tj. musi zawsze rosnąć lub pozostawać takie samo, nigdy nie może maleć).
   2. Po utworzeniu synchronizacji NIE MOŻESZ ustawiać wartości znacznika czasu wiersza na czas w przeszłości, w przeciwnym razie Klaviyo może nie odebrać tego wiersza.
   3. Strefa czasowa tego konkretnego pola nie jest ważna dla Klaviyo, o ile spełniasz powyższe wymagania
   4. Klaviyo ZALECA ustawienie pola znacznika czasu za pomocą funkcji CURRENT_TIMESTAMP() lub jej odpowiednika. Wiele wierszy może mieć ten sam znacznik czasu. Zobacz przykład poniżej. 

INSERT INTO table_name AS 

SELECT ... 

, CURRENT_TIMESTAMP() AS inserted_at

.... 

2. Twoje znaczniki czasu MUSZĄ być w UTC lub zawierać informacje o strefie czasowej. Jeśli brakuje informacji o strefie czasowej, Klaviyo przyjmie UTC. W przypadku właściwości niestandardowych znaczniki czasu pozostają w formacie ciągu znaków, co pozwala na ich interpretację w preferowanej strefie czasowej.

Struktura tabeli 

3. Tabele POWINNY być traktowane jako tylko dołączane (aka tylko wstawiane).
   1. Jeśli zamiast tego wolisz zaktualizować wiersze w miejscu, MUSISZ zaktualizować pole znacznika czasu, aby Klaviyo mógł zidentyfikować zmianę.
4. Tabele POWINNY być uporządkowane według kolumny znacznika czasu. Snowflake zajmie się klastrowaniem i partycjonowaniem w oparciu o twoją kolejność wstawiania. Pomoże to zoptymalizować zapytania importowe Klaviyo, utrzymując koszty obliczeniowe w Snowflake na niskim poziomie

Unikalność i spójność profilu 

5. MUSISZ upewnić się, że każdy profil właściwości jest importowany tylko z jednego źródła danych (tabeli). Klaviyo zapobiega wybieraniu tej samej właściwości z różnych tabel podczas tworzenia synchronizacji, upraszczając ten wymóg.
6. POWINIENEŚ używać tego samego identyfikatora profilu (e-mail, numer telefonu, identyfikator zewnętrzny itp.) we wszystkich tabelach importu, aby zminimalizować ryzyko utworzenia duplikatów profilu.
   1. Klaviyo utworzy nowy profil, jeśli podany identyfikator profilu nie pasuje do istniejącego profilu w Klaviyo.
   2. Przykład: Table1 (Email, fav_color) + Table2 (Phone, birthday)
      1. Może to spowodować utworzenie 2 profili dla tej samej osoby, jeśli profil ten obecnie nie istnieje. Jeśli profil istnieje, Klaviyo będzie wewnętrznie obsługiwać rozwiązywanie i aktualizację profilu. 
   3. Jednym ze sposobów uniknięcia tego problemu jest użycie tylko jednej tabeli importu dla wszystkich twoich profili. 

Zapobieganie pętli import-eksport w obiegu zamkniętym 

7. POWINIENEŚ ostrożnie zarządzać scenariuszami, w których używane są zarówno funkcje importu, jak i eksportu, aby zapobiec pętlom importu i eksportu. Upewnij się, że proces eksportu nie przekazuje danych z powrotem do tabeli, która znajduje się przed tabelą importu, ponieważ Klaviyo nie wykrywa obecnie takiego scenariusza.
   1. Klaviyo nie ma jeszcze logiki do wykrywania tego scenariusza.
   2. Wyglądałoby to mniej więcej tak:
      1. Podczas każdego cyklu synchronizacji eksportu, Klaviyo wyeksportuje wszystkie twoje profile.
      2. Następnie dodajesz wszystkie wyeksportowane profile do tabeli importu poprzez serię przekształceń.
      3. W każdym cyklu synchronizacji importu, Klaviyo odczyta wszystkie profile w twojej tabeli importu, które ostatecznie zostaną ponownie wyeksportowane
   3. Scenariusze, w których jest to prawdopodobnie bezpieczne 
      1. jeśli używasz tabeli eksportu tylko do ograniczenia wierszy dodawanych do tabeli importu
      2. Jeśli sprawdzisz, że tabela eksportu nie dodaje wierszy do tabeli importu.
   4. Jakie są konsekwencje pętli import-eksport?
      1. Spowoduje to niepotrzebne koszty obliczeniowe zarówno dla Ciebie, jak i Klaviyo.