# Conexão ao Pipedrive O Pipedrive é um CRM de pipeline de vendas projetado para ajudar pequenas empresas a gerenciar leads, rastrear atividades de vendas e fechar mais negócios. O Pipedrive permite que as equipes de vendas em pequenas empresas simplifiquem processos e consolidem dados de vendas em uma ferramenta unificada de CRM de vendas. Se você usa o Pipedrive, pode conectar o AWS Glue à conta do Pipedrive. Em seguida, será possível usar o Pipedrive como fonte de dados nos seus trabalhos de ETL. Execute esses trabalhos para transferir dados entre o Pipedrive e serviços da AWS ou outras aplicações compatíveis. **Topics** + [Suporte do AWS Glue para o Pipedrive](pipedrive-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](pipedrive-configuring-iam-permissions.md) + [Configuração do Pipedrive](pipedrive-configuring.md) + [Configuração de conexões do Pipedrive](pipedrive-configuring-connections.md) + [Leitura de entidades do Pipedrive](pipedrive-reading-from-entities.md) + [Referência de opções de conexão do Pipedrive](pipedrive-connection-options.md) + [Limitações](pipedrive-connector-limitations.md) # Suporte do AWS Glue para o Pipedrive O AWS Glue oferece suporte ao Pipedrive da seguinte forma: **Compatível como fonte?** Sim. Você pode usar trabalhos de ETL do AWS Glue para consultar dados do Pipedrive. **Compatível como destino?** Não. **Versões compatíveis da API do Pipedrive** 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 da AWS necessárias 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": "*" } ] } ``` ------ É possível usar as seguintes políticas gerenciadas do IAM para permitir acesso: + [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 serem executados 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 Pipedrive Antes de usar o AWS Glue para transferir dados do Pipedrive, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos + Você tem uma conta do Pipedrive. + Sua conta do Pipedrive está habilitada para acesso à API. Se você atender a esses requisitos, poderá conectar o AWS Glue à sua conta do Pipedrive. Para conexões típicas, você não precisa fazer mais nada no Pipedrive. # Configuração de conexões do Pipedrive O Pipedrive oferece suporte ao tipo de concessão AUTHORIZATION\$1CODE para OAuth2. + Esse tipo de concessão é considerado um OAuth de “três pernas”, pois conta com o redirecionamento dos usuários para o servidor de autorização de terceiros para autenticar o usuário. Ele é usado na criação de conexões por meio do Console do AWS Glue. O usuário que está criando uma conexão pode, por padrão, contar com uma aplicação conectada pertencente ao AWS Glue, na qual ele não precisa fornecer quaisquer informações relacionadas ao OAuth, exceto o instanceurl do Pipedrive. O Console do AWS Glue redirecionará o usuário para o Pipedrive, onde ele deverá fazer login e dar autorização para que as permissões solicitadas pelo AWS Glue acessem a instância do Pipedrive. + Os usuários devem optar por criar sua própria aplicação conectada no Pipedrive e fornecer seus próprios ID e segredo do cliente ao criar conexões por meio do Console do AWS Glue. Nesse cenário, eles ainda serão redirecionados para o Pipedrive para fazer login e autorizar o acesso do AWS Glue aos recursos. + Esse tipo de concessão resulta em um token de atualização e um token de acesso. O token de acesso ficará ativo por uma hora e poderá ser atualizado automaticamente sem a interação do usuário por meio do token de atualização. + Para obter mais informações, consulte a [documentação sobre como criar uma aplicação conectada para o fluxo AUTHORIZATION\$1CODE do OAuth](https://developers.pipedrive.com/docs/api/v1/Oauth). Para configurar uma conexão do Pipedrive: 1. No AWS Secrets Manager, crie um segredo com os detalhes a seguir. É necessário criar um segredo para cada conexão no AWS Glue. 1. Para uma aplicação conectada gerenciada pelo cliente, o segredo deve conter o segredo do consumidor da aplicação conectada com a chave USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET. 1. Em AWS Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas: 1. Em Conexões de dados, escolha **Criar conexão**. 1. Ao selecionar uma **Fonte de dados**, selecione o Pipedrive. 1. Forneça o **instanceURL** do Pipedrive. 1. Selecione o perfil do 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. Forneça o ClientId da aplicação cliente gerenciada pelo usuário do Pipedrive ao qual deseja se conectar. 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`. Escolha **Próximo**. 1. Forneça o **connectionName** e escolha **Próximo**. 1. Na página seguinte, escolha **Criar conexão**. Você precisará fazer login no Pipedrive. Forneça seu nome de usuário e senha e selecione **Fazer login**. 1. Depois de fazer login, escolha **Continuar para a aplicação**. Agora sua conexão está pronta para ser usada. 1. Na configuração do trabalho do AWS Glue, forneça `connectionName` como uma **Conexão de rede adicional**. # Leitura de entidades do Pipedrive **Pré-requisitos** + Um objeto do Pipedrive do qual você deseja ler. Consulte a tabela de entidades compatíveis abaixo para verificar as entidades disponíveis. **Entidades compatíveis** | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | Atividades | Sim | Sim | Não | Sim | Sim | | Tipo de atividade | Não | Não | Não | Sim | Não | | Logs de chamadas | Não | Não | Não | Sim | Não | | Moedas | Sim | Sim | Não | Sim | Não | | Ofertas | Sim | Sim | Sim | Sim | Sim | | Leads | Sim | Sim | Sim | Sim | Não | | Fontes de leads | Não | Sim | Não | Sim | Não | | Rótulos de leads | Não | Não | Não | Não | Não | | Observações | Sim | Sim | Sim | Sim | Sim | | Organização | Sim | Sim | Não | Sim | Sim | | Conjuntos de permissões | Sim | Não | Não | Sim | Não | | Pessoas | Sim | Sim | Sim | Sim | Sim | | Pipelines | Não | Sim | Não | Sim | Não | | Produtos | Sim | Sim | Não | Sim | Sim | | Perfis | Não | Sim | Não | Sim | Não | | Estágios | Sim | Sim | Não | Sim | Não | | Usuários | Não | Não | Não | Sim | Não | **Exemplo** ``` pipedrive_read= glueContext.create_dynamic_frame.from_options( connection_type="PIPEDRIVE", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "activites", "API_VERSION": "v1" } ``` **Detalhes das entidades e dos campos do Pipedrive** Lista de entidades: + Atividades: [https://developers.pipedrive.com/docs/api/v1/Activities](https://developers.pipedrive.com/docs/api/v1/Activities) + Tipo de atividade: [https://developers.pipedrive.com/docs/api/v1/ActivityTypes](https://developers.pipedrive.com/docs/api/v1/ActivityTypes) + Logs de chamadas: [https://developers.pipedrive.com/docs/api/v1/CallLogs](https://developers.pipedrive.com/docs/api/v1/CallLogs) + Moedas: [https://developers.pipedrive.com/docs/api/v1/Currencies](https://developers.pipedrive.com/docs/api/v1/Currencies) + Ofertas: [https://developers.pipedrive.com/docs/api/v1/Deals](https://developers.pipedrive.com/docs/api/v1/Deals) + Leads: [https://developers.pipedrive.com/docs/api/v1/Leads](https://developers.pipedrive.com/docs/api/v1/Leads) + Fontes de leads: [https://developers.pipedrive.com/docs/api/v1/LeadSources](https://developers.pipedrive.com/docs/api/v1/LeadSources) + Rótulos de leads: [https://developers.pipedrive.com/docs/api/v1/LeadLabels](https://developers.pipedrive.com/docs/api/v1/LeadLabels) + Observações: [https://developers.pipedrive.com/docs/api/v1/Notes](https://developers.pipedrive.com/docs/api/v1/Notes) + Organizações: [https://developers.pipedrive.com/docs/api/v1/Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations) + Conjuntos de permissões: [https://developers.pipedrive.com/docs/api/v1/PermissionSets](https://developers.pipedrive.com/docs/api/v1/PermissionSets) + Pessoas: [https://developers.pipedrive.com/docs/api/v1/Persons](https://developers.pipedrive.com/docs/api/v1/Persons) + Pipelines: [https://developers.pipedrive.com/docs/api/v1/Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines) + Produtos: [https://developers.pipedrive.com/docs/api/v1/Products](https://developers.pipedrive.com/docs/api/v1/Products) + Perfis: [https://developers.pipedrive.com/docs/api/v1/Roles](https://developers.pipedrive.com/docs/api/v1/Roles) + Estágios: [https://developers.pipedrive.com/docs/api/v1/Stages](https://developers.pipedrive.com/docs/api/v1/Stages) + Usuários: [https://developers.pipedrive.com/docs/api/v1/Users](https://developers.pipedrive.com/docs/api/v1/Users) | Entidade | Tipo de dado | Operadores com suporte | | --- | --- | --- | | Atividades, Ofertas, Observações, Organização, Pessoas e Produtos. | Data | '=' | | | Inteiro | '=' | | | String | '=' | | | Booleano | '=' | ## Particionamento de consultas No Pipedrive, apenas um campo (due\$1date) da entidade Atividades oferece suporte ao particionamento baseado em campos, que é um campo de Data. Podem ser fornecidas as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se você 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. Na data, aceitamos o formato de data do Spark usado em consultas SQL do Spark. Exemplo de valores válidos: `"2024-02-06"`. + `UPPER_BOUND`: um valor limite superior exclusivo do campo de partição escolhido. + `NUM_PARTITIONS`: número de partições. **Exemplo** ``` pipedrive_read = glueContext.create_dynamic_frame.from_options( connection_type="PIPEDRIVE", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "activites", "API_VERSION": "v1", "PARTITION_FIELD": "due_date" "LOWER_BOUND": "2023-09-07T02:03:00.000Z" "UPPER_BOUND": "2024-05-07T02:03:00.000Z" "NUM_PARTITIONS": "10" } ``` # Referência de opções de conexão do Pipedrive Estas são as opções de conexão do Pipedrive: + `ENTITY_NAME`(string): (obrigatório) usado para leitura/gravação. O nome do seu objeto no Pipedrive. + `API_VERSION`(string): (obrigatório) usado para leitura/gravação. A versão da API Rest do Pipedrive que você deseja usar. Exemplo: v1. + `INSTANCE_URL`(string): (obrigatório) o URL da instância em que o usuário deseja executar as operações. Exemplo: v1. + `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 Estas são as limitações do conector do Pipedrive: + O Pipedrive oferece suporte ao particionamento baseado em campos para apenas uma entidade (Atividades). + O Pipedrive oferece suporte ao particionamento baseado em registros para as entidades Atividades, Ofertas, Observações, Pessoas, Organizações e Produtos. + Na entidade Ofertas, o campo de status como filtro retornará todos os registros se um valor de filtro inválido for usado. + Na entidade Ofertas, não há suporte para a ordenação com vários campos. + Para obter dados de performance, utilizamos uma conta local da AWS. No entanto, devido à limitação de atualizar o token de acesso localmente, o trabalho do AWS Glue para processar 1 GB de dados está falhando. Consequentemente, otimizamos o teste de performance com 179 MB de dados, e os resultados acima são baseados nessa otimização. Ainda assim, observamos que, com um número cada vez maior de partições, o endpoint SaaS está levando mais tempo, em comparação ao processamento com uma única partição. Consultamos a equipe de suporte do Pipedrive sobre esse comportamento e eles nos informaram que o Pipedrive está silenciosamente limitando as solicitações e atrasando a resposta. Portanto, executar o trabalho do AWS Glue com grandes conjuntos de dados ou chamar o mesmo endpoint de API várias vezes pode resultar em um problema de tempo limite devido à implementação da API do Pipedrive. Porém, os tempos de resposta do conector e do shim estão diminuindo conforme o esperado com o aumento do número de partições.