将 Klaviyo 数据加载到 BigQuery 中

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

如需了解 Klaviyo 转移的运作方式，请参阅 Klaviyo 转移简介。

准备工作

以下部分介绍了在创建 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. 在数据源详细信息部分，执行以下操作：

    • 对于私有 API 密钥，请输入您的私有 API 密钥。如需了解详情，请参阅 Klaviyo 前提条件。
    • 可选：对于开始日期，请指定要纳入数据转移的新记录的开始日期。数据传输中仅包含在此日期或之后创建的记录。默认值为迁移运行日期前 3 个月。
    • 在 Klaviyo objects to transfer（要转移的 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：（可选）要纳入数据转移的新记录的开始日期，格式为 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。
  • 如需了解如何使用转移作业，包括获取有关转移作业配置的信息、列出转移作业配置以及查看转移作业的运行历史记录，请参阅管理转移作业。