Carregue dados do Stripe para o BigQuery

Pode carregar dados do Stripe para o BigQuery através do conetor do Stripe com o Serviço de transferência de dados do BigQuery. Ao usar o conetor do Stripe, pode agendar tarefas de transferência recorrentes que adicionam os seus dados mais recentes do Stripe ao BigQuery.

Limitações

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

  • Uma transferência de dados do Stripe carrega moedas de acordo com as unidades menores do Stripe. Para mais informações, consulte o artigo Unidades menores nos valores da API.
  • O conector do Stripe transfere apenas relatórios pré-gerados para cada conta do Stripe. O conetor do Stripe não gera novos relatórios com base nos novos dados do Stripe.
    • Para transferir relatórios atualizados, gere os relatórios manualmente no painel de controlo do Stripe antes de iniciar a transferência de dados do Stripe.
    • Para mais informações, consulte o artigo Relatórios do Stripe.
  • O conetor do Stripe não suporta eventos baseados em webhook, atualizações em tempo real nem o Stripe Sigma.
  • As transferências de dados do Stripe de regiões do Stripe em pré-visualização podem encontrar problemas com as transferências de dados:
    • As opções de filtragem estão restritas ou indisponíveis nas regiões de pré-visualização do Stripe.
    • As transferências e as consultas de dados condicionais não são suportadas nas regiões de pré-visualização do Stripe.
    • Pode deparar-se com tempos de execução de transferência de dados longos quando transfere dados de regiões de pré-visualização do Stripe.
  • O conetor do Stripe suporta alguns objetos com o filtro StartDate.
    • O formato necessário para o filtro StartDate é YYYY-MM-DD. Se não for indicada uma data de início, o conector usa como predefinição três anos antes da data atual. Se for fornecida uma data anterior a 1 de janeiro de 2011, o conetor usa automaticamente 1 de janeiro de 2011.
    • Para ver uma lista dos objetos suportados, consulte o artigo Objetos com suporte de filtros StartDate.
  • Uma única configuração de transferência só pode suportar uma execução de transferência de dados num determinado momento. Se estiver agendada a execução de uma segunda transferência de dados antes da conclusão da primeira, apenas a primeira transferência de dados é concluída. Todas as outras transferências de dados que se sobreponham à primeira são ignoradas.
    • Para evitar transferências ignoradas numa única configuração de transferência, recomendamos que aumente a duração do tempo entre transferências de dados grandes configurando a frequência de repetição.

Antes de começar

As secções seguintes descrevem os passos que tem de seguir antes de criar uma transferência de dados do Stripe.

Pré-requisitos do Stripe

  • Tem de ter uma conta de programador do Stripe para autorizar uma transferência de dados do Stripe. Para registar uma conta do Stripe, consulte o artigo Registo no Stripe.
  • Configure a sua aplicação da plataforma Stripe com os seguintes passos:
    1. Navegue para a secção Developers no painel de controlo do Stripe.
    2. Em Associar, configure a sua plataforma para suportar contas Padrão e Expresso.
  • São necessárias as seguintes informações para criar uma transferência de dados do Stripe:
    • Tome nota do ID da sua conta do Stripe. Para mais informações, consulte Crie uma conta.
    • Anote a sua chave secreta ou chave restrita. Para mais informações, consulte o artigo Chaves da API.
  • Se planeia transferir dados de contas associadas, certifique-se de que a sua plataforma está configurada para o Stripe Connect e tem acesso às capacidades da conta necessárias. Para mais informações sobre o Stripe Connect, consulte o artigo Plataformas e mercados com o Stripe Connect.

Funções do BigQuery necessárias

Para obter as autorizações de que precisa para criar uma transferência, peça ao seu administrador para lhe conceder a função do IAM de administrador do BigQuery (roles/bigquery.admin) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar uma transferência. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar uma transferência:

  • bigquery.transfers.update no utilizador
  • bigquery.datasets.get no conjunto de dados de destino
  • bigquery.datasets.update no conjunto de dados de destino

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Pré-requisitos do BigQuery

Tipos de contas do Stripe

O conetor do Stripe suporta contas da plataforma do Stripe e contas associadas do Stripe. Para mais informações, consulte o artigo Associe tipos de contas.

Associe contas de plataformas

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

  • Introduza o ID da conta da plataforma no campo ID da conta.
  • Introduza a chave secreta ou restrita da conta da plataforma no campo Chave secreta/da API.
  • Para SyncAllConnectedAccounts, selecione Falso.

Para executar uma transferência de dados do Stripe para várias contas, por exemplo, para uma conta de plataforma associada a contas associadas, faça o seguinte quando configurar a configuração de transferência:

  • Introduza o ID da conta da plataforma no campo ID da conta.
  • Introduza a chave secreta ou restrita da conta da plataforma no campo Chave secreta/da API.
  • Para SyncAllConnectedAccounts, selecione Verdadeiro.

Associe a contas associadas

As contas associadas são contas do Stripe associadas ao Stripe através do Stripe Connect.

Para executar uma transferência de dados do Stripe a partir de uma conta associada, faça o seguinte quando configurar a configuração de transferência:

  • Introduza o ID da conta da plataforma para a conta associada no campo ID da conta.
  • Introduza a chave secreta ou restrita da conta da plataforma à qual a conta associada está associada no campo Chave secreta/API.
  • Para SyncAllConnectedAccounts, selecione Falso.

Configure uma transferência de dados do Stripe

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

Consola

  1. Aceda à página Transferências de dados na Google Cloud consola.

    Aceda a Transferências de dados

  2. Clique em Criar transferência.

  3. Na secção Tipo de origem, para Origem, selecione Stripe.

  4. Na secção Detalhes da origem de dados, faça o seguinte:

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

  5. Na secção Definições de destino, para Conjunto de dados, selecione o conjunto de dados que criou para armazenar os seus dados.

  6. Na secção Nome da configuração de transferência, em Nome a apresentar, introduza um nome para a transferência de dados.

  7. Na secção Opções de agendamento, faça o seguinte:

    • Na lista Frequência de repetição, selecione uma opção para especificar a frequência com que esta transferência de dados é executada. Para especificar uma frequência de repetição personalizada, selecione Personalizado. Se selecionar A pedido, esta transferência é executada quando aciona manualmente a transferência.
    • Se aplicável, selecione Começar agora ou Começar à hora definida e indique uma data de início e um tempo de execução.

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

    • Para ativar as notificações por email, clique no botão Notificação por email. Depois de ativar esta opção, o administrador da transferência recebe uma notificação por email quando uma execução de transferência falha.
    • Para ativar as notificações de execução da transferência do Pub/Sub para esta transferência, clique no botão para ativar/desativar notificações do Pub/Sub. Pode selecionar o nome do tópico ou clicar em Criar um tópico para criar um.

  9. Clique em Guardar.

bq

Introduza o comando bq mk e forneça a flag de criação de 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'

Onde:

  • PROJECT_ID (opcional): o ID do seu Google Cloud projeto. Se --project_id não for fornecido para especificar um projeto em particular, é usado o projeto predefinido.
  • DATA_SOURCE: a origem de dados: stripe.
  • DISPLAY_NAME: o nome a apresentar da configuração de transferência de dados. O nome da transferência pode ser qualquer valor que lhe permita identificar a transferência se precisar de a modificar mais tarde.
  • DATASET: o conjunto de dados de destino para a configuração de transferência.

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

    • assets: uma lista de objetos Stripe a incluir nesta transferência.
    • connector.accountId: o ID da conta do Stripe.
    • connector.secretKey: a chave da API para a conta do Stripe.
    • connector.syncAllConnectedAccounts: especifique true para sincronizar todas as contas associadas.
    • connector.startDate: introduza uma data no formato YYYY-MM-DD. A transferência de dados carrega os dados do Stripe a partir desta data.

Por exemplo, o seguinte comando cria uma transferência de dados do Stripe no projeto predefinido 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 guarda a configuração de transferência, o conector do Stripe aciona automaticamente uma execução de transferência de acordo com a opção de agendamento. Com cada execução de transferência, o conetor do Stripe transfere todos os dados disponíveis do Stripe para o BigQuery.

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

Mapeamento de tipos de dados

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

Tipo de dados de faixas Tipo de dados do BigQuery Notas
String STRING
Dictionary STRING Quando um objeto aninhado é carregado no BigQuery, é convertido num objeto simplificado. Este objeto achatado é, em seguida, guardado 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 de filtro StartDate

Os seguintes objetos do Stripe suportam o filtro StartDate, que lhe permite carregar dados baseados no tempo:

  • Contas
  • ApplicationFees
  • BalanceTransactions
  • Titulares de cartões
  • Cobranças
  • Cupões
  • Clientes
  • Diferendos
  • EarlyFraudWarnings
  • Eventos
  • FileLinks
  • Ficheiros
  • InvoiceItems
  • Faturas
  • IssuingCards
  • IssuingDisputes
  • PaymentIntent
  • Pagamentos
  • Planos
  • Preços
  • Produtos
  • PromotionCodes
  • Reembolsos
  • Críticas
  • ShippingRates
  • Subscrições
  • TaxRates
  • TopUps
  • Transferências
  • ValueListItems
  • ValueLists

Resolva problemas de configuração da transferência

Se estiver a ter problemas com a configuração da transferência de dados, consulte o artigo Problemas de transferência do Stripe.

Preços

Não existe custo para transferir dados do Stripe para o BigQuery enquanto esta funcionalidade estiver em pré-visualização.

O que se segue?