Carregar dados do Stripe no BigQuery

É possível carregar dados da Stripe para o BigQuery usando o conector da Stripe com o serviço de transferência de dados do BigQuery. Com o conector da Stripe, é possível programar jobs de transferência recorrentes que adicionam seus dados mais recentes da Stripe ao BigQuery.

Limitações

As transferências de dados do Stripe estão sujeitas às seguintes limitações:

  • Uma transferência de dados da Stripe carrega moedas de acordo com as unidades menores da Stripe. Para mais informações, consulte Unidades secundárias em valores da API.
  • O conector da Stripe transfere apenas relatórios pré-gerados para cada conta da Stripe. O conector da Stripe não gera novos relatórios com base em novos dados da Stripe.
    • Para transferir relatórios atualizados, gere-os manualmente no painel da Stripe antes de iniciar a transferência de dados.
    • Para mais informações, consulte Relatórios da Stripe.
  • O conector da Stripe não é compatível com eventos baseados em webhook, atualizações em tempo real ou o Stripe Sigma.
  • As transferências de dados da Stripe de regiões em prévia podem ter problemas:
    • As opções de filtragem são restritas ou não estão disponíveis nas regiões de prévia do Stripe.
    • As transferências e consultas condicionais de dados não são compatíveis com as regiões de prévia do Stripe.
    • Você pode encontrar tempos de execução longos ao transferir dados das regiões de prévia da Stripe.
  • O conector da Stripe é compatível com alguns objetos com o filtro StartDate.
    • O formato obrigatório para o filtro StartDate é YYYY-MM-DD. Se nenhuma data de início for fornecida, o conector vai usar três anos antes da data atual. Se uma data anterior a 1º de janeiro de 2011 for fornecida, o conector usará automaticamente 1º de janeiro de 2011.
    • Para uma lista de objetos compatíveis, consulte Objetos com suporte para filtro StartDate.
  • Uma única configuração de transferência só pode oferecer suporte a uma execução de transferência de dados por vez. Se uma segunda transferência de dados for programada para ser executada antes da conclusão da primeira, apenas a primeira será concluída. Todas as outras transferências de dados que se sobrepõem à primeira serão ignoradas.
    • Para evitar transferências ignoradas em uma única configuração, recomendamos aumentar a duração entre grandes transferências de dados configurando a Frequência de repetição.

Antes de começar

Nas seções a seguir, descrevemos as etapas que você precisa seguir antes de criar uma transferência de dados da Stripe.

Pré-requisitos do Stripe

  • Você precisa ter uma conta de desenvolvedor da Stripe para autorizar uma transferência de dados da Stripe. Para registrar uma conta do Stripe, consulte Registro do Stripe.
  • Configure seu aplicativo de plataforma do Stripe com as seguintes etapas:
    1. Acesse a seção Desenvolvedores no painel da Stripe.
    2. Em Conectar, configure sua plataforma para oferecer suporte às contas Standard e Express.
  • As seguintes informações são necessárias para criar uma transferência de dados da Stripe:
    • Anote o ID da sua conta da Stripe. Para mais informações, consulte Criar uma conta.
    • Anote sua chave secreta ou restrita. Para mais informações, consulte Chaves de API.
  • Se você planeja transferir dados de contas conectadas, verifique se a plataforma está configurada para o Stripe Connect e tem acesso aos recursos necessários da conta. Para mais informações sobre o Stripe Connect, consulte Plataformas e marketplaces com o Stripe Connect.

Papéis obrigatórios do BigQuery

