# Pipedrive への接続 Pipedrive は、小規模ビジネスがリードを管理し、営業活動を追跡し、より多くの取引を成立させるのに役立つように設計された販売パイプライン CRM です。Pipedrive を使用すると、小規模ビジネスの販売チームは、プロセスを合理化し、販売データを 1 つの統合された CRM 販売ツールに統合できます。Pipedrive ユーザーの場合は、Pipedrive アカウントに AWS Glue を接続できます。その後、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 アクセスが有効になっている。 これらの要件を満たすと、Pipedrive アカウントに AWS Glue を接続する準備が整います。一般的な接続では、Pipedrive で他に何もする必要はありません。 # Pipedrive 接続の設定 Pipedrive は、OAuth2 の AUTHORIZATION\$1CODE のグラントタイプをサポートしています。 + このグラントタイプは、ユーザーを認証するためにサードパーティーの認証サーバーにユーザーをリダイレクトすることから、「three-legged」の OAuth と見なされます。AWS Glue コンソール経由で接続を作成するときに使用されます。接続を作成するユーザーは、デフォルトで AWS Glue 所有の接続アプリケーションを使用できます。この場合、Pipedrive インスタンス URL 以外の OAuth 関連情報を指定する必要はありません。AWS Glue コンソールでは、ユーザーが Pipedrive にリダイレクトされます。ここではユーザーがログインし、Pipedrive インスタンスにアクセスするためのリクエストされた権限を AWS Glue に許可する必要があります。 + ユーザーは、Pipedrive で独自の接続アプリケーションを作成し、AWS Glue コンソールを介して接続を作成するときに独自のクライアント ID とクライアントシークレットを指定することを選択する必要があります。このシナリオでは、引き続き Pipedrive にリダイレクトされてログインし、リソースへアクセスするために AWS Glue を承認します。 + このグラントタイプは、更新トークンとアクセストークンになります。アクセストークンは 1 時間有効で、更新トークンを使用することでユーザーとやり取りすることなく自動的に更新できます。 + 詳細については、[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 の **[instanceURL]** を指定します。 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 オブジェクト。使用可能なエンティティを確認するには、以下のサポートされているエンティティの表を参照してください。 **サポートされているエンティティ** | エンティティ | フィルタリング可能 | 制限をサポートする | Order By をサポートする | Select \$1 をサポートする | パーティショニングをサポートする | | --- | --- | --- | --- | --- | --- | | アクティビティ | はい | あり | なし | あり | あり | | アクティビティタイプ | なし | なし | なし | あり | なし | | 通話ログ | なし | なし | なし | あり | なし | | 通貨 | はい | あり | なし | あり | なし | | Deals | はい | あり | あり | あり | あり | | リード | はい | あり | あり | あり | なし | | リードソース | なし | あり | なし | あり | なし | | リードラベル | なし | なし | なし | なし | なし | | コメント | はい | あり | あり | あり | あり | | 組織 | はい | あり | なし | あり | あり | | 許可セット | あり | なし | なし | あり | なし | | 人物 | はい | あり | あり | あり | あり | | Pipelines | なし | あり | なし | あり | なし | | 製品 | はい | あり | なし | あり | あり | | ロール | なし | あり | なし | あり | なし | | ステージ | はい | あり | なし | あり | なし | | [ユーザー] | なし | なし | なし | あり | なし | **例** ``` pipedrive_read= glueContext.create_dynamic_frame.from_options( connection_type="PIPEDRIVE", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "activites", "API_VERSION": "v1" } ``` **Pipedrive エンティティとフィールドの詳細** エンティティリスト: + アクティビティ:[ https://developers.pipedrive.com/docs/api/v1/Activities ](https://developers.pipedrive.com/docs/api/v1/Activities) + アクティビティタイプ:[ https://developers.pipedrive.com/docs/api/v1/ActivityTypes ](https://developers.pipedrive.com/docs/api/v1/ActivityTypes) + 通話ログ:[ https://developers.pipedrive.com/docs/api/v1/CallLogs ](https://developers.pipedrive.com/docs/api/v1/CallLogs) + 通貨:[ https://developers.pipedrive.com/docs/api/v1/Currencies ](https://developers.pipedrive.com/docs/api/v1/Currencies) + ディール:[ https://developers.pipedrive.com/docs/api/v1/Deals ](https://developers.pipedrive.com/docs/api/v1/Deals) + リード:[ https://developers.pipedrive.com/docs/api/v1/Leads ](https://developers.pipedrive.com/docs/api/v1/Leads) + リードソース:[ https://developers.pipedrive.com/docs/api/v1/LeadSources ](https://developers.pipedrive.com/docs/api/v1/LeadSources) + リードラベル:[ https://developers.pipedrive.com/docs/api/v1/LeadLabels ](https://developers.pipedrive.com/docs/api/v1/LeadLabels) + メモ:[ https://developers.pipedrive.com/docs/api/v1/Notes ](https://developers.pipedrive.com/docs/api/v1/Notes) + 組織:[ https://developers.pipedrive.com/docs/api/v1/Organizations ](https://developers.pipedrive.com/docs/api/v1/Organizations) + 許可セット:[ https://developers.pipedrive.com/docs/api/v1/PermissionSets ](https://developers.pipedrive.com/docs/api/v1/PermissionSets) + 個人:[ https://developers.pipedrive.com/docs/api/v1/Persons ](https://developers.pipedrive.com/docs/api/v1/Persons) + パイプライン:[ https://developers.pipedrive.com/docs/api/v1/Pipelines ](https://developers.pipedrive.com/docs/api/v1/Pipelines) + 製品:[ https://developers.pipedrive.com/docs/api/v1/Products ](https://developers.pipedrive.com/docs/api/v1/Products) + ロール:[ https://developers.pipedrive.com/docs/api/v1/Roles ](https://developers.pipedrive.com/docs/api/v1/Roles) + ステージ:[ https://developers.pipedrive.com/docs/api/v1/Stages ](https://developers.pipedrive.com/docs/api/v1/Stages) + ユーザー:[ https://developers.pipedrive.com/docs/api/v1/Users ](https://developers.pipedrive.com/docs/api/v1/Users) | エンティティ | データタイプ | サポートされている演算子 | | --- | --- | --- | | アクティビティ、ディール、メモ、組織、個人、製品。 | 日付 | '=' | | | 整数 | '=' | | | 文字列 | '=' | | | ブール値 | '=' | ## パーティショニングクエリ Pipedrive では、アクティビティエンティティの 1 つのフィールド (due\$1date) のみでフィールドベースのパーティショニングがサポートされています。それは日付フィールドです。 Spark で同時実行を使用する場合は、追加の Spark オプション `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、および `NUM_PARTITIONS` を指定できます。これらのパラメータを使用すると、元のクエリは Spark タスクで同時に実行できるサブクエリの `NUM_PARTITIONS` の数に分割されます。 + `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`(List) – Default: empty(SELECT \$1). 読み込みに使用されます。オブジェクトに選択する列です。 + `FILTER_PREDICATE`(文字列) – デフォルト: 空 読み込みに使用されます。Spark SQL 形式である必要があります。 + `QUERY`(文字列) - デフォルト: 空 読み込みに使用されます。完全な Spark SQL クエリです。 + `PARTITION_FIELD`(文字列) - 読み取りに使用されます。クエリをパーティション化するために使用するフィールドです。 + `LOWER_BOUND`(文字列) - 読み取りに使用されます。選択したパーティションフィールドの包括的な下限値。 + `UPPER_BOUND` (文字列) - 読み取りに使用されます。選択したパーティションフィールドの排他的上限値。 + `NUM_PARTITIONS`(整数) – デフォルト: 1。読み込みに使用されます。読み取り用のパーティションの数です。 # 制限 Pipedrive コネクタの制限は次のとおりです。 + Pipedrive は、1 つのエンティティ (アクティビティ) に対してのみフィールドベースのパーティショニングをサポートしています。 + Pipedrive は、アクティビティ、ディール、ノート、個人、組織、製品エンティティに対してレコードベースのパーティショニングをサポートしています。 + ディールエンティティで、無効な値フィルター値が使用されている場合、フィルターとしてのステータスフィールドはすべてのレコードを返します。 + ディールエンティティで、複数のフィールドを使用した順序付けはサポートされていません。 + パフォーマンスデータを取得するために、ローカル AWS アカウントを使用しています。しかし、アクセストークンをローカルで更新する制限により、1 GB のデータを処理する AWS Glue ジョブは失敗します。したがって、179 MB のデータでパフォーマンステストを最適化しており、上記の結果はこの最適化に基づいています。その場合でも、パーティションの数が増えると、SaaS エンドポイントは 1 つのパーティションと比較して時間がかかることがわかりました。この動作について Pipedrive サポートチームに相談したところ、Pipedrive はリクエストをサイレントにスロットリングし、レスポンスを遅延させているとのことでした。したがって、大規模なデータセットで AWS Glue ジョブを実行したり、同じ API エンドポイントを複数回呼び出したりすると、Pipedrive API の実装が原因でタイムアウトの問題が発生する可能性があります。ただし、コネクタとシムの応答時間は、パーティション数が増加すると期待どおりに減少します。