本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 Zendesk
Zendesk 是以雲端為基礎的服務台管理解決方案，提供可自訂的工具來建置客戶服務入口網站、知識庫和線上社群。
**Topics**
+ [AWS Glue 支援 Zendesk](zendesk-support.md)
+ [包含用於建立和使用連線的 API 操作的政策](zendesk-configuring-iam-permissions.md)
+ [設定 Zendesk](zendesk-configuring.md)
+ [設定 Zendesk 連線](zendesk-configuring-connections.md)
+ [從 Zendesk 實體中讀取](zendesk-reading-from-entities.md)
+ [Zendesk 連線選項](zendesk-connection-options.md)
+ [限制](zendesk-limitations.md)
# AWS Glue 支援 Zendesk
AWS Glue 支援 Zendesk，如下所示：
**支援作為來源？**
是。您可以使用 AWS Glue ETL 任務從 Zendesk 查詢資料。
**支援作為目標？**
否。
**支援的 Zendesk API 版本**
支援下列 Zendesk API 版本
+ v2
# 包含用於建立和使用連線的 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 主控台的使用者。
# 設定 Zendesk
您必須先符合下列要求，才能使用 從 Zendesk AWS Glue 傳輸資料：
## 最低需求
以下是最低要求：
+ 您擁有一個 Zendesk 帳戶。如需詳細資訊，請參閱[建立 Zendesk 帳戶](#zendesk-configuring-creating-account)。
+ 您的 Zendesk 帳戶已啟用 API 存取。
+ 您的 Zendesk 帳戶可讓您安裝連線的應用程式。
如果您符合這些要求，就可以 AWS Glue 連線到 Zendesk 帳戶。
## 建立 Zendesk 帳戶
若要建立 Zendesk 帳戶：
1. 前往 https://www.zendesk.com/in/register/
1. 輸入詳細資訊，例如工作電子郵件、名字、姓氏、電話號碼、職稱、公司名稱、公司員工人數、密碼和偏好的語言。然後選擇**完成試用註冊**。
1. 建立帳戶後，請完成您收到的驗證連結，以驗證您的電子郵件地址。
1. 驗證工作電子郵件地址後，系統會將您重新導向至 Zendesk 帳戶。針對您偏好的計劃選擇**購買 Zendesk 選項**。注意：對於 Zendesk 連接器，建議購買 Suite Enterprise 計劃。
## 建立用戶端應用程式和 OAuth 2.0 憑證
若要建立用戶端應用程式和 OAuth 2.0 憑證：
1. 登入您要在其中建立 OAuth 2.0 應用程式的 Zendesk 帳戶 https://www.zendesk.com/in/login/
1. 按一下齒輪圖示。選擇**前往管理中心**連結以開啟管理中心頁面。
1. 在左側邊欄中選擇**應用程式和整合**，然後選取 **API** > **Zendesk API**。
1. 在 Zendesk API 頁面上，選擇 **OAuth 用戶端**索引標籤。
1. 選擇右側的**新增 Oauth 用戶端**。
1. 完成下列欄位以建立用戶端：
1. 用戶端名稱 - 輸入應用程式名稱。這是使用者在被要求授權應用程式存取權時，以及當他們檢查可存取其 Zendesk 的第三方應用程式清單時，將會看到的名稱。
1. 說明 - 選用。當使用者被要求為您的應用程式授予存取權時會看到的簡短說明。
1. 公司 - 選用。當使用者被要求為您的應用程式授予存取權時會看到的公司名稱。這些資訊可以協助他們了解授予存取權的對象。
1. 標誌 - 選用。這是使用者在被要求授予應用程式存取權時將會看到的標誌。影像格式可以是 JPG、GIF 或 PNG。為了獲得最佳結果，請上傳方形影像。其會針對授權頁面調整大小。
1. 唯一識別符 - 欄位會自動填入您為應用程式輸入之名稱的重新格式化版本。若您希望的話，可以變更。
1. 重新導向 URL - 輸入一個或多個 URL，Zendesk 應使用其來傳送使用者的決策，以授權您的應用程式。
例如：https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. 按一下 **Save (儲存)**。
1. 頁面重新整理後，下方會出現新的預先填入**機密**欄位。這是 OAuth2 規格中指定的 "client\$1secret" 值。將機密值複製到剪貼簿，並將其儲存在安全的地方。注意：字元可能會超出文字方塊的寬度，因此請務必在複製之前選取所有項目。
1. 按一下 **Save (儲存)**。
# 設定 Zendesk 連線
Zendesk 連接器支援授權碼授予類型。
+ 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。根據預設，建立連線的使用者可能會依賴 AWS Glue擁有的連線應用程式AWS Glue（受管用戶端應用程式），除了其 Zendesk 執行個體 URL 之外，不需要提供任何 OAuth 相關資訊。 AWS Glue 主控台會將使用者重新導向至 Zendesk，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 Zendesk 執行個體。
+ 您仍然可以選擇在 Zendesk 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，您仍會重新導向至 Zendesk 以登入並授權 AWS Glue 存取您的 資源。
+ 此授權類型會產生存取字符。存取字符永遠不會過期。
如需為授權碼 OAuth 流程建立連線應用程式的公有 Zendesk 文件，請參閱[授權類型的 OAuth 字符](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/)。
若要設定 Zendesk 連線：
1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密：
1. 對於 AuthorizationCode 授權類型：對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。
1. 注意：您必須在 AWS Glue中為每個連線建立機密。
1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線：
1. 選取**連線類型**時，請選取 Zendesk。
1. 提供您要連線之 Zendesk 的 INSTANCE\$1URL。
1. 提供 Zendesk 環境。
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`。
# 從 Zendesk 實體中讀取
**必要條件**
您要從中讀取的 Zendesk 物件。您將需要物件名稱，例如票證或使用者或文章，如下表所述。
| 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- |
| 票證 | Y | Y | Y | Y | N |
| 使用者 | Y | Y | Y | Y | N |
| 組織 | Y | Y | Y | Y | N |
| 文章 | Y | Y | N | Y | N |
| 票證事件 | Y | Y | N | Y | N |
| 票證指標事件 | Y | Y | N | Y | N |
| 票證評論 | Y | Y | Y | Y | N |
| 票證欄位 | Y | Y | N | Y | N |
| 票證指標 | Y | Y | N | Y | N |
| 票證活動 | Y | Y | N | Y | N |
| 略過票證 | N | Y | N | Y | N |
| Group | Y | Y | Y | Y | N |
| 群組成員資格 | N | Y | Y | Y | N |
| 滿意度評分 | Y | Y | N | Y | N |
| 檢視 | Y | Y | Y | Y | N |
| 觸發條件 | Y | Y | Y | Y | N |
| 觸發條件類別 | N | Y | Y | Y | N |
| 巨集 | Y | Y | Y | Y | N |
| 自動化 | N | Y | Y | Y | N |
**範例**：
```
Zendesk_read = glueContext.create_dynamic_frame.from_options(
connection_type="Zendesk",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v2"
}
```
**Zendesk 實體和欄位詳細資訊**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/zendesk-reading-from-entities.html)
**注意**
在連接器的回應中，Struct 和 List 資料類型會轉換為 String 資料類型。
## 分區查詢
Zendesk 不支援分區。
# Zendesk 連線選項
以下是 Zendesk 的連線選項：
+ `ENTITY_NAME`(String) - (必要) 用於讀取。Zendesk 中的物件名稱。
+ `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Zendesk Rest API 版本。例如：v2。
+ `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。例如：id、name、url、created\$1at
+ `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。例如：group\$1id = 100
+ `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。例如："SELECT id,url FROM users WHERE role=\$1"end-user\$1""
+ `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。預設欄位為 `update_at`，其適用於支援增量匯出 API 的實體 (`created_at` 適用於 `ticket-events`，`time` 適用於 `ticket-metric-events`)。
+ `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。
+ `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。選用；如果任務選項中未提供此選項，則連接器會處理此選項。預設值 - "2024-05-01T20:55:02.000Z
+ `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。選用；如果任務選項中未提供此選項，則連接器會處理此選項。預設值：1。
+ `IMPORT_DELETED_RECORDS`(String) - 預設：FALSE。用於讀取。在查詢時取得刪除記錄。
+ `ACCESS_TOKEN` - 要在請求中使用的存取字符。
+ `INSTANCE_URL` - 使用者想要執行操作的執行個體 URL。例如：https://\$1subdomain\$1/.zendesk.com
# 限制
以下是 Zendesk 連接器的限制：
+ 位移型分區會將可擷取的頁面數限制為 100，但不建議這樣做，因為可擷取的記錄總數為 10,000。不過，針對 Zendesk 連接器實作的游標型分區可克服此限制。Zendesk API 僅支援 EQUAL\$1TO 篩選條件運算子。
因此，Zendesk 連接器不支援分區。
+ 對於「票證事件」實體，「速率限制」為每分鐘 10 個請求。執行 AWS Glue ETL 任務時，您可能會收到 429 （太多請求） 錯誤。