Carregar dados da Stripe no BigQuery

É possível carregar dados da Stripe no BigQuery usando o conector da Stripe com o serviço de transferência de dados do BigQuery. Ao usar o conector da Stripe, você pode programar jobs de transferência recorrentes que adicionam seus dados mais recentes da Stripe ao BigQuery.

Limitações

As transferências de dados da 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 menores em valores da API.
  • O conector da Stripe só transfere 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 relatórios manualmente no painel da Stripe antes de iniciar a transferência de dados da Stripe.
    • Para mais informações, consulte Relatórios da Stripe.
  • O conector da Stripe não oferece suporte a eventos baseados em webhook, atualizações em tempo real ou Stripe Sigma.
  • As transferências de dados da Stripe de regiões da Stripe que estão em pré-lançamento podem encontrar problemas com transferências de dados:
    • As opções de filtragem são restritas ou indisponíveis nas regiões de pré-lançamento da Stripe.
    • As transferências e consultas de dados condicionais não são aceitas nas regiões de pré-lançamento da Stripe.
    • Você pode encontrar tempos de execução de transferência de dados longos ao transferir dados de regiões de pré-lançamento da Stripe.
  • O conector da Stripe oferece suporte a alguns objetos com o filtro StartDate.
    • O formato necessá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 vai usar automaticamente 1º de janeiro de 2011.
    • Para uma lista de objetos com suporte, consulte Objetos com suporte ao 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 transferência de dados será concluída, enquanto 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 de transferência, recomendamos que você aumente a duração do tempo entre grandes transferências de dados configurando a Frequência de repetição.

Antes de começar

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

Pré-requisitos da Stripe

  • Você precisa ter uma conta de desenvolvedor da Stripe para autorizar uma transferência de dados da Stripe. Para registrar uma conta da Stripe, consulte Registro da Stripe.
  • Configure o aplicativo da plataforma Stripe seguindo estas etapas:
    1. Navegue até a seção Desenvolvedores no painel da Stripe.
    2. Em Connect, configure sua plataforma para oferecer suporte a 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 chave restrita. Para mais informações, consulte Chaves de API.
  • Se você planeja transferir dados de contas conectadas, verifique se sua plataforma está configurada para o Stripe Connect e tem acesso aos recursos de conta necessários. 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 contas da Stripe

O conector da Stripe oferece suporte a contas de plataforma e contas conectadas da Stripe. Para mais informações, consulte Tipos de contas do Connect.

Conectar-se a contas de plataforma

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

  • Insira o ID da conta de plataforma no campo ID da conta.
  • Insira a chave secreta ou restrita da conta de 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, para uma conta de plataforma vinculada a contas conectadas, faça o seguinte ao configurar a transferência:

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

Conectar-se a contas conectadas

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 de plataforma da conta conectada no campo ID da conta.
  • Insira a chave secreta ou restrita da conta de plataforma à qual a conta conectada está conectada no campo Chave secreta/de API.
  • Em SyncAllConnectedAccounts, selecione False.

Configurar uma transferência de dados da Stripe

Adicione dados da Stripe ao BigQuery configurando uma transferência usando uma das seguintes opções:

Console

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

    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 conta conectada/da plataforma, 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 os dados da Stripe a partir dessa data.
    • Selecione Sincronizar todas as contas conectadas para sincronizar todas as contas conectadas.
    • Em Objetos da Stripe para transferência, insira os nomes dos objetos da Stripe para transferência 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 de dados 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 escolha uma data de início e hora de execução.

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

  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): ID do seu Google Cloud projeto. 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 da Stripe:

    • assets: uma lista de objetos da Stripe a serem incluídos nessa transferência.
    • connector.accountId: o ID da conta da Stripe.
    • connector.secretKey: a chave de API da conta da 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 os dados da 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 projects.locations.transferConfigs.create método e forneça uma instância do TransferConfig recurso.

Ao salvar 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. Com 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 programação normal, você pode iniciar uma execução de preenchimento.

Mapeamento de tipo de dados

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

Tipo de dados da Stripe Tipo de dados do BigQuery Observações
String STRING
Dictionary STRING Quando um objeto aninhado é carregado no BigQuery, ele é convertido em um objeto nivelado. Esse objeto nivelado é 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 da Stripe oferecem suporte ao filtro StartDate, que permite carregar dados com base no tempo:

  • Contas
  • ApplicationFees
  • BalanceTransactions
  • Cardholders
  • Charges
  • 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 da Stripe.

Preços

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

A seguir