將 Stripe 資料載入 BigQuery

您可以使用 BigQuery 資料移轉服務的 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，請參閱「Platforms and marketplaces with Stripe Connect」。

須具備的 BigQuery 角色

如要取得建立移轉作業所需的權限，請要求管理員授予您專案的 BigQuery 管理員 (roles/bigquery.admin) 身分與存取權管理角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備建立轉移作業所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要建立移轉作業，必須具備下列權限：

  • bigquery.transfers.update 使用者
  • bigquery.datasets.get 目標資料集
  • bigquery.datasets.update 目標資料集

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

BigQuery 必要條件

Stripe 帳戶類型

Stripe 連接器支援 Stripe 平台帳戶和 Stripe 已連結帳戶。詳情請參閱「連結帳戶類型」。

連結平台帳戶

如要只從一個平台帳戶執行 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 Key」(密鑰/API 金鑰) 欄位中，輸入連結帳戶所連線平台帳戶的密鑰或受限金鑰。
  • 在「SyncAllConnectedAccounts」部分，選取「False」。

設定 Stripe 資料移轉

如要將 Stripe 資料新增至 BigQuery，請使用下列任一方法設定移轉作業：

主控台

  1. 前往 Google Cloud 控制台的「資料移轉」頁面。

    前往「資料移轉」

  2. 按一下 「建立轉移作業」。

  3. 在「Source type」(來源類型) 部分，「Source」(來源) 請選取「Stripe」。

  4. 在「Data source details」(資料來源詳細資料) 部分執行下列操作：

    • 在「Platform/Connected Account ID」(平台/已連結帳戶 ID) 專區中輸入 Stripe 帳戶 ID。詳情請參閱「Stripe 先決條件」。
    • 在「Stripe Secret Key」(Stripe 私密金鑰) 部分，輸入 Stripe 帳戶的 API 金鑰。詳情請參閱「Stripe 先決條件」。
    • 在「開始日期」中，以 YYYY-MM-DD 格式輸入日期。資料轉移作業會從這個日期開始載入 Stripe 資料。
    • 選取「同步處理所有連結的帳戶」，即可同步處理所有連結的帳戶。
    • 在「Stripe objects to transfer」(要移轉的 Stripe 物件)，輸入要移轉的 Stripe 物件名稱，或是點選「Browse」(瀏覽) 並選取要移轉的物件。

  5. 在「Destination settings」(目的地設定) 部分，「Dataset」(資料集) 請選取您為了儲存資料而建立的資料集。

  6. 在「Transfer config name」(轉移設定名稱) 部分，「Display name」(顯示名稱) 請輸入資料移轉作業的名稱。

  7. 在「Schedule options」(排程選項) 部分執行下列操作：

    • 在「Repeat frequency」(重複頻率) 清單選取選項，指定這項資料移轉作業的執行頻率。如要指定自訂重複頻率，請選取「Custom」(自訂)。如果選取「On-demand」(隨選)，這項移轉作業會在您手動觸發後執行。
    • 視情況選取「Start now」(立即開始) 或「Start at set time」(在所設時間開始執行)，並提供開始日期和執行時間。

  8. 選用：在「Notification options」(通知選項) 專區，執行下列操作：

    • 如要啟用電子郵件通知，請點選「Email notification」(電子郵件通知) 切換按鈕。啟用這個選項之後，若移轉失敗，移轉作業管理員就會收到電子郵件通知。
    • 如要針對這項移轉作業啟用 Pub/Sub 移轉作業執行通知，請點選「Pub/Sub notifications」(Pub/Sub 通知) 切換按鈕。您可以選取主題名稱，或點選「Create a topic」(建立主題) 來建立主題。

  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 不會產生費用。

後續步驟