# Kustomer への接続 Kustomer は、顧客により良いサービスを提供するために必要なすべてを 1 つの使いやすいツールにまとめた、強力なカスタマーエクスペリエンスプラットフォームです。 **Topics** + [Kustomer の AWS Glue サポート](kustomer-support.md) + [接続を作成および使用するための API オペレーションを含むポリシー](kustomer-configuring-iam-permissions.md) + [Kustomer の設定](kustomer-configuring.md) + [Kustomer 接続の設定](kustomer-configuring-connections.md) + [Kustomer エンティティからの読み取り](kustomer-reading-from-entities.md) + [Kustomer 接続のオプション](kustomer-connection-options.md) + [Kustomer の制限事項](kustomer-connection-limitations.md) # Kustomer の AWS Glue サポート AWS Glue は、次のように Kustomer をサポートしています。 **ソースとしてサポートされていますか?** はい。AWS Glue ETL ジョブを使用して、Kustomer からデータをクエリできます。 **ターゲットとしてサポートされていますか?** いいえ。 **サポートされている Kustomer API バージョン** 次の Kustomer API バージョンがサポートされています。 + v1 # 接続を作成および使用するための API オペレーションを含むポリシー 次のサンプル ポリシーで、接続の作成と使用に必要な AWS IAM 権限について説明します。新しいロールを作成する場合は、以下を含むポリシーを作成します。 ------ #### [ 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 コンソールのユーザーにアタッチされています。 # Kustomer の設定 AWS Glue を使用して Kustomer からサポートされている送信先にデータを転送できるようにするには、次の要件を満たす必要があります。 ## 最小要件 以下に、最小要件を示します。 + 転送するデータを含む Kustomer のアカウントがある。 + アカウントの設定で、API キーを作成している。詳細については、「[API キーの作成](#kustomer-configuring-creating-an-api-key)」を参照してください。 + 接続の作成時に AWS Glue に API キーを指定します。 これらの要件を満たすと、Kustomer アカウントに AWS Glue を接続する準備が整います。 ## API キーの作成 AWS Glue Studio で Kustomer コネクタ用の接続を作成するために使用する API キーを作成するには 1. [認証情報を使用して Kustomer ダッシュボード](https://amazon-appflow.kustomerapp.com/login)にログインします。 1. 左側のメニューから、**[Settings]** アイコンを選択します。 1. **[Security]** ドロップダウンを展開し、**[API Keys]** を選択します。 1. API キーの作成ページで、右上隅の **[Add an API Key]** を選択します。 1. 作成する API キーの必須項目を入力します。 + Name: API キーの任意の名前。 + Roles: Kustomer API が機能するには、「org」を選択する必要があります。 + Expires (in days): API キーを有効にする日数。ユースケースに応じて、**[Never expires]** にすることもできます。 1. **[作成]** を選択します。 1. Kustomer コネクタ用の接続を作成するための API キー (トークン) 値を今後の使用のために AWS Glue Studio に保存します。 # Kustomer 接続の設定 Kustomer 接続を設定するには 1. AWS Secrets Manager で、次の詳細を含むシークレットを作成します。 1. カスタマーマネージド接続アプリケーションの場合、シークレットには、`apiKey` を使用して接続されたアプリケーションのコンシューマーシークレットをキーとして含める必要があります。 1. 注: AWS Glue で接続にシークレットを作成する必要があります。 1. AWS Glue Glue Studio で、以下の手順に従って **[データ接続]** の下に接続を作成します。 1. **[接続]** で **[接続を作成]** を選択します。 1. **[データソース]** を選択するときは、[Kustomer] を選択します。 1. 次のアクションを実行でき、AWS Glue がその権限を持つ AWS IAM ロールを選択します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. AWS Glue でこの接続に使用する `secretName` を選択して、トークンを配置します。 1. ネットワークを使用する場合は、ネットワークオプションを選択します。 1. AWS Glue ジョブに関連付けられている IAM ロールに `secretName` を読み取るアクセス許可を付与します。 # Kustomer エンティティからの読み取り **前提条件** 読み取り元の Kustomer オブジェクト。Brands または Cards などのオブジェクト名が必要です。次の表に、サポートされているエンティティを示します。 **ソースに対応するエンティティ**: | エンティティ | フィルタリング可能 | 制限をサポートする | Order By をサポートする | Select \$1 をサポートする | パーティション分割をサポートする | | --- | --- | --- | --- | --- | --- | | Brands | なし | あり | なし | あり | なし | | [Cards] (カード) | なし | あり | なし | あり | なし | | Chat Settings | なし | なし | なし | あり | なし | | Companies | はい | あり | あり | あり | あり | | Conversations | はい | あり | あり | あり | あり | | Customers | はい | あり | あり | あり | あり | | Customer Searches Pinned | なし | あり | なし | あり | なし | | Customer Searches Position | なし | なし | なし | あり | なし | | Email Hooks | なし | あり | なし | あり | なし | | Web Hooks | なし | あり | なし | あり | なし | | KB Articles | なし | あり | なし | あり | なし | | KB Categories | なし | あり | なし | あり | なし | | KB Forms | なし | あり | なし | あり | なし | | KB Routes | なし | あり | なし | あり | なし | | KB Tags | なし | あり | なし | あり | なし | | KB Templates | なし | あり | なし | あり | なし | | KB Themes | なし | あり | なし | あり | なし | | Klasses | なし | あり | なし | あり | なし | | KViews | なし | あり | なし | あり | なし | | メッセージ | はい | あり | あり | あり | はい | | コメント | はい | あり | あり | あり | あり | | 通知 | なし | あり | なし | あり | なし | **例**: ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "brands", "API_VERSION": "v1" } ``` ## Kustomer のエンティティとフィールドの詳細 エンティティとフィールドの詳細については、以下を参照してください: + [Brands](https://api.kustomerapp.com/v1/brands) + [[Cards]](https://api.kustomerapp.com/v1/cards) (カード) + [Chat Settings](https://api.kustomerapp.com/v1/chat/settings) + [Companies](https://api.kustomerapp.com/v1/companies) + [Conversations](https://api.kustomerapp.com/v1/conversations) + [Customers](https://api.kustomerapp.com/v1/customers) + [Customers Searches Pinned](https://api.kustomerapp.com/v1/customers/searches/pinned) + [Customer Searches Positions](https://api.kustomerapp.com/v1/customers/searches/positions) + [Hooks Email](https://api.kustomerapp.com/v1/hooks/email) + [Hooks Web](https://api.kustomerapp.com/v1/hooks/web) + [KB Articles](https://api.kustomerapp.com/v1/kb/articles) + [KB Categories](https://api.kustomerapp.com/v1/kb/categories) + [KB Forms]( https://api.kustomerapp.com/v1/kb/forms) + [KB Routes](https://api.kustomerapp.com/v1/kb/routes) + [KB Tags](https://api.kustomerapp.com/v1/kb/tags) + [KB Templates](https://api.kustomerapp.com/v1/kb/templates) + [KB Themes](https://api.kustomerapp.com/v1/kb/themes) + [Klasses](https://api.kustomerapp.com/v1/klasses) + [Kviews](https://api.kustomerapp.com/v1/kviews) + [メッセージ](https://api.kustomerapp.com/v1/messages) + [Notes](https://api.kustomerapp.com/v1/notes) (メモ) + [通知](https://api.kustomerapp.com/v1/notifications) Kustomer API v1 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/kustomer-reading-from-entities.html) ## パーティショニングクエリ **フィールドベースのパーティション分割** Spark で同時実行を使用する場合は、追加の Spark オプション `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、および `NUM_PARTITIONS` を指定できます。これらのパラメータを使用すると、元のクエリは Spark タスクで同時に実行できるサブクエリの `NUM_PARTITIONS` の数に分割されます。 + `PARTITION_FIELD`: クエリのパーティション化に使用するフィールドの名前。 + `LOWER_BOUND`: 選択したパーティションフィールドの**包括的な**下限値。 DateTime フィールドでは、ISO 形式の値を受け入れます。 有効な値の例: ``` "2023-01-15T11:18:39.205Z" ``` + `UPPER_BOUND`: 選択したパーティションフィールドの**排他的**上限値。 + `NUM_PARTITIONS`: パーティション数。 エンティティごとのパーティション分割フィールドのサポートの詳細は、次の表にまとめられています。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/kustomer-reading-from-entities.html) 例: ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "conversation", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2023-01-15T11:18:39.205Z" "UPPER_BOUND": "2023-02-15T11:18:39.205Z" "NUM_PARTITIONS": "2" } ``` # Kustomer 接続のオプション Kustomer の接続オプションは次のとおりです。 + `ENTITY_NAME`(文字列) – (必須) 読み取りに使用されます。Kustomer のオブジェクトの名前。 + `API_VERSION`(文字列) – (必須) 読み取りに使用されます。使用する Kustomer Rest API バージョン。 + `SELECTED_FIELDS`(List) – Default: empty(SELECT \$1). 読み込みに使用されます。オブジェクトに選択する列です。 + `FILTER_PREDICATE`(文字列) – デフォルト: 空 読み込みに使用されます。Spark SQL 形式である必要があります。 + `QUERY`(文字列) - デフォルト: 空 読み込みに使用されます。完全な Spark SQL クエリです。 + `PARTITION_FIELD` (文字列) – 読み取りに使用されます。クエリをパーティション化するために使用するフィールドです。 + `LOWER_BOUND` (文字列)– 読み取りに使用されます。選択したパーティションフィールドの包括的な下限値。 + `UPPER_BOUND` (文字列) – 読み取りに使用されます。選択したパーティションフィールドの排他的上限値。 + `NUM_PARTITIONS`(整数) – デフォルト: 1。読み込みに使用されます。読み取り用のパーティションの数です。 + `INSTANCE_URL` (文字列) – (必須) 読み取りに使用されます。Kustomer インスタンス URL。 # Kustomer の制限事項 Kustomer の制限事項または注意事項は次のとおりです。 + Kustomer API ドキュメントではエンドポイントが宣言されていないため、`Customer Searches` エンティティはサポートされていません。 + `Klasses` エンティティでのフィルタリングと増分転送のサポートはありません。 + 並べ替えは、1 回のリクエストで複数の適用可能なフィールドで使用できます。 ただし、複数のフィールドでの並べ替え機能は、一部の組み合わせで SaaS エンドからの一貫性ない動作が確認されています。誤ったソート結果を示す「n」個の組み合わせが存在する可能性があるため、予測できません。例: `Customers` エンティティの場合、`progressiveStatus desc, name asc` による並べ替えでは正しいソート結果が得られません。`progressiveStatus` の順序に基づいてのみソートされます。このような動作が確認された場合は、単一のフィールドを使用して並べ替えができます。 + 「id」フィールドで並べ替えを行う場合は、クエリパラメータとして `Conversations` および `Messages` エンティティのみがサポートされます。例: https://api.kustomerapp.com/v1/conversations?sort=desc (これにより、結果が「id」で降順にソートされます)。 また、他のフィールドに対する他のフィルタリングまたは並べ替えは、API エンドポイントが POST https://api.kustomerapp.com/v1/customers/search として設定された POST リクエスト本文に変換されます。`Conversations` および `Messages` で「id」による並べ替えをサポートできるようにするには、id による並べ替えのみが存在するか、他のフィルタリングや並べ替えが他の適用可能なフィールドに存在する必要があります。 + Kustomer では、リクエストがフィルタリングされたかどうかに関係なく、最大 10,000 件のレコードを取得できます。この制限により、10,000 件を超えるレコードを保持するエンティティのデータが失われます。これを部分的に軽減するための回避策は 2 つあります。 + フィルターを適用して、特定のレコードセットを取得します。 + フィルター適用後のレコードが 10,000 件を超える場合は、新しい後続のリクエストに続きのフィルター値を適用するか、フィルターに範囲を適用します。例: 最初のリクエストの filterExpression: `modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z` これにより、10,000 件のレコードの制限が使い果たされると仮定します。 filterExpression を使用して別のリクエストをトリガーできます: `modifiedAt >= 2023-03-15T05:26:23.000Z` + SaaS の動作として、Kustomer の `CONTAINS` 演算子は完全な単語の一致のみをサポートし、単語内の部分一致はサポートしません。例えば、「body CONTAINS 'test record'」は「body」フィールドに「test」があるレコードと一致します。ただし、「body CONTAINS 'test'」は、「body」フィールドに「testAnotherRecord」があるレコードと一致しません。