Klaviyo データを BigQuery に読み込む

Klaviyo から BigQuery への定期的なデータ転送をスケジュールするには、転送構成を作成して、転送するデータ オブジェクトとデータ転送のスケジュールを設定する頻度を指定します。転送構成を作成するには、 Google Cloud コンソールまたは bq コマンドライン ツールを使用します。転送構成を設定すると、BigQuery Data Transfer Service は、指定されたスケジュールで最新のデータを BigQuery テーブルに転送します。

Klaviyo 転送の仕組みについては、Klaviyo データ転送の概要をご覧ください。

制限事項

  • ネットワーク アタッチメントが、データ転送の Google Cloud プロジェクトとは異なる Google Cloud プロジェクトで作成された場合は、データ転送が作成された Google Cloud プロジェクトに属するサービス エージェントに compute.networkAttachments.get 権限と compute.networkAttachments.update 権限を付与する必要があります。

増分転送の制限事項

Klaviyo の増分転送には、次の制限があります。

  • ウォーターマーク列として選択できるのは TIMESTAMP 列のみです。
  • 増分取り込みは、有効なウォーターマーク列があるアセットでのみサポートされます。
  • ウォーターマーク列の値は単調に増加する必要があります。
  • 増分転送では、ソーステーブルの削除オペレーションを同期できません。
  • 1 つの転送構成でサポートできるのは、増分取り込みまたは完全取り込みのいずれかのみです。
  • 最初の増分取り込みの実行後に、asset リスト内のオブジェクトを更新することはできません。
  • 最初の増分取り込みの実行後に、転送構成の書き込みモードを変更することはできません。
  • 最初の増分取り込みの実行後に、ウォーターマーク列または主キーを変更することはできません。
  • 宛先の BigQuery テーブルは、指定された主キーを使用してクラスタ化され、クラスタ化テーブルの制限が適用されます。
  • 既存の転送構成を初めて増分取り込みモードに更新すると、その更新後の最初のデータ転送で、データソースから利用可能なすべてのデータが転送されます。それ以降の増分データ転送では、データソースから新しい行と更新された行のみが転送されます。

始める前に

以降のセクションでは、Klaviyo のデータ転送を作成する前に必要な前提条件について説明します。

Klaviyo の前提条件

Klaviyo コネクタが BigQuery にデータを転送できるようにするには、読み取り専用の非公開 API キーが必要です。詳細については、秘密鍵を作成するをご覧ください。

BigQuery の前提条件

必要な BigQuery のロール

BigQuery Data Transfer Service データ転送の作成に必要な権限を取得するには、プロジェクトに対する BigQuery 管理者（roles/bigquery.admin）IAM ロールを付与するよう管理者に依頼します。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、BigQuery Data Transfer Service のデータ転送の作成に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

BigQuery Data Transfer Service のデータ転送を作成するには、次の権限が必要です。

  • BigQuery Data Transfer Service の権限
    • bigquery.transfers.update
    • bigquery.transfers.get
  • BigQuery の権限
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

詳細については、bigquery.admin のアクセス権を付与するをご覧ください。

Pub/Sub の転送実行通知を設定する場合は、pubsub.topics.setIamPolicy IAM 権限があることを確認してください。メール通知のみを設定する場合は、Pub/Sub の権限は必要ありません。詳細については、BigQuery Data Transfer Service の実行通知をご覧ください。

Klaviyo のデータ転送を設定する

次のいずれかのオプションを使用して転送構成を設定し、Klaviyo データを BigQuery に追加します。

