本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 連線至 Kustomer Kustomer 是一個功能強大的客戶體驗平台，可將您更好地服務客戶所需的一切整合到一個易於使用的工具中。 **Topics** + [AWS Glue 支援 Kustomer](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) # AWS Glue 支援 Kustomer 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 金鑰給 。 如果您符合這些要求，就可以 AWS Glue 連線到您的 Kustomer 帳戶。 ## 建立 API 金鑰 若要建立 API 金鑰，您將用來在 AWS Glue Studio 中建立 Kustomer 連接器的連線： 1. 使用您的憑證登入 [Kustomer 儀表板](https://amazon-appflow.kustomerapp.com/login)。 1. 選擇左側功能表中的**設定**圖示。 1. 展開**安全性**下拉式功能表，然後選取 **API 金鑰**。 1. 在「API 金鑰」建立頁面中，從右上角選取**新增 API 金鑰**。 1. 填入要建立之 API 金鑰的必填輸入。 + 名稱：API 金鑰的任何名稱。 + 角色：必須選取 'org'，Kustomer API 才能運作。 + 過期 (以天為單位)：您希望 API 金鑰有效的天數。如果符合您的使用案例，可以將其保留為**永不過期**。 1. 選擇**建立**。 1. 存放 API 金鑰 （權杖） 值以供進一步使用，以在 AWS Glue Studio 中建立 Kustomer 連接器的連線。 # 設定 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. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 # 從 Kustomer 實體中讀取 **必要條件** 您要從中讀取的 Kustomer 物件。您將需要物件名稱，例如品牌或卡片。下表顯示支援的實體。 **來源的支援實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 品牌 | 否 | 是 | 否 | 是 | 否 | | 卡片 | 否 | 是 | 否 | 是 | 否 | | 聊天設定 | 否 | 否 | 否 | 是 | 否 | | 公司 | 是 | 是 | 是 | 是 | 是 | | 對話 | 是 | 是 | 是 | 是 | 是 | | 客戶 | 是 | 是 | 是 | 是 | 是 | | 客戶搜尋已鎖定 | 否 | 是 | 否 | 是 | 否 | | 客戶搜尋位置 | 否 | 否 | 否 | 是 | 否 | | 電子郵件勾點 | 否 | 是 | 否 | 是 | 否 | | Web 勾點 | 否 | 是 | 否 | 是 | 否 | | KB 文章 | 否 | 是 | 否 | 是 | 否 | | KB 類別 | 否 | 是 | 否 | 是 | 否 | | KB 表單 | 否 | 是 | 否 | 是 | 否 | | KB 路由 | 否 | 是 | 否 | 是 | 否 | | KB 標籤 | 否 | 是 | 否 | 是 | 否 | | KB 範本 | 否 | 是 | 否 | 是 | 否 | | KB 主題 | 否 | 是 | 否 | 是 | 否 | | Klasses | 否 | 是 | 否 | 是 | 否 | | KViews | 否 | 是 | 否 | 是 | 否 | | 訊息 | 是 | 是 | 是 | 是 | 是 | | 備註 | 是 | 是 | 是 | 是 | 是 | | 通知 | 否 | 是 | 否 | 是 | 否 | **範例**： ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "brands", "API_VERSION": "v1" } ``` ## Kustomer 實體和欄位詳細資訊 如需實體和欄位詳細資訊的更多資訊，請參閱： + [品牌](https://api.kustomerapp.com/v1/brands) + [卡片](https://api.kustomerapp.com/v1/cards) + [聊天設定](https://api.kustomerapp.com/v1/chat/settings) + [公司](https://api.kustomerapp.com/v1/companies) + [對話](https://api.kustomerapp.com/v1/conversations) + [客戶](https://api.kustomerapp.com/v1/customers) + [客戶搜尋已鎖定](https://api.kustomerapp.com/v1/customers/searches/pinned) + [客戶搜尋位置](https://api.kustomerapp.com/v1/customers/searches/positions) + [勾點電子郵件](https://api.kustomerapp.com/v1/hooks/email) + [勾點 Web](https://api.kustomerapp.com/v1/hooks/web) + [KB 文章](https://api.kustomerapp.com/v1/kb/articles) + [KB 類別](https://api.kustomerapp.com/v1/kb/categories) + [KB 表單]( https://api.kustomerapp.com/v1/kb/forms) + [KB 路由](https://api.kustomerapp.com/v1/kb/routes) + [KB 標籤](https://api.kustomerapp.com/v1/kb/tags) + [KB 範本](https://api.kustomerapp.com/v1/kb/templates) + [KB 主題](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) + [備註](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/zh_tw/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/zh_tw/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`(String) - (必要) 用於讀取。Kustomer 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。要使用的 Kustomer Rest API 版本。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 + `INSTANCE_URL`(String) - (必要) 用於讀取。Kustomer 執行個體 URL。 # Kustomer 限制 以下是 Kustomer 的限制或備註： + 不支援 `Customer Searches` 實體，因為 Kustomer API 文件尚未為其宣告任何端點。 + 不支援對 `Klasses` 實體進行篩選和增量傳輸。 + 單一請求中的多個適用欄位可支援排序依據。 不過，對於某些組合，已觀察到 SaaS 終端的多個欄位的排序依據功能行為不一致。其無法預測，因為有可能顯示不正確排序結果的 'n' 個組合。例如： 對於 `Customers` 實體，按 `progressiveStatus desc, name asc` 排序不會產生正確的排序結果。其只會根據 `progressiveStatus` 順序排序。如果發現此類行為，可以使用單一欄位進行排序。 + `Conversations` 和 `Messages` 實體僅支援欄位 'id' 的排序依據作為查詢參數。例如：https://api.kustomerapp.com/v1/conversations?sort=desc (這會以遞減順序按照 'id' 對結果進行排序。) 此外，任何其他欄位上的篩選條件或排序會轉換為將 API 端點作為 POST 的 POST 請求內文 https://api.kustomerapp.com/v1/customers/search 若要允許在 `Conversations` 和 `Messages` 中依 'id' 排序，應該只存在依 id 排序，或在任何其他適用欄位存在任何其他篩選條件和/或排序依據。 + 無論是已篩選還是未篩選的請求，Kustomer 允許擷取最多 10K 筆記錄。由於此限制，持有超過 10K 筆記錄的任何實體都會遺失資料。可以執行兩種可能的解決方法，以部分緩解此問題： + 套用篩選條件來擷取一組特定記錄。 + 如果已套用的篩選條件具有超過 10K 筆記錄，請在新的後續請求中套用連續篩選條件值，或在篩選條件中套用範圍。例如： 第一個請求的 filterExpression：`modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z` 假設這會耗盡 10K 筆記錄限制。 可以使用 filterExpression 觸發另一個請求：`modifiedAt >= 2023-03-15T05:26:23.000Z` + 作為 SaaS 行為，Kustomer 中的 `CONTAINS` 運算子僅支援對完整字詞進行比對，而不是對字詞進行部分比對。例如："body CONTAINS 'test record'" 將比對 'body' 欄位中具有 'test' 的記錄。不過，"body CONTAINS 'test'" 不會比對 'body' 欄位中具有 'testAnotherRecord' 的記錄。