Caricare i dati di Stripe in BigQuery

Puoi caricare i dati da Stripe a BigQuery utilizzando il connettore Stripe con BigQuery Data Transfer Service. Utilizzando il connettore Stripe, puoi pianificare job di trasferimento ricorrenti che aggiungono i tuoi dati più recenti da Stripe a BigQuery.

Limitazioni

I trasferimenti di dati Stripe sono soggetti alle seguenti limitazioni:

  • Un trasferimento di dati Stripe carica le valute in base alle unità minori di Stripe. Per saperne di più, consulta Unità secondarie negli importi dell'API.
  • Il connettore Stripe trasferisce solo i report pregenerati per ogni account Stripe. Il connettore Stripe non genera nuovi report in base ai nuovi dati Stripe.
    • Per trasferire report aggiornati, generali manualmente nella dashboard di Stripe prima di iniziare il trasferimento dei dati di Stripe.
    • Per ulteriori informazioni, consulta la sezione Report di Stripe.
  • Il connettore Stripe non supporta gli eventi basati su webhook, gli aggiornamenti in tempo reale o Stripe Sigma.
  • I trasferimenti di dati Stripe dalle regioni Stripe in anteprima potrebbero riscontrare problemi con i trasferimenti di dati:
    • Le opzioni di filtro sono limitate o non disponibili nelle regioni di anteprima di Stripe.
    • I trasferimenti e le query di dati condizionali non sono supportati nelle regioni di anteprima di Stripe.
    • Potresti riscontrare tempi di esecuzione del trasferimento dei dati lunghi quando trasferisci dati dalle regioni di anteprima di Stripe.
  • Il connettore Stripe supporta alcuni oggetti con il filtro StartDate.
    • Il formato richiesto per il filtro StartDate è YYYY-MM-DD. Se non viene fornita una data di inizio, il connettore utilizza per impostazione predefinita tre anni prima della data corrente. Se viene fornita una data precedente al 1° gennaio 2011, il connettore utilizza automaticamente il 1° gennaio 2011.
    • Per un elenco degli oggetti supportati, consulta Oggetti con supporto del filtro StartDate.
  • Una singola configurazione di trasferimento può supportare una sola esecuzione di trasferimento dei dati in un determinato momento. Se è pianificato l'esecuzione di un secondo trasferimento dei dati prima del completamento del primo, solo il primo trasferimento dei dati viene completato, mentre gli altri trasferimenti dei dati che si sovrappongono al primo vengono ignorati.
    • Per evitare trasferimenti ignorati all'interno di una singola configurazione di trasferimento, ti consigliamo di aumentare la durata di tempo tra i trasferimenti di grandi quantità di dati configurando la Frequenza di ripetizione.

Prima di iniziare

Le sezioni seguenti descrivono i passaggi da seguire prima di creare un trasferimento di dati Stripe.

Prerequisiti di Stripe

  • Per autorizzare un trasferimento di dati Stripe, devi disporre di un account sviluppatore Stripe. Per registrare un account Stripe, vedi Registrazione di Stripe.
  • Configura l'applicazione della piattaforma Stripe seguendo questi passaggi:
    1. Vai alla sezione Sviluppatori nella dashboard Stripe.
    2. In Collega, configura la tua piattaforma in modo che supporti gli account Standard ed Express.
  • Per creare un trasferimento di dati Stripe sono necessarie le seguenti informazioni:
    • Prendi nota dell'ID account Stripe. Per ulteriori informazioni, vedi Creare un account.
    • Prendi nota della chiave segreta o della chiave con limitazioni. Per saperne di più, consulta Chiavi API.
  • Se prevedi di trasferire dati da account collegati, assicurati che la tua piattaforma sia configurata per Stripe Connect e abbia accesso alle funzionalità dell'account necessarie. Per ulteriori informazioni su Stripe Connect, consulta Piattaforme e marketplace con Stripe Connect.

Ruoli BigQuery richiesti

