将 Klaviyo 数据加载到 BigQuery 中

如需安排从 Klaviyo 到 BigQuery 的周期性数据传输，请创建转移作业配置，以指定要传输的数据对象以及安排数据传输的频率。您可以使用 控制台 Google Cloud 或 bq 命令行工具创建转移作业配置。设置转移作业配置后， BigQuery Data Transfer Service 会按照指定的时间表将最新 数据转移到 BigQuery 表中。

如需了解 Klaviyo 转移作业的工作原理，请参阅 Klaviyo 数据转移作业简介。

限制

增量 Klaviyo 转移作业受到以下限制：

  • 您只能选择 TIMESTAMP 列作为水位线列。
  • 仅当资产具有有效的水位线列时，才支持增量提取。
  • 水位线列中的值必须单调递增。
  • 增量转移无法同步源表中的删除操作。
  • 单个转移作业配置只能支持增量提取或完整提取。
  • 在首次增量提取运行后，您无法更新 asset 列表中的对象。
  • 在首次增量提取运行后，您无法更改转移作业配置中的写入模式。
  • 在首次增量提取运行后，您无法更改水位线列或主键。
  • 目标 BigQuery 表使用提供的 主键进行聚簇，并受 聚簇表限制的约束。
  • 首次将现有转移作业配置更新为增量提取模式时，更新后的首次数据传输会转移数据源中的所有可用数据。任何后续增量数据传输作业都只会传输数据源中的新行和更新后的行。

准备工作

以下部分介绍了在创建 Klaviyo 数据传输作业之前需要完成的前提条件。

Klaviyo 前提条件

您必须拥有只读私有 API 密钥，才能允许 Klaviyo 连接器将数据转移到 BigQuery。如需了解详情，请参阅 创建私钥。

BigQuery 前提条件

所需 BigQuery 角色

如需获得创建 BigQuery Data Transfer Service 数据传输所需的权限，请让您的管理员为您授予项目的BigQuery Admin (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 密钥），输入您的私有 API 密钥。如需了解详情，请参阅 Klaviyo 前提条件。
    • 可选：对于 Start Date（开始日期），指定一个开始日期，以便将新记录纳入数据传输作业。只有在此日期或之后创建的记录才会纳入数据传输作业。默认值为转移作业运行日期之前的 3 个月。
    • 对于 Klaviyo objects to transfer（要转移的 Klaviyo 对象），点击 Browse 以选择要转移到 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：（可选）一个开始日期，以便将新记录纳入数据传输作业，格式为 YYYY-MM-DD。只有在此日期或之后创建的记录才会纳入数据传输作业。默认值为转移作业运行日期之前的 3 个月。

以下命令会在默认项目中创建 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。
  • 如需了解如何使用转移作业，包括获取有关 转移作业配置的信息、列出转移作业配置以及查看 转移作业的运行历史记录，请参阅管理转移作业。