# 连接到 Pipedrive Pipedrive 是一个销售管线 CRM，旨在帮助小型企业管理潜在客户、跟踪销售活动以及完成更多交易。Pipedrive 让小型企业的销售团队能够：在一个统一的 CRM 销售工具中简化流程并整合销售数据。如果您是 Pipedrive 用户，则可以将 AWS Glue 连接到自己的 Pipedrive 账户。然后，您可以使用 Pipedrive 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Pipedrive 与 AWS 服务或其他受支持的应用程序之间传输数据。 **Topics** + [AWS Glue 对 Pipedrive 的支持](pipedrive-support.md) + [包含创建和使用连接的 API 操作的策略](pipedrive-configuring-iam-permissions.md) + [配置 Pipedrive](pipedrive-configuring.md) + [配置 Pipedrive 连接](pipedrive-configuring-connections.md) + [从 Pipedrive 实体读取内容](pipedrive-reading-from-entities.md) + [Pipedrive 连接选项参考](pipedrive-connection-options.md) + [限制](pipedrive-connector-limitations.md) # AWS Glue 对 Pipedrive 的支持 AWS Glue 对 Pipedrive 的支持情况如下： **是否支持作为来源？** 是。可以使用 AWS Glue ETL 作业查询 Pipedrive 中的数据。 **是否支持作为目标？** 否。 **支持的 Pipedrive API 版本** v1。 # 包含创建和使用连接的 API 操作的策略 以下示例策略描述了创建和使用连接所需的 AWS 权限。如果您要创建新角色，请创建包含以下内容的策略： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ 您还可以使用以下托管 IAM 策略允许访问权限： + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole)：授予对各种 AWS Glue 进程代表您运行所需的资源的访问权限。这些资源包括 AWS Glue、Amazon S3、IAM、CloudWatch Logs 和 Amazon EC2。如果您遵循此策略中指定的资源的命名约定，则 AWS Glue 进程具有所需的权限。此策略通常附加到在定义爬网程序、作业和开发终端节点时指定的角色。 + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess)：当策略所附加到的身份使用 AWS 管理控制台时，授予对 AWS Glue 资源的完全访问权限。如果遵循此策略中指定的资源的命名约定，则用户具有完全控制台功能。此策略通常附加到 AWS Glue 控制台的用户。 # 配置 Pipedrive 必须满足以下要求，才能使用 AWS Glue 从 Pipedrive 传输数据： ## 最低要求 + 拥有 Pipedrive 账户。 + Pipedrive 账户已启用 API 访问权限。 如果满足这些要求，就可以将 AWS Glue 连接到 Pipedrive 账户。对于常见连接，无需在 Pipedrive 中执行其他操作。 # 配置 Pipedrive 连接 Pipedrive 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。 + 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序；在该应用程序中，除了 Pipedrive 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Pipedrive，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Pipedrive 实例。 + 用户可以选择在 Pipedrive 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Pipedrive，以便登录并授权 AWS Glue 访问其资源。 + 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期为一小时，可以通过刷新令牌在不需要用户互动的情况下自动刷新。 + 有关更多信息，请参阅[有关为 AUTHORIZATION\$1CODE OAuth 流创建关联应用程序的文档](https://developers.pipedrive.com/docs/api/v1/Oauth)。 要配置 Pipedrive 连接，请执行以下操作： 1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。 1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作为键。 1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接： 1. 在“数据连接”下，选择**创建连接**。 1. 选择**数据来源**时，请选择 Pipedrive。 1. 提供 Pipedrive **实例 URL**。 1. 选择 AWS Glue 可以担任并有权执行以下操作的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 提供要连接的 Pipedrive 的用户托管客户端应用程序 ClientId。 1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。 1. 如果要使用网络，请选择网络选项。 1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。选择**下一步**。 1. 提供 **connectionName**，然后选择**下一步**。 1. 在下一页上，选择**创建连接**。系统将要求您登录 Pipedrive。提供用户名和密码，然后选择**登录**。 1. 登录后，选择**继续使用应用程序**。连接现已就绪，随时可用。 1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。 # 从 Pipedrive 实体读取内容 **先决条件** + 要从中读取内容的 Pipedrive 对象。请参阅下面的支持的实体表，查看可用的实体。 **支持的实体** | 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 | | --- | --- | --- | --- | --- | --- | | 活动 | 支持 | 是 | 否 | 是 | 是 | | 活动类型 | 否 | 否 | 否 | 是 | 否 | | Call Logs | 否 | 否 | 否 | 是 | 否 | | Currencies | 支持 | 是 | 否 | 是 | 否 | | 交易 | 支持 | 是 | 是 | 是 | 是 | | 线索 | 支持 | 是 | 是 | 是 | 否 | | Lead Sources | 否 | 是 | 否 | 是 | 否 | | Lead Labels | 否 | 否 | 否 | 否 | 否 | | 备注 | 支持 | 是 | 是 | 是 | 是 | | 组织 | 支持 | 是 | 否 | 是 | 是 | | 权限集 | 是 | 否 | 否 | 是 | 否 | | 人员 | 支持 | 是 | 是 | 是 | 是 | | Pipelines | 否 | 是 | 否 | 是 | 否 | | 产品 | 支持 | 是 | 否 | 是 | 是 | | 角色 | 否 | 是 | 否 | 是 | 否 | | 阶段 | 支持 | 是 | 否 | 是 | 否 | | Users | 否 | 否 | 否 | 是 | 否 | **示例** ``` pipedrive_read= glueContext.create_dynamic_frame.from_options( connection_type="PIPEDRIVE", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "activites", "API_VERSION": "v1" } ``` **Pipedrive 实体和字段详细信息** 实体列表： + Activities：[ https://developers.pipedrive.com/docs/api/v1/Activities](https://developers.pipedrive.com/docs/api/v1/Activities) + Activity Type：[https://developers.pipedrive.com/docs/api/v1/ActivityTypes](https://developers.pipedrive.com/docs/api/v1/ActivityTypes) + Call Logs：[https://developers.pipedrive.com/docs/api/v1/CallLogs](https://developers.pipedrive.com/docs/api/v1/CallLogs) + Currencies：[https://developers.pipedrive.com/docs/api/v1/Currencies](https://developers.pipedrive.com/docs/api/v1/Currencies) + Deals：[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) + Lead Sources：[https://developers.pipedrive.com/docs/api/v1/LeadSources](https://developers.pipedrive.com/docs/api/v1/LeadSources) + Lead Labels：[https://developers.pipedrive.com/docs/api/v1/LeadLabels](https://developers.pipedrive.com/docs/api/v1/LeadLabels) + Notes：[https://developers.pipedrive.com/docs/api/v1/Notes](https://developers.pipedrive.com/docs/api/v1/Notes) + Organizations：[https://developers.pipedrive.com/docs/api/v1/Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations) + Permission Sets：[ https://developers.pipedrive.com/docs/api/v1/PermissionSets](https://developers.pipedrive.com/docs/api/v1/PermissionSets) + Persons：[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) + Products：[https://developers.pipedrive.com/docs/api/v1/Products](https://developers.pipedrive.com/docs/api/v1/Products) + Roles：[https://developers.pipedrive.com/docs/api/v1/Roles](https://developers.pipedrive.com/docs/api/v1/Roles) + Stages：[https://developers.pipedrive.com/docs/api/v1/Stages](https://developers.pipedrive.com/docs/api/v1/Stages) + Users：[https://developers.pipedrive.com/docs/api/v1/Users](https://developers.pipedrive.com/docs/api/v1/Users) | 实体 | 数据类型 | 支持的运算符 | | --- | --- | --- | | Activities、Deals、Notes、Organization、Persons 及 Products。 | 日期 | '=' | | | 整数 | '=' | | | 字符串 | '=' | | | 布尔值 | '=' | ## 对查询进行分区 在 Pipedrive 中，“Activities”实体中只有一个字段（due\$1date）支持基于字段的分区。即“Date”字段。 如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。 + `PARTITION_FIELD`：用于对查询进行分区的字段的名称。 + `LOWER_BOUND`：所选分区字段的包含下限值。 对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。 + `UPPER_BOUND`：所选分区字段的排除上限值。 + `NUM_PARTITIONS`：分区的数量。 **示例** ``` 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" } ``` # Pipedrive 连接选项参考 以下是 Pipedrive 的连接选项： + `ENTITY_NAME`（字符串）–（必填）用于读/写。Pipedrive 中对象的名称。 + `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Pipedrive Rest API 版本。示例：v1。 + `INSTANCE_URL`（字符串）：（必填）用户要在其中执行操作的实例的 URL。示例：v1。 + `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。 + `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。 + `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。 + `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。 + `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。 + `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。 + `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。 # 限制 以下是 Pipedrive 连接器的限制： + Pipedrive 仅支持对一个实体（Activities）基于字段的分区。 + Pipedrive 支持对 Activities、Deals、Notes、Persons、Organizations 和 Products 实体进行基于记录的分区。 + 在 Deals 实体中，如果筛选条件值使用了无效值，则状态字段作为筛选条件将返回所有记录。 + 在 Deals 实体中，不支持对多个字段排序。 + 要获得性能数据，需要使用本地 AWS 账户。然而，由于存在本地刷新访问令牌限制，处理 1 GB 数据的 AWS Glue 作业执行失败。因此，我们对 179 MB 数据的性能测试进行了优化，上述结果也基于此优化得出。但是我们观察到，随着分区越来越多，相较于单个分区，SaaS 端点所需的处理时间也更多。我们就此咨询了 Pipedrive 支持团队，他们表示，Pipedrive 会无提示地限制请求并延迟响应。因此，运行包含大型数据集的 AWS Glue 作业或多次调用相同 API 端点时，可能会由于 Pipedrive API 的实施而导致超时问题。但是，随着分区数量增加，连接器和 shim 的响应时间会按预期缩短。