将 Stripe 数据加载到 BigQuery 中

您可以使用 BigQuery Data Transfer Service 的 Stripe 连接器将数据从 Stripe 加载到 BigQuery。借助 Stripe 连接器，您可以安排周期性转移作业，以将 Stripe 中的最新数据添加到 BigQuery。

限制

Stripe 数据转移作业受到以下限制：

  • Stripe 数据转移会根据 Stripe 的最小单位加载币种。如需了解详情，请参阅 API 金额中的最小单位。
  • Stripe 连接器仅会转移每个 Stripe 账号的预生成报告。Stripe 连接器不会根据新的 Stripe 数据生成新报告。
    • 如需转移最新报告，请在开始 Stripe 数据转移之前，在 Stripe 管理平台中手动生成报告。
    • 如需了解详情，请参阅 Stripe 报告。
  • Stripe 连接器不支持基于 Webhook 的事件、实时更新或 Stripe Sigma。
  • 从处于预览阶段的 Stripe 区域进行 Stripe 数据转移时，可能会遇到数据转移问题：
    • 在 Stripe 预览区域，过滤选项会受到限制或无法使用。
    • Stripe 预览区域不支持有条件的数据转移和查询。
    • 从 Stripe 预览版区域转移数据时，您可能会遇到数据转移运行时间过长的问题。
  • Stripe 连接器支持使用 StartDate 过滤器的部分对象。
    • StartDate 过滤条件的必需格式为 YYYY-MM-DD。如果未提供开始日期，连接器会默认使用当前日期前三年。如果提供的日期早于 2011 年 1 月 1 日，连接器会自动使用 2011 年 1 月 1 日。
    • 如需查看支持的对象列表，请参阅支持 StartDate 过滤条件的对象。
  • 单个转移配置在给定时间只能支持一次数据转移运行。如果第二次数据转移的预定运行时间在第一次转移完成之前，则只有第一次数据转移会完成，而与第一次转移时间重叠的任何其他数据转移都会被跳过。
    • 为避免在单个转移配置中跳过转移，建议您通过配置重复频率来增加大型数据转移之间的时长。

准备工作

以下部分介绍了在创建 Stripe 数据转移作业之前需要执行的步骤。

Stripe 前提条件

  • 您必须拥有 Stripe 开发者账号才能授权 Stripe 数据转移。如需注册 Stripe 账号，请参阅 Stripe 注册。
  • 按照以下步骤配置 Stripe 平台应用：
    1. 前往 Stripe 信息中心中的开发者部分。
    2. 在关联下，配置您的平台以支持标准和快速账号。
  • 如需创建 Stripe 数据转移作业，您需要提供以下信息：
    • 记下您的 Stripe 账号 ID。如需了解详情，请参阅创建账号。
    • 记下您的密钥或受限密钥。如需了解详情，请参阅 API 密钥。
  • 如果您打算从关联的账号转移数据，请确保您的平台已针对 Stripe Connect 进行配置，并且有权使用必要的账号功能。如需详细了解 Stripe Connect，请参阅使用 Stripe Connect 的平台和市场。

所需 BigQuery 角色