Per ottenere le autorizzazioni necessarie per creare un trasferimento, chiedi all'amministratore di concederti il ruolo IAM BigQuery Admin (roles/bigquery.admin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un trasferimento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare un trasferimento sono necessarie le seguenti autorizzazioni:

  • bigquery.transfers.update sull'utente
  • bigquery.datasets.get sul set di dati di destinazione
  • bigquery.datasets.update sul set di dati di destinazione

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Prerequisiti di BigQuery

Tipi di account Stripe

Il connettore Stripe supporta sia gli account della piattaforma Stripe sia gli account Stripe collegati. Per saperne di più, vedi Connettere i tipi di account.

Connettersi agli account delle piattaforme

Per eseguire un trasferimento di dati Stripe da un solo account della piattaforma, fai quanto segue quando configuri il trasferimento:

  • Inserisci l'ID account della piattaforma nel campo ID account.
  • Inserisci la chiave segreta o con limitazioni per l'account della piattaforma nel campo Chiave segreta/API.
  • Per SyncAllConnectedAccounts, seleziona False.

Per eseguire un trasferimento di dati Stripe per più account, ad esempio per un account della piattaforma collegato ad account connessi, procedi nel seguente modo quando configuri il trasferimento:

  • Inserisci l'ID account della piattaforma nel campo ID account.
  • Inserisci la chiave segreta o con limitazioni per l'account della piattaforma nel campo Chiave segreta/API.
  • Per SyncAllConnectedAccounts, seleziona True.

Connettersi agli account collegati

Gli account connessi sono account Stripe collegati a Stripe tramite Stripe Connect.

Per eseguire un trasferimento di dati Stripe da un account collegato, segui questi passaggi quando configuri il trasferimento:

  • Inserisci l'ID account della piattaforma per l'account collegato nel campo ID account.
  • Inserisci la chiave segreta o con limitazioni per l'account della piattaforma a cui è collegato l'account connesso nel campo Chiave segreta/API.
  • Per SyncAllConnectedAccounts, seleziona False.

Configura un trasferimento di dati Stripe

Aggiungi i dati di Stripe a BigQuery configurando una configurazione del trasferimento utilizzando una delle seguenti opzioni:

Console

  1. Vai alla pagina Trasferimenti di dati nella console Google Cloud .

    Vai a Trasferimenti dati

  2. Fai clic su Crea trasferimento.

  3. Nella sezione Tipo di origine, per Origine, seleziona Stripe.

  4. Nella sezione Dettagli origine dati, segui questi passaggi:

    • Nel campo ID piattaforma/account collegato, inserisci l'ID account Stripe. Per maggiori informazioni, consulta la sezione Prerequisiti di Stripe.
    • Per Stripe Secret Key, inserisci la chiave API per l'account Stripe. Per maggiori informazioni, consulta la sezione Prerequisiti di Stripe.
    • Per Data di inizio, inserisci una data nel formato YYYY-MM-DD. Il trasferimento dei dati carica i dati di Stripe a partire da questa data.
    • Seleziona Sincronizza tutti gli account collegati per sincronizzare tutti gli account collegati.
    • In Oggetti Stripe da trasferire, inserisci i nomi degli oggetti Stripe da trasferire oppure fai clic su Sfoglia e seleziona gli oggetti da trasferire.

  5. Nella sezione Impostazioni destinazione, per Set di dati, seleziona il set di dati che hai creato per archiviare i dati.

  6. Nella sezione Nome configurazione di trasferimento, per Nome visualizzato, inserisci un nome per il trasferimento di dati.

  7. Nella sezione Opzioni di pianificazione, segui questi passaggi:

    • Nell'elenco Frequenza di ripetizione, seleziona un'opzione per specificare la frequenza con cui viene eseguito questo trasferimento di dati. Per specificare una frequenza di ripetizione personalizzata, seleziona Personalizzata. Se selezioni On demand, questo trasferimento viene eseguito quando attivi manualmente il trasferimento.
    • Se applicabile, seleziona Inizia ora o Inizia all'ora impostata e fornisci una data di inizio e un'ora di esecuzione.

  8. (Facoltativo) Nella sezione Opzioni di notifica, segui questi passaggi:

    • Per attivare le notifiche via email, fai clic sul pulsante di attivazione/disattivazione Notifica email. Dopo aver attivato questa opzione, l'amministratore del trasferimento riceve una notifica via email quando l'esecuzione di un trasferimento non riesce.
    • Per attivare le notifiche di esecuzione del trasferimento Pub/Sub per questo trasferimento, fai clic sul pulsante di attivazione/disattivazione Notifiche Pub/Sub. Puoi selezionare il nome del tuo argomento oppure fare clic su Crea un argomento per crearne uno.

  9. Fai clic su Salva.

