# Klaviyo インポートインテグレーション Klaviyoは、eコマースビジネス向けのメールマーケティング自動化に特化したデジタルマーケティングプラットフォームです。Klaviyoは、eコマース向けのSMSおよびメールマーケティング自動化プラットフォームを提供しており、無料アカウントでは250件の連絡先と500通のメール送信が可能です。 このTDインポートを使用すると、KlaviyoアカウントからTreasure Dataにデータを転送できます。 # 前提条件 - [TD Toolbelt](https://api-docs.treasuredata.com/en/tools/cli/quickstart/)を含む、Treasure Dataの基本知識 - Klaviyoのアカウント - Klaviyoアカウントのプライベート APIキー # 要件と制限事項 - CLIからのインポートには、[Ruby Gem for TD Toolbelt](https://toolbelt.treasuredata.com/)が必要です。 # Treasure Dataの静的IPアドレス Treasure Dataの静的IPアドレスは、このインテグレーションのアクセスポイントおよび連携元です。静的IPアドレスを確認するには、カスタマーサクセス担当者またはテクニカルサポートにお問い合わせください。 # Klaviyo APIキーの取得 Klaviyoからインポートするには、Klaviyoアカウントに関連付けられたAPIキーが必要です。 1. Klaviyoの認証情報を使用して、[https://www.klaviyo.com/login](https://www.klaviyo.com/login)にログインします。 2. **Settings**を選択します。 ![](/assets/image2023-6-12_18-30-4.57f860dc7f8057c048c45b73004a2cc36bd1517674fb152a77169576471f5225.b6b69b1e.png) 1. **Account**タブを選択し、次に**Create Private API Key**を選択します。 ![](/assets/image2023-6-12_18-31-3.3e613b401bb3ac44d5533d73869fd10d619d6d0f4aeab67cd1684a31aec48548.b6b69b1e.png) 1. APIキー名を入力し、APIキーのアクセススコープを選択します。 ![](/assets/image2023-6-12_18-32-1.e86549d1e6a53d34b693bf10ac4699f5c68f742b39a11e70d2c314f4d4aea5a9.b6b69b1e.png) 1. **Create**を選択します。 # TD Console経由でKlaviyoからインポート ## 認証の作成 最初のステップは、認証情報セットを使用して新しい認証を作成することです。 1. Integrations **Hub > Catalog**を選択します。 ![](/assets/image2021-9-30_14-38-2.ca92fa4ab9277dca95973c6bd413fc662a3f0d04b57d58f7a8c952a29f28bbec.b6b69b1e.png) 1. カタログで*Klaviyo*を検索し、アイコンにマウスを合わせて**Create Authentication**を選択します。 ![](/assets/klaviyo.1105232bfb36480b7642357cd425b0ddf75dc5a703b0f6387fb73a72df6469cc.b6b69b1e.png) 1. **Credentials**タブが選択されていることを確認し、KlaviyoのプライベートAPIキーを入力します。 2. **Continue**を選択します。 3. 認証の名前を入力し、**Done**を選択します。 ## ソースの作成 1. TD Consoleを開きます。 2. **Integrations Hub** > **Authentications**に移動します。 3. Klaviyo認証を見つけて、**New Source**を選択します。 ![](/assets/klaviyo_auth2.0792185b50e82d1d4e7cc74aa4ac58c63627f5911d96671553a0535207a3e2f0.b6b69b1e.png) ## 接続の作成 | Parameter | Description | | --- | --- | | Data Transfer Name | 転送の名前を定義できます。 | | Authentication | 転送に使用される認証名。 | 1. Data Transfer Nameフィールドにソース名を入力します。 2. **Next**を選択します。 **Source Table**タブが選択された状態で、ソースの作成ページが表示されます。 ## ソーステーブルの識別 ![](/assets/screen-shot-2024-08-26-at-08.55.37.1efa9f1b54a1755d1e553930cbb6f61b51072d3e4f4cb502d75cdfd0a1657740.b6b69b1e.png) 次の表は、ソーステーブルを構成するためのパラメータについて説明しています: | Parameter | Mandatory | Description | | --- | --- | --- | | Data Source | Yes | 取り込む必要のあるデータを指定します。サポートされる値:1. Metric Data: アカウント内のすべてのメトリクスを取得します。 2. Events: アカウント内のすべてのイベントを取得します 3. Event Metrics: 指定されたイベントIDのイベントのメトリクスを取得します。 4. Event Profiles: 指定されたイベントIDのイベントに関連付けられたプロファイルを取得します。 5. Email Templates: アカウント内のすべてのテンプレートを取得します。 6. Campaigns: 一部またはすべてのキャンペーンを取得します 7. Lists: アカウント内のすべてのリストを取得します。 8. Profiles in List: 指定されたリストID内のすべてのプロファイルを取得します。 9. Profiles: アカウント内のすべてのプロファイルを取得します。 | | Revision | No | APIエンドポイントのリビジョン（形式: **YYYY-MM-DD**）。詳細については、**Appendix A**セクションを参照してください。推奨される安定したリビジョン値:- `2022-10-17` - `2023-01-24` - `2023-02-22` | | Skip Related Object | No | このチェックボックスは、Data Sourceが**Events**の場合にのみ表示されます。メトリクスおよびプロファイルオブジェクトの詳細の取得をスキップするには、ユーザーは個別の構成でそれらを取得し、後でそれらのテーブルを結合できます。 | | Incremental | No | このチェックボックスは、Data Sourceが次のいずれかの値の場合にのみ表示されます: - Events - Email Templates - Campaigns - Lists - Profiles チェックボックスを選択すると、カスタムの開始時刻-終了時刻を使用した増分データ読み込みが有効になります。 | | Filter By | No | 開始時刻と終了時刻を使用した時間ベースのフィルタで使用されるオブジェクト属性を選択します: - Updated - Created このオプションの利用可能性は、データソースによって異なります。 | | Start Time - End Time | No | この期間のKlaviyoからデータをリクエストします。形式: ISO 8601形式（yyyy-MM-dd'T'HH:mm:ss） | **Revision**: 空白のままにすると、インテグレーションによって管理されるデフォルトバージョンが使用されます。 **Skip Related Object**: パフォーマンスを向上させるには、これを有効にします。 **Incremental**: 増分モードを実行する場合、開始時刻および/または終了時刻が欠落している場合、コネクタは前回の実行の終了時刻を新しい開始時刻として使用し、現在のシステム時刻を終了時刻として使用します。 1. **Next**を選択します。 ## データ設定の定義 ![](/assets/image2023-6-13_8-17-11.7a44df17211ec9a4fab7d4b41113675ae3a0ab83a07c2fdc7a54e1fdbe4c1c3f.b6b69b1e.png) | Parameter | Type | Mandatory | Default Value | Description | | --- | --- | --- | --- | --- | | Retry Limit | Number | No | 5 | API呼び出しごとの最大リトライ回数。 **最小: 1、最大: 7** | | Initial retry time wait | Number | No | 1 | API呼び出しごとの初期リトライ間隔（秒）。 **最小: 1、最大: 10** | | Max retry wait | Number | No | 300 | API呼び出しごとの最大リトライ間隔（秒）。 **最小: 30、最大: 1800** | | HTTP Connection Timeout | Number | No | 300 | HTTP接続タイムアウト（秒）。 **最小: 30、最大: 1800** | | HTTP read timeout | Number | No | 300 | HTTP読み取りタイムアウト（秒）。 **最小: 30、最大: 1800** | | HTTP write timeout | Number | No | 300 | HTTP書き込みタイムアウト（秒）。 **最小: 30、最大: 1800** | 1. **Next**を選択します。 ## データのプレビュー ![](/assets/image2023-6-13_9-20-21.590453ebed8fdf7f3f999bb67a48cac967b7c371c6fe2572ef0d7440daf5937d.b6b69b1e.png) データプレビューに表示されるデータは、ソースから概算されたものです。実際にインポートされるデータではありません。 1. データをプレビューするには、**Generate Preview** を選択します。オプションで、**Next** を選択して次のセクションにスキップできます。 2. データが期待どおりに表示されていることを確認します。 3. **Next** を選択します。 ## データの配置を定義する ![](/assets/klaviyo_dataplacement3.80f2f206b8f5a2f8b9273dc53f5c6c9280d84084e73dfc57b69f1bbd2be2b8c6.b6b69b1e.png) Storage セクションで、Treasure Data 内でデータを保存する場所の詳細を指定します: - Database — データを保存するデータベースを選択します。 - Table — インポートしたデータを保存する宛先テーブル - Method - Append — 既存のテーブルにレコードを追加します。（データが重複する可能性があることに注意してください。） - Always Replace — レコードを追加する前に、常に宛先テーブルをクリアします。 - Replace on new data — 新しいデータが見つかった場合、古いデータは新しいデータで上書きされます。 - Timestamp-based Partition Key **—** パーティションキーとして使用するカスタムタイムスタンプカラムを選択します。 - Data Storage Timezone — データベースに想定されるタイムゾーン。 **Schedule** セクションでは、このクエリを実行するタイミングと頻度を選択できます。 - Repeat — **On** または **Off** を選択します。 - Schedule **—** ドロップダウンリストには次のオプションがあります: *@daily (midnight)*、*@hourly,(:00)*、または *Custom cron*。 - Delay Transfer **—** 実行時間に遅延を指定できます。 - Scheduling Timezone **Create & Run Now** を選択します。 転送が実行された後、**Data Workbench** > **Databases** で転送の結果を確認できます。 # CLI（Toolbelt）を使用したKlaviyoからのインポート TD Toolbeltを使用してKlaviyoからデータをインポートします。 ## 前提条件 Ruby Gemを使用して最新の `TD Tool` をインストールします。 ``` $ gem install td $ td --version 0.16.10 ``` 他のインストール方法もあります。詳細については、[Treasure Data Toolbelt](https://toolbelt.treasuredata.com/) を参照してください。 ## 設定ファイルの作成 config.yml 設定ファイルを作成します: ``` in: type: klaviyo data_source: lists api_token: xxx revision_time: "2022-12-17" incremental: true start_time: "2023-06-01T17:06:39.698883" incremental_field: updated out: mode: append ``` ## 設定ファイルから取り込まれるデータのプレビュー 設定ファイルが取り込むデータをプレビューできます: ``` $ td connector:preview config.yml +-----------+-----------------------+-------------------------+-------------------------+ | id:string | name:string | created:string | updated:string | +-----------+-----------------------+-------------------------+-------------------------+ | SPg3aL | chrome_line_name | 2021-08-30 05:35:46 UTC | 2021-08-30 05:35:46 UTC | | QPg3zL | 100_w_phone_line_name | 2021-08-27 23:49:56 UTC | 2021-08-27 23:49:56 UTC | +-----------+-----------------------+-------------------------+-------------------------+ ``` ## スケジュール実行 定期的なKlaviyoインポートのために、定期的なデータコネクタ実行をスケジュールできます。この機能を使用することで、ローカルデータセンターで `cron` デーモンを使用する必要がなくなります。 ### スケジュールの作成 新しいスケジュールは `td connector:create` コマンドを使用して作成できます。次のデータを指定する必要があります: - スケジュールの名前 - cron形式のスケジュール - データが保存されるデータベースとテーブル - データコネクタ設定ファイルが必要です。 ``` $ td connector:create \ daily_klaviyo_import \ "10 0 * * *" \ sample_db \ sample_table \ config.yml ``` cronパラメータは、`@hourly`、`@daily`、`@monthly` の3つの特別なオプションも受け入れます。詳細については、[Scheduled Jobs](https://docs.treasuredata.com/smart/project-product-documentation/scheduling-jobs-using-td-console) を参照してください。 デフォルトでは、スケジュールは UTC タイムゾーンで設定されます。`-t` または `--timezone` オプションを使用して、タイムゾーンでスケジュールを設定できます。`--timezone` オプションは、'Asia/Tokyo'、'America/Los_Angeles' などの拡張タイムゾーン形式のみをサポートします。PST や CST などのタイムゾーンの略語はサポートされて*いません*。予期しないスケジュールになる可能性があります。 ### スケジュールの一覧表示 `td connector:list` を入力すると、現在スケジュールされているエントリのリストを確認できます。 ``` $ td connector:list +----------------------+------------+----------+-------+-----------------+--------------+ | Name | Cron | Timezone | Delay | Database | Table | +----------------------+------------+----------+-------+-----------------+--------------+ | daily_klaviyo_import | 10 0 * * * | UTC | 0 | sample_database | sample_table | +----------------------+------------+----------+-------+-----------------+--------------+ ``` ### スケジュールの設定と履歴の表示 `td connector:show` は、スケジュールエントリの実行設定を表示します。 ``` $ td connector:show daily_klaviyo_import Name : daily_klaviyo_import Cron : 10 0 * * * Timezone : UTC Delay : 0 Database : sample_db Table : sample_table ``` `td connector:history` は、スケジュールエントリの実行履歴を表示します。個々の実行結果を調査するには、`td job:show jobid` を使用します。 ``` | 577914 | success | 20000 | sample_db | sample_table | 0 | 2015-04-16 00:10:03 +0000 | 152 | | 577872 | success | 20000 | sample_db | sample_table | 0 | 2015-04-15 00:10:04 +0000 | 163 | | 577810 | success | 20000 | sample_db | sample_table | 0 | 2015-04-14 00:10:04 +0000 | 164 | | 577766 | success | 20000 | sample_db | sample_table | 0 | 2015-04-13 00:10:04 +0000 | 155 | | 577710 | success | 20000 | sample_db | sample_table | 0 | 2015-04-12 00:10:05 +0000 | 156 | | 577610 | success | 20000 | sample_db | sample_table | 0 | 2015-04-11 00:10:04 +0000 | 157 | +--------+---------+---------+-----------+--------------+----------+---------------------------+----------+ ``` ### スケジュールの削除 `td connector:delete` は、スケジュールを削除します。 ``` $ td connector:delete daily_klaviyo_import ``` # 付録 A: Klaviyo APIのバージョニング Treasure Data Klaviyoコネクタは、"Stable" Klaviyo APIのみをサポートします。"v1-2" レガシーAPIや非推奨のAPIはサポートしていません。"v1-2" レガシーAPIは、2024年1月1日に終了する予定です。 ![](/assets/image2023-6-13_19-55-53.0b3a4330b9fcfa6c300b8c801e54b2129f0086d50e82d1f69577e8d027ede2fe.b6b69b1e.png) Klaviyo APIは、後方互換性のない変更を含む正確なAPIリリースをより明示的に指定できるバージョニングシステムに従っています: - 新しいKlaviyo API（/apiエンドポイント）のパスにはバージョン番号が含まれていません。 - バージョンは現在、YYYY-MM-DDのパターンでフォーマットされます。例えば、リビジョン2022-04-15です。Klaviyoコネクタでは、TD ConsoleまたはTD Toolbeltを使用して新しいソースを作成する際に、リビジョンは必須パラメータです。 - Klaviyoは次のリビジョンの使用を推奨しています | Revision | Deprecated? | Planned retirement date | Retired? | | --- | --- | --- | --- | | **`2022-10-17`** | Yes | ~January 24th, 2024 | No | | **`2023-01-24`** | Yes | ~February 23rd, 2024 | No | | **`2023-02-22`** | No | TBD | No | ## References: - API versioning and deprecation policy: [https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy](https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy) - API Overview: [https://developers.klaviyo.com/en/reference/api_overview](https://developers.klaviyo.com/en/reference/api_overview)