如需获得创建转移作业所需的权限，请让管理员为您授予项目的 BigQuery Admin (roles/bigquery.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供创建转移作业所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

创建转移作业需要以下权限：

  • 针对用户的 bigquery.transfers.update 权限
  • 针对目标数据集的 bigquery.datasets.get 权限
  • 针对目标数据集的 bigquery.datasets.update 权限

您也可以使用自定义角色或其他预定义角色来获取这些权限。

BigQuery 前提条件

Stripe 账号类型

Stripe 连接器同时支持 Stripe 平台账号和 Stripe 关联账号。如需了解详情，请参阅 Connect 账号类型。

关联平台账号

如需仅从一个平台账号运行 Stripe 数据转移作业，请在设置转移配置时执行以下操作：

  • 在账号 ID 字段中，输入平台账号的平台账号 ID。
  • 在 Secret/API Key（密文/API 密钥）字段中，输入平台账号的密文或受限密钥。
  • 对于 SyncAllConnectedAccounts，选择 False。

如需为多个账号（例如与关联账号相关联的平台账号）运行 Stripe 数据转移，请在设置转移配置时执行以下操作：

  • 在账号 ID 字段中，输入平台账号的平台账号 ID。
  • 在 Secret/API Key（密文/API 密钥）字段中，输入平台账号的密文或受限密钥。
  • 对于 SyncAllConnectedAccounts，选择 True。

关联到关联的账号

关联的账号是指使用 Stripe Connect 与 Stripe 关联的 Stripe 账号。

如需从关联的账号运行 Stripe 数据转移，请在设置转移配置时执行以下操作：

  • 在账号 ID 字段中，输入关联账号的平台账号 ID。
  • 在 Secret/API 密钥字段中，输入关联账号所关联的平台账号的 Secret 或受限密钥。
  • 对于 SyncAllConnectedAccounts，选择 False。

设置 Stripe 数据转移作业

通过使用以下选项之一设置转移配置，将 Stripe 数据添加到 BigQuery 中：

控制台

  1. 前往 Google Cloud 控制台中的“数据转移”页面。

    转到“数据传输”

  2. 点击 创建转移作业。

  3. 在来源类型部分的来源中，选择 Stripe。

  4. 在数据源详细信息部分，执行以下操作：

    • 对于平台/关联的账号 ID，请输入 Stripe 账号 ID。如需了解详情，请参阅 Stripe 前提条件。
    • 对于 Stripe 密钥，请输入 Stripe 账号的 API 密钥。如需了解详情，请参阅 Stripe 前提条件。
    • 对于开始日期，请输入格式为 YYYY-MM-DD 的日期。数据转移会加载从该日期开始的 Stripe 数据。
    • 选择同步所有关联账号，以同步所有关联账号。
    • 在 Stripe objects to transfer（要转移的 Stripe 对象）部分，输入要转移的 Stripe 对象的名称，或点击浏览并选择要转移的对象。

  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=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

其中：

  • PROJECT_ID（可选）：您的 Google Cloud 项目 ID。如果未提供 --project_id 来指定具体项目，则系统会使用默认项目。
  • DATA_SOURCE：数据源，stripe。
  • DISPLAY_NAME：数据转移作业配置的显示名称。转移作业名称可以是任何可让您在需要修改转移作业时识别该转移作业的名称。
  • DATASET：转移作业配置的目标数据集。

  • PARAMETERS：所创建转移作业配置的参数（采用 JSON 格式）。例如 --params='{"param":"param_value"}'。以下是 Stripe 数据转移作业的参数：

    • assets：要包含在此转移中的 Stripe 对象列表。
    • connector.accountId：Stripe 账号 ID。
    • connector.secretKey：Stripe 账号的 API 密钥。
    • connector.syncAllConnectedAccounts：指定 true 以同步所有关联的账号。
    • connector.startDate：输入日期，格式为 YYYY-MM-DD。数据转移会加载从该日期开始的 Stripe 数据。

例如，以下命令会使用所有必需参数在默认项目中创建 Stripe 数据转移作业：

  bq mk \
      --transfer_config \
      --target_dataset=mydataset \
      --data_source=stripe \
      --display_name='My Transfer' \
      --params= ' {
  "assets" : [ "Customers" , "Accounts", "BalanceSummaryReport"] ,
  "connector.accountId" : "acct_000000000000",
  "connector.secretKey" : "sk_test_000000000",
  "connector.syncAllConnectedAccounts" : "true",
  "connector.startDate": "2025-05-20"
  }'

API

使用 projects.locations.transferConfigs.create 方法并提供 TransferConfig 资源实例。

保存转移配置后，Stripe 连接器会根据您的安排选项自动触发转移运行。在每次转移运行时，Stripe 连接器都会将 Stripe 中的所有可用数据转移到 BigQuery。

如需在常规安排之外手动运行数据转移，您可以启动回填运行。

数据类型映射

下表将 Stripe 数据类型映射到相应的 BigQuery 数据类型。

Stripe 数据类型 BigQuery 数据类型 备注
String STRING
Dictionary STRING 当嵌套对象加载到 BigQuery 中时，系统会将其转换为扁平化对象。然后，此扁平化对象会作为单个字面量字符串保存在表格中。
Integer INT64
Double DOUBLE
Float FLOAT
Decimal BIGNUMERIC
BigInt (long) BIGNUMERIC
Boolean BOOL
Datetime TIMESTAMP
Unix timestamp TIMESTAMP

支持 StartDate 过滤条件的对象

以下 Stripe 对象支持 StartDate 过滤条件，可用于加载基于时间的数据：

  • 账号
  • ApplicationFees
  • BalanceTransactions
  • 持卡人
  • 收费
  • 优惠券
  • 客户
  • 争议
  • EarlyFraudWarnings
  • 事件
  • FileLinks
  • 文件
  • InvoiceItems
  • 账单
  • IssuingCards
  • IssuingDisputes
  • PaymentIntent
  • 支付情况
  • 方案
  • 价格
  • 产品
  • PromotionCodes
  • 退款
  • 评价
  • ShippingRates
  • 订阅
  • TaxRates
  • TopUps
  • 传输
  • ValueListItems
  • ValueLists

排查转移作业设置问题

如果您在设置数据转移作业时遇到问题，请参阅 Stripe 转移问题。

价格

将 Stripe 数据转移到 BigQuery 的功能处于预览版阶段时，您无需付费即可使用此功能。

后续步骤