Para receber as permissões necessárias para criar uma transferência, peça ao administrador para conceder a você o papel do IAM Administrador do BigQuery (roles/bigquery.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma transferência. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar uma transferência:

  • bigquery.transfers.update no usuário
  • bigquery.datasets.get no conjunto de dados de destino
  • bigquery.datasets.update no conjunto de dados de destino

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Pré-requisitos do BigQuery

Tipos de conta da Stripe

O conector da Stripe é compatível com contas da plataforma e contas conectadas da Stripe. Para mais informações, consulte Tipos de conta do Connect.

Conectar contas de plataforma

Para executar uma transferência de dados do Stripe de apenas uma conta da plataforma, faça o seguinte ao configurar a transferência:

  • Insira o ID da conta da plataforma no campo ID da conta.
  • Insira a chave secreta ou restrita da conta da plataforma no campo Chave secreta/de API.
  • Em SyncAllConnectedAccounts, selecione False.

Para executar uma transferência de dados da Stripe para várias contas, por exemplo, uma conta de plataforma vinculada a contas conectadas, faça o seguinte ao configurar a transferência:

  • Insira o ID da conta da plataforma no campo ID da conta.
  • Insira a chave secreta ou restrita da conta da plataforma no campo Chave secreta/de API.
  • Em SyncAllConnectedAccounts, selecione True.

Conectar às contas vinculadas

As contas conectadas são contas da Stripe vinculadas à Stripe usando o Stripe Connect.

Para executar uma transferência de dados da Stripe de uma conta conectada, faça o seguinte ao configurar a transferência:

  • Insira o ID da conta da plataforma para a conta conectada no campo ID da conta.
  • Insira a chave secreta ou restrita da conta da plataforma a que a conta conectada está vinculada no campo Chave secreta/de API.
  • Em SyncAllConnectedAccounts, selecione False.

Configurar uma transferência de dados da Stripe

Adicione dados do Stripe ao BigQuery configurando uma configuração de transferência usando uma das seguintes opções:

Console

  1. Acesse a página "Transferências de dados" no console Google Cloud .

    Acesse Transferências de dados

  2. Clique em Criar transferência.

  3. Na seção Tipo de origem, em Origem, selecione Stripe.

  4. Na seção Detalhes da fonte de dados, faça o seguinte:

    • Em ID da plataforma/conta conectada, insira o ID da conta da Stripe. Para mais informações, consulte Pré-requisitos da Stripe.
    • Em Chave secreta da Stripe, insira a chave de API da conta da Stripe. Para mais informações, consulte Pré-requisitos da Stripe.
    • Em Data de início, insira uma data no formato YYYY-MM-DD. A transferência de dados carrega dados do Stripe a partir dessa data.
    • Selecione Sincronizar todas as contas conectadas.
    • Em Objetos do Stripe para transferência, insira os nomes dos objetos do Stripe ou clique em Procurar e selecione os objetos que você quer transferir.

  5. Na seção Configurações de destino, em Conjunto de dados, selecione o conjunto que você criou para armazenar seus dados.

  6. No campo Nome de exibição, na seção Nome de configuração da transferência, insira um nome para a transferência de dados.

  7. Na seção Opções de programação, realize estas ações:

    • Na lista Frequência de repetição, selecione uma opção para especificar com que frequência essa transferência de dados é executada. Para especificar uma frequência de repetição personalizada, selecione Personalizada. Se você selecionar Sob demanda, essa transferência vai ser executada quando você acionar manualmente a transferência.
    • Se aplicável, selecione Começar agora ou Começar no horário definido e forneça uma data de início e um horário de execução.

  8. Opcional: na seção Opções de notificação, faça o seguinte:

    • Para ativar as notificações por e-mail, clique no botão que ativa as Notificações por e-mail. Depois de ativar essa opção, o administrador de transferências recebe uma notificação por e-mail quando uma execução de transferência falha.
    • Para ativar as notificações de execução de transferência do Pub/Sub para essa transferência, clique no botão Notificações do Pub/Sub. Selecione o nome do tópico ou clique em Criar um tópico.

  9. Clique em Salvar.

bq

Insira o comando bq mk e forneça a sinalização de execução da transferência --transfer_config:

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

Em que:

  • PROJECT_ID (opcional): o ID do projeto do Google Cloud . Se --project_id não for fornecido para especificar um projeto determinado, o projeto padrão será usado.
  • DATA_SOURCE: a fonte de dados — stripe.
  • DISPLAY_NAME: o nome de exibição da configuração da transferência de dados. O nome da transferência pode ser qualquer valor que permita identificá-la, caso você precise modificá-la mais tarde.
  • DATASET: o conjunto de dados de destino na configuração da transferência.

  • PARAMETERS é o parâmetro da configuração de transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Confira a seguir os parâmetros de uma transferência de dados do Stripe:

    • assets: uma lista de objetos do Stripe a serem incluídos nesta transferência.
    • connector.accountId: o ID da conta do Stripe.
    • connector.secretKey: a chave de API da conta do Stripe.
    • connector.syncAllConnectedAccounts: especifique true para sincronizar todas as contas conectadas.
    • connector.startDate: insira uma data no formato YYYY-MM-DD. A transferência de dados carrega dados do Stripe a partir dessa data.

Por exemplo, o comando a seguir cria uma transferência de dados da Stripe no projeto padrão com todos os parâmetros necessários:

  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

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Quando você salva a configuração de transferência, o conector da Stripe aciona automaticamente uma execução de transferência de acordo com a opção de programação. A cada execução de transferência, o conector da Stripe transfere todos os dados disponíveis da Stripe para o BigQuery.

Para executar manualmente uma transferência de dados fora da sua programação regular, inicie uma execução de preenchimento.

Mapeamento de tipo de dados

A tabela a seguir mapeia os tipos de dados do Stripe para os tipos de dados correspondentes do BigQuery.

Tipo de dados do Stripe Tipo de dados do BigQuery Observações
String STRING
Dictionary STRING Quando um objeto aninhado é carregado no BigQuery, ele é convertido em um objeto simplificado. Esse objeto simplificado é salvo como uma única string literal na tabela.
Integer INT64
Double DOUBLE
Float FLOAT
Decimal BIGNUMERIC
BigInt (long) BIGNUMERIC
Boolean BOOL
Datetime TIMESTAMP
Unix timestamp TIMESTAMP

Objetos com suporte ao filtro StartDate

Os seguintes objetos do Stripe são compatíveis com o filtro StartDate, que permite carregar dados com base no tempo:

  • Contas
  • ApplicationFees
  • BalanceTransactions
  • Titulares de cartão
  • Cobranças
  • Cupons
  • Clientes
  • Disputas
  • EarlyFraudWarnings
  • Eventos
  • FileLinks
  • Arquivos
  • InvoiceItems
  • Faturas
  • IssuingCards
  • IssuingDisputes
  • PaymentIntent
  • Pagamentos
  • Planos
  • Preços
  • Produtos
  • PromotionCodes
  • Reembolsos
  • Avaliações
  • ShippingRates
  • Assinaturas
  • TaxRates
  • TopUps
  • Transferências
  • ValueListItems
  • ValueLists

Resolver problemas na configuração da transferência

Se você tiver problemas para configurar a transferência de dados, consulte Problemas de transferência do Stripe.

Preços

Não há custo para transferir dados do Stripe para o BigQuery enquanto esse recurso está em Pré-lançamento.

A seguir