コンソール

  1. Google Cloud コンソールの [データ転送] ページに移動します。

    [データ転送] に移動

  2. [転送を作成] をクリックします。

  3. [ソースタイプ] セクションで、[ソース] として [Klaviyo - プレビュー] を選択します。

  4. [データソースの詳細] セクションで、次のようにします。

    • [Private API Key] に、非公開 API キーを入力します。詳細については、Klaviyo の前提条件をご覧ください。
    • 省略可: [開始日] に、データ転送に含める新しいレコードの開始日を指定します。この日付以降に作成されたレコードのみがデータ転送に含まれます。デフォルト値は、転送実行日の 3 か月前です。
    • [転送する Klaviyo オブジェクト] で、[参照] をクリックして、BigQuery 宛先データセットに転送するオブジェクトを選択します。このフィールドには、データ転送に含めるオブジェクトを手動で入力することもできます。

  5. [転送先の設定] セクションの [データセット] で、データを保存するために作成したデータセットを選択します。

  6. [転送構成名] セクションの [表示名] に、データ転送の名前を入力します。

  7. [スケジュール オプション] セクションで:

    • [繰り返しの頻度] リストで、この転送の実行頻度を指定するオプションを選択します。カスタムの繰り返しの頻度を指定するには、[カスタム] を選択します。[オンデマンド] を選択した場合、手動で転送をトリガーすると、この転送が実行されます。
    • 必要に応じて、[すぐに開始] を選択するか、[設定した時刻に開始] を選択して開始日と実行時間を指定します。

  8. 省略可: [通知オプション] セクションで、次のようにします。

    • メール通知を有効にするには、[メール通知] をクリックします。このオプションを有効にした場合、転送の実行が失敗すると転送管理者にメール通知が送信されます。
    • この転送の Pub/Sub 転送実行通知を有効にするには、[Pub/Sub 通知] をクリックします。トピック名を選択するか、[トピックを作成] をクリックしてトピックを作成します。

  9. [保存] をクリックします。

bq

bq mk コマンドを入力して、転送作成フラグ --transfer_config を指定します。

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

次のように置き換えます。

  • PROJECT_ID（省略可）: Google Cloud プロジェクト ID。--project_id で特定のプロジェクトを指定しない場合は、デフォルトのプロジェクトが使用されます。
  • DATA_SOURCE: データソース - klaviyo。
  • NAME: データ転送構成の表示名。転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
  • DATASET: 転送構成のターゲット データセット。

  • PARAMETERS: 作成される転送構成のパラメータを JSON 形式で指定します。例: --params='{"param":"param_value"}'。Klaviyo データ転送のパラメータは次のとおりです。

    • assets: BigQuery に転送する Klaviyo オブジェクトのパス。
    • connector.authentication.privateApiKey: Klaviyo アカウントの非公開 API キー。
    • connector.startDate: （省略可）Data Transfer に含める新しいレコードの開始日（YYYY-MM-DD 形式）。この日付以降に作成されたレコードのみがデータ転送に含まれます。デフォルト値は、転送実行日の 3 か月前です。
    • ingestionType: （省略可）データ読み込み方法を指定します。使用できる値は、full（宛先テーブルのすべてのデータを置き換える）または incremental（最後の転送以降の新しいデータまたは変更されたデータのみを読み込む）です。
    • writeMode: （省略可）ingestionType が incremental に設定されている場合、宛先テーブルへのデータの書き込み方法を指定します。使用できる値は、WRITE_MODE_APPEND（新しいレコードを追加）または WRITE_MODE_UPSERT（既存のレコードを更新して新しいレコードを挿入）です。

次のコマンドは、デフォルト プロジェクトに Klaviyo データ転送を作成します。

    bq mk
        --transfer_config
        --target_dataset=mydataset
        --data_source=klaviyo
        --display_name='My Transfer'
        --params= ' {
            "assets": [ "Events" , "Flows"] ,
            "connector.authentication.privateApiKey" : "pk_123456789123",
            "connector.startDate": "2025-10-20"
            }'
転送構成を保存すると、Klaviyo コネクタはスケジュール オプションに従って転送実行を自動的にトリガーします。転送が実行されるたびに、Klaviyo コネクタは Klaviyo から BigQuery に利用可能なすべてのデータを転送します。

定期的なスケジュール外でデータ転送を手動で実行するには、バックフィル実行を開始します。

Klaviyo データ移転に含まれるデータのリストについては、Klaviyo データモデル リファレンスをご覧ください。

転送の設定に関するトラブルシューティング

データ転送の設定で問題が発生した場合は、Klaviyo の転送に関する問題をご覧ください。

次のステップ

  • BigQuery Data Transfer Service の概要については、BigQuery Data Transfer Service とはをご覧ください。
  • 転送構成に関する情報の取得、転送構成の一覧表示、転送の実行履歴の表示など、転送の使用方法については、転送の管理をご覧ください。