bq

Inserisci il comando bq mk e fornisci il flag di creazione del trasferimento --transfer_config:

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

Dove:

  • PROJECT_ID (facoltativo): il tuo ID progetto Google Cloud . Se non viene fornito --project_id per specificare un progetto particolare, viene utilizzato il progetto predefinito.
  • DATA_SOURCE: l'origine dati stripe.
  • DISPLAY_NAME: il nome visualizzato per la configurazione del trasferimento dei dati. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento se devi modificarlo in un secondo momento.
  • DATASET: il set di dati di destinazione per la configurazione del trasferimento.

  • PARAMETERS: i parametri per la configurazione del trasferimento creata in formato JSON. Ad esempio: --params='{"param":"param_value"}'. Di seguito sono riportati i parametri per un trasferimento di dati Stripe:

    • assets: un elenco di oggetti Stripe da includere in questo trasferimento.
    • connector.accountId: l'ID account Stripe.
    • connector.secretKey: la chiave API per l'account Stripe.
    • connector.syncAllConnectedAccounts: specifica true per sincronizzare tutti gli account collegati.
    • connector.startDate: inserisci una data nel formato YYYY-MM-DD. Il trasferimento dei dati carica i dati di Stripe a partire da questa data.

Ad esempio, il comando seguente crea un trasferimento di dati Stripe nel progetto predefinito con tutti i parametri richiesti:

  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

Utilizza il metodo projects.locations.transferConfigs.create e fornisci un'istanza della risorsa TransferConfig.

Quando salvi la configurazione del trasferimento, il connettore Stripe attiva automaticamente un'esecuzione del trasferimento in base all'opzione di pianificazione. A ogni esecuzione del trasferimento, il connettore Stripe trasferisce tutti i dati disponibili da Stripe a BigQuery.

Per eseguire manualmente un trasferimento di dati al di fuori della pianificazione regolare, puoi avviare un'esecuzione di backfill.

Mappatura dei tipi di dati

La seguente tabella mappa i tipi di dati Stripe ai tipi di dati BigQuery corrispondenti.

Tipo di dati Stripe Tipo di dati BigQuery Note
String STRING
Dictionary STRING Quando un oggetto nidificato viene caricato in BigQuery, viene convertito in un oggetto appiattito. Questo oggetto compresso viene quindi salvato come una singola stringa letterale all'interno della tabella.
Integer INT64
Double DOUBLE
Float FLOAT
Decimal BIGNUMERIC
BigInt (long) BIGNUMERIC
Boolean BOOL
Datetime TIMESTAMP
Unix timestamp TIMESTAMP

Oggetti con supporto del filtro StartDate

I seguenti oggetti Stripe supportano il filtro StartDate, che ti consente di caricare dati basati sul tempo:

  • Account
  • ApplicationFees
  • BalanceTransactions
  • Titolari delle carte
  • Addebiti
  • Coupon
  • Clienti
  • Contestazioni
  • EarlyFraudWarnings
  • Eventi
  • FileLinks
  • File
  • InvoiceItems
  • Fatture
  • IssuingCards
  • IssuingDisputes
  • PaymentIntent
  • Pagamenti
  • Piani
  • Prezzi
  • Prodotti
  • PromotionCodes
  • Rimborsi
  • Recensioni
  • ShippingRates
  • Abbonamenti
  • TaxRates
  • TopUps
  • Trasferimenti
  • ValueListItems
  • ValueLists

Risolvere i problemi di configurazione del trasferimento

Se riscontri problemi durante la configurazione del trasferimento dei dati, consulta Problemi con i trasferimenti di Stripe.

Prezzi

Il trasferimento dei dati di Stripe in BigQuery non prevede costi durante l'anteprima di questa funzionalità.

Passaggi successivi