SFTP 経由でのカスタムオブジェクトのインポートとデータウェアハウス同期

推定 1 分で読めます

更新日 2026年6月28日 0:00 EST

カスタムオブジェクトの一括取り込み

2 つの方法（SFTP と データウェアハウスのインポート（DWH））を使用して、カスタムオブジェクトレコードを一括でインポートできます。どちらの方法でも、生のレコードをデータソースに読み込み、その後 Klaviyo UI でカスタムオブジェクトタイプに接続できます。

この記事では、各方法の仕組み、ファイルの形式設定方法、インポート中およびインポート後に想定される内容について説明します。

始める前に

カスタムオブジェクトについて理解を深めるには、カスタムオブジェクトのスタートガイドおよびカスタムオブジェクト APIの概要をご覧ください。

一括取り込み/同期を設定する際に、カスタムオブジェクト機能について留意すべき点がいくつかあります：

カスタムオブジェクトのデータソースは、柔軟なユーザー定義スキーマです。データソースレコードは、データソース内のレコードを表します。これらは Klaviyo に保持されるため、過去に読み込んだデータソースレコードから、将来的に異なるスキーマ／オブジェクトを作成できます。
カスタムオブジェクト自体は、オブジェクトスキーマと、データソースとオブジェクト間のマッピングスキーマで構成されます。
異なるカスタムオブジェクトは、同一または異なるフィールドマッピングを使用して、単一のデータソースにマッピングできます。

SFTP からカスタムオブジェクトをインポートするには、データソースレコードを作成するデータソースの ID が必要です。これは、API を介して、または新しいカスタムオブジェクトを作成する際にウェブ UI で作成できます。これは、カスタムオブジェクト用のデータウェアハウス同期の初回同期サイクル中に自動的に作成することもできますのでご注意ください。

方法 1: SFTP インポート

データソース

インポートでターゲットにするカスタムオブジェクトのデータソース ID を特定し、次のように ID を含む config.json ファイルを作成します。

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

ディレクトリ構造

SFTP ルートから、/imports/custom_objects/ に新しいフォルダを作成します。フォルダ名はデータの処理方法に影響しません。

data_source_id を含む config.json ファイルを新しいフォルダにコピーします。

アップロードするデータファイルを新しいフォルダに配置します。*.csv と *.jsonl のファイルが処理されます。

{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

サブディレクトリなしで custom_objects/ の直下に配置されたファイルは拒否されます。すべてのカスタムオブジェクトのインポートは、名前付きサブフォルダ内に配置する必要があります。

サポートされているファイル形式

フォーマット	拡張機能	注意
CSV	`.csv`	列名はデータソース定義に対応している必要があります。
JSONL	`.jsonl`	1 行につき 1 つの JSON オブジェクト。プロパティ名はデータソース定義に対応している必要があります。ネストされたオブジェクトと配列がサポートされ、そのまま保存されます。

レコードにネストされたデータや配列が含まれる場合は、JSONL を強く推奨します。

CSV の書式設定

最初の行はヘッダー行である必要があります。列名はデータソースの定義に対応している必要があります。
CSV セル内のネストされた JSON は二重引用符で囲み、内部の引用符は二重引用符文字でエスケープする必要があります（例：""）。
空のセルは、null 値ではなく存在しないフィールドとして扱われます。

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 の書式設定

各行は有効な JSON オブジェクト（{...}）である必要があります。
オブジェクトではない行（配列やプリミティブなど）はスキップされ、エラーとしてカウントされます。
空行は通知なしで無視されます。
ネストされたオブジェクトと配列は、そのまま渡され、全体が保存されます。

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

インポート中に起こること

Klaviyo はサブディレクトリパスを検出し、リソースタイプが custom_objects であると判断します。
Klaviyo は、アカウント内に config.json の data_source_id を含むカスタムオブジェクトのデータソースが存在するかどうかを確認します。
レコードは、1 バッチあたり最大500 レコードのバッチで抽出および処理されます。
各バッチは、Bulk API で使用されるのと同じパイプラインを介してデータソースに書き込まれます。
ジョブが完了すると、完了通知（メールまたは製品内）を受け取ります。

エラー処理

無効な行（形式が不正な CSV または解析できない JSONL 行）はスキップされます。ジョブはファイルの残りの部分の処理を継続します。
完了通知には、スキップされた行数と、発生したエラーの概要が含まれます。
フォルダに .config.json がない場合、または設定内のデータソース ID が無効な場合、ファイルは処理されません。再試行するには、別の名前でファイルを再度アップロードする必要があります。古いファイルは 30 日後に削除されます。

方法 2: データウェアハウスのインポート

概要

Snowflake、Databricks、または BigQuery を使用している場合は、データウェアハウスの同期を設定して、カスタムオブジェクトを直接インポートできます。設定フローはプロファイルとイベントの場合と同じです。データウェアハウスを接続し、テーブルまたはビューを選択してから、リソースタイプとして カスタムオブジェクト を選択します。

同期の設定

[外部連携] > [データウェアハウス] に移動し、ウェアハウス接続を開きます。
新しいインポート同期を作成するか、既存のものを編集してください。
リソースタイプ で、カスタムオブジェクト を選択します。
レコードのルーティング先として使用する データソース を選択してください。
1. 既存のデータソースの場合：データウェアハウスの列名はデータソース定義と一致している必要があります。
2. データソースがまだ存在しない場合は、最初の同期実行時に自動的に作成され、「Data Sync: {sync_name}」という名前が付けられます。必要に応じて、この名前は変更できます。なお、少なくとも 1 件のレコードがインポートされるまで（データソーススキーマを確立するため）、新しいオブジェクトを設定することはできません。
同期を保存して有効化します。