# Conexão com o PayPal O PayPal é um sistema de pagamentos que facilita transferências de dinheiro online entre partes, como transferências entre clientes e fornecedores online. Se você for usuário do PayPal, sua conta contém dados sobre suas transações, como pagadores, datas e status. É possível usar o AWS Glue para transferir dados do PayPal para determinados serviços da AWS ou outras aplicações com suporte. **Topics** + [Suporte do AWS Glue para PayPal](paypal-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](paypal-configuring-iam-permissions.md) + [Configuração do PayPal](paypal-configuring.md) + [Configuração de conexões do PayPal](paypal-configuring-connections.md) + [Leitura de entidades do PayPal](paypal-reading-from-entities.md) + [Opções de conexão do PayPal](paypal-connection-options.md) + [Limitações e notas do conector do PayPal](paypal-connector-limitations.md) # Suporte do AWS Glue para PayPal O AWS Glue oferece suporte ao PayPal da seguinte forma: **Compatível como fonte?** Sim. É possível usar trabalhos de ETL do AWS Glue para consultar dados do PayPal. **Compatível como destino?** Nº **Versões da API do PayPal com suporte** Versões da API do PayPal com suporte: + v1 # Políticas que contêm as operações de API para criar e usar conexões O exemplo de política a seguir descreve as permissões necessárias do AWS IAM para criar e usar conexões. Se você estiver criando um novo perfil, crie uma política que contenha o seguinte: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ Se você não quiser usar o método acima, como alternativa use as seguintes políticas do IAM gerenciadas: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Concede acesso a recursos que vários processos do AWS Glue exigem para fazer a execução em seu nome. Esses recursos incluem o AWS Glue, Amazon S3, IAM, CloudWatch Logs e Amazon EC2. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os processos do AWS Glue terão as permissões necessárias. Esta política geralmente é anexada a funções especificadas durante a definição de crawlers, trabalhos e endpoints de desenvolvimento. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess): concede acesso total aos recursos do AWS Glue quando uma identidade à qual a política está anexada usa o Console de Gerenciamento da AWS. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os usuários poderão acessar todos os recursos do console. Esta política geralmente é anexada aos usuários do console do AWS Glue. # Configuração do PayPal Antes de poder usar o AWS Glue para transferir dados do PayPal, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos Estes são os requisitos mínimos: + Você tem uma conta do PayPal com credenciais de cliente. + Sua conta do PayPal tem acesso à API com uma licença válida. Se você atender a esses requisitos, poderá conectar o AWS Glue à conta do PayPal. Para conexões típicas, você não precisa fazer mais nada no PayPal. # Configuração de conexões do PayPal O PayPal oferece suporte ao tipo de concessão CLIENT CREDENTIALS para OAuth2. + Esse tipo de concessão é considerado OAuth 2.0 de 2 pernas, pois é usado pelos clientes para obter um token de acesso fora do contexto de um usuário. O AWS Glue é capaz de usar o ID do cliente e o segredo do cliente para autenticar as APIs do PayPal que são fornecidas pelos serviços personalizados que você define. + Cada serviço personalizado é de propriedade de um usuário somente de API que tem um conjunto de perfis e permissões que autorizam o serviço a realizar ações específicas. Um token de acesso é associado a um único serviço personalizado. + Esse tipo de concessão resulta em um token de acesso de curta duração, que pode ser renovado com uma chamada ao endpoint `/v2/oauth2/token` novamente. + Para obter a documentação pública do PayPal para OAuth 2.0 com credenciais de cliente, consulte [Autenticação](https://developer.paypal.com/api/rest/authentication/). Para configurar uma conexão do PayPal: 1. No AWS Secrets Manager, crie um segredo com os seguintes detalhes: 1. Para a aplicação conectada gerenciada pelo cliente, o segredo deve conter a aplicação conectada Segredo do consumidor com a chave `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`. 1. Observação: é necessário criar um segredo para a sua conexão no AWS Glue. 1. No AWS Glue Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas: 1. Ao selecionar um **Tipo de conexão**, escolha PayPal. 1. Forneça o `INSTANCE_URL` da instância do PayPal à qual você deseja se conectar. 1. Selecione o perfil do AWS IAM que o AWS Glue pode assumir e tem permissões para as seguintes ações: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Selecione o `secretName` que você deseja usar para essa conexão no AWS Glue para colocar os tokens. 1. Selecione as opções de rede se quiser usar sua rede. 1. Conceda permissão ao perfil do IAM associado ao seu trabalho do AWS Glue para ler `secretName`. ## Obtenção de credenciais do Outh 2.0 Para chamar a API REST, você precisará trocar seu ID do cliente e segredo do cliente por um token de acesso. Para obter mais informações, consulte [Conceitos básicos das APIs REST do PayPal](https://developer.paypal.com/api/rest/). # Leitura de entidades do PayPal **Pré-requisito** Um objeto do PayPal do qual você deseja ler. Você precisará do nome do objeto, `transaction`. **Entidades compatíveis quanto à origem**: | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | transaction | Sim | Sim | Não | Sim | Sim | **Exemplo:** ``` paypal_read = glueContext.create_dynamic_frame.from_options( connection_type="paypal", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "transaction", "API_VERSION": "v1", "INSTANCE_URL": "https://api-m.paypal.com" } ``` **Detalhes de entidade e campo do PayPal**: Entidades com metadados estáticos: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/paypal-reading-from-entities.html) ## Consultas de particionamento É possível fornecer as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se quiser utilizar a simultaneidade no Spark. Com esses parâmetros, a consulta original seria dividida em `NUM_PARTITIONS` subconsultas, que poderiam ser executadas pelas tarefas do Spark simultaneamente. + `PARTITION_FIELD`: o nome do campo a ser usado para particionar a consulta. + `LOWER_BOUND`: um valor limite inferior **inclusivo** do campo de partição escolhido. Para o campo Datetime, aceitamos o valor no formato ISO. Exemplos de valores válidos: ``` "2024-07-01T00:00:00.000Z" ``` + `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido. + `NUM_PARTITIONS`: o número de partições. Há suporte para o campo a seguir para particionamento por entidade: | Nome da entidade | Campos de particionamento | Tipo de dados | | --- | --- | --- | | transaction | transaction\$1initiation\$1date | DateTime | Exemplo: ``` paypal_read = glueContext.create_dynamic_frame.from_options( connection_type="paypal", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "transaction", "API_VERSION": "v1", "PARTITION_FIELD": "transaction_initiation_date" "LOWER_BOUND": "2024-07-01T00:00:00.000Z" "UPPER_BOUND": "2024-07-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # Opções de conexão do PayPal Estas são as opções de conexão do PayPal: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no PayPal. + `API_VERSION`(string): (obrigatório) usado para leitura. Versão da API Rest do PayPal que você deseja usar. + `SELECTED_FIELDS`(Lista): padrão: vazio(SELECIONE \$1). Usado para leitura. Colunas que deseja selecionar para o objeto. + `FILTER_PREDICATE`(string): padrão: vazio. Usado para leitura. Deve estar no formato Spark SQL. + `QUERY`(String): padrão: vazia. Usado para leitura. Consulta completa do Spark SQL. + `PARTITION_FIELD`(string): usado para leitura. Campo a ser usado para particionar a consulta. + `LOWER_BOUND`(string): usado para leitura. Um valor limite inferior inclusivo do campo de partição escolhido. + `UPPER_BOUND`(string): usado para leitura. Um valor limite superior exclusivo do campo de partição escolhido. + `NUM_PARTITIONS`(Inteiro): padrão: 1. Usado para leitura. Número de partições para leitura. # Limitações e notas do conector do PayPal Estas são as limitações ou notas do conector do PayPal: + A [documentação de transações do PayPal](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get) menciona que são necessárias no máximo três horas para que as transações executadas apareçam na chamada de listagem de transações. No entanto, observou-se que leva mais tempo do que isso, dependendo da [https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=last_refreshed_datetime](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=last_refreshed_datetime). Aqui, `last_refreshed_datetime` é o tempo até o qual você tem dados disponíveis nas APIs. + Se a `last_refreshed_datetime` for menor que a `end_date` solicitada, então a `end_date` torna-se igual à `last_refreshed_datetime`, pois só temos dados até aquele ponto. + O campo `transaction_initiation_date` é um filtro obrigatório a ser fornecido para a entidade `transaction` e o intervalo de datas [máximo suportado](https://developer.paypal.com/docs/transaction-search/#:~:text=The%20maximum%20supported%20date%20range%20is%2031%20days.) para esse campo é de 31 dias. + Quando você chama a solicitação de API da entidade `transaction` com filtros (parâmetros de consulta) diferentes do campo `transaction_initiation_date`, espera-se que o valor do campo [https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=If%20you%20specify%20one%20or%20more%20optional%20query%20parameters%2C%20the%20ending_balance%20response%20field%20is%20empty.](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=If%20you%20specify%20one%20or%20more%20optional%20query%20parameters%2C%20the%20ending_balance%20response%20field%20is%20empty.) não seja obtido na resposta.