Carregar dados do PayPal no BigQuery

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para receber suporte ou enviar feedback sobre esse recurso, entre em contato com [e-mail].

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

O conector do PayPal oferece suporte a contas de produção e sandbox do PayPal.

Objetos com suporte

Tipos de objetos do PayPal	Objetos com suporte do BigQuery	Suporte ao filtro por data
Transações	TransactionReports	Com suporte
	TransactionReportsCartInfoItemDetails	Com suporte
	TransactionReportsIncentiveDetails	Com suporte
Disputes	Disputes	Com suporte
	DisputeDetails	Com suporte
	DisputeTransactions	Com suporte
Pagamentos	Payments	Com suporte
	PaymentTransactions	Com suporte
Saldo	Balance	Indisponível
Produtos	Products	Indisponível
	ProductDetails	Indisponível
Faturas	Invoices	Com suporte

Limitações

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

• Pode haver um atraso de várias horas até que as transações do PayPal fiquem disponíveis pela API do PayPal.
  • Recomendamos programar transferências de dados subsequentes em intervalos mais longos (não mais de uma a cada hora) para evitar a perda de dados.
• O conector do PayPal só oferece suporte a dados de transações dos últimos três anos.
• O conector do PayPal só oferece suporte a dados de disputas dos últimos seis meses.
• As APIs do PayPal usam limites de tamanho de página diferentes para cada objeto de dados. O conector do PayPal usa o tamanho máximo de página permitido pelo PayPal em uma transferência de dados.
  • No entanto, alguns objetos, como Payments ou Payment Transactions, usam limites de tamanho de página menores. Isso pode levar a transferências de dados mais lentas, especialmente ao lidar com conjuntos de dados grandes.

Antes de começar

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

Pré-requisitos do PayPal

Para ativar as transferências de dados do PayPal, você precisa ter o seguinte:

• É necessário ter uma conta de desenvolvedor do PayPal. Para mais informações, consulte Programa para desenvolvedores do PayPal.
• Crie um app da API REST do PayPal. Para mais informações, consulte Introdução às APIs REST do PayPal.
  • Na seção Apps e credenciais, anote o ID do cliente e a chave secreta do app.
  • Na seção Recursos, ative as permissões da API Pesquisa de transações e Faturamento.

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). 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

• Verifique se você realizou todas as ações necessárias para ativar o serviço de transferência de dados do BigQuery.
• Crie um conjunto de dados do BigQuery para armazenar os dados.
• Se quiser configurar notificações de execução de transferência do Pub/Sub, verifique se você tem a permissão pubsub.topics.setIamPolicy do Identity and Access Management (IAM). As permissões do Pub/Sub não serão necessárias caso você configure notificações por e-mail. Para mais informações, consulte Notificações de execução do serviço de transferência de dados do BigQuery.

Configurar uma transferência de dados do PayPal

Adicione dados do PayPal 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 PayPal.

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

   • Em ID do cliente, insira o ID do cliente do PayPal. Para mais informações, consulte Pré-requisitos do PayPal.
   • Em Chave secreta do cliente, insira a chave secreta do cliente do PayPal. Para mais informações, consulte Pré-requisitos do PayPal.
   • Selecione É sandbox se você estiver usando uma conta do PayPal sandbox.
   • Em Data de início, insira uma data no formato YYYY-MM-DD. A transferência de dados carrega os dados do PayPal a partir dessa data.
     • Se esse campo for deixado em branco, essa transferência será definida como padrão para recuperar dados dos últimos três anos.
     • Para informações sobre quais objetos oferecem suporte ao filtro de data de início, consulte Objetos com suporte.
   • Em Objetos do PayPal para transferência, insira os nomes dos objetos do PayPal a serem transferidos 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:

   • Para ativar as notificações por e-mail, ative a opção Notificação por e-mail. Quando você ativa essa opção, o administrador de transferência 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, ative a opção Notificações do Pub/Sub. Você pode selecionar o nome do seu tópico ou clicar em Criar um tópico para criar um.

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 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 — paypal.
• 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 PayPal:

  • assets: uma lista de objetos do PayPal a serem incluídos nessa transferência.
  • connector.authentication.clientId: ID do cliente do aplicativo PayPal.
  • connector.authentication.clientSecret: chave secreta do cliente do aplicativo PayPal.
  • connector.isSandbox: defina o valor como true se você estiver usando uma conta do PayPal sandbox ou false se estiver usando uma conta de produção do PayPal.
  • connector.createdStartDate: (opcional) insira uma data no formato YYYY-MM-DD. A transferência de dados carrega os dados do PayPal a partir dessa data.

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

  bq mk \
      --transfer_config \
      --target_dataset=mydataset \
      --data_source=PayPal \
      --display_name='My Transfer' \
      --params='{"assets":  ["Payments", "TransactionReports"],
          "connector.authentication.clientId": "112233445566",
          "connector.authentication.clientSecret":"123456789",
          "connector.isSandbox":"false",
          "connector.createdStartDate":  "2025-01-01"}'

Ao criar uma transferência de dados usando a ferramenta de linha de comando bq, a configuração de transferência programa transferências de dados uma vez a cada 8 horas.

**Observação**: não é possível configurar notificações se você configurar uma transferência usando a ferramenta de linha de comando bq.

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 do PayPal 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 do PayPal transfere todos os dados disponíveis do PayPal 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 do PayPal para os tipos de dados correspondentes do BigQuery.

Tipo de dados do PayPal	Tipo de dados do BigQuery
String	STRING
Decimal	BIGNUMERIC
Boolean	BOOL
Datetime	TIMESTAMP

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 PayPal.

Preços

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

A seguir

• Para uma visão geral do serviço de transferência de dados do BigQuery, consulte Introdução ao serviço de transferência de dados do BigQuery.
• Para saber como gerenciar configurações de transferência, incluindo como receber informações, listar configurações e visualizar o histórico de execução, consulte Gerenciar transferências.
• Saiba como carregar dados com operações entre nuvens.