# 连接到 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
您必须满足以下要求，才能使用 AWS Glue 从 Zendesk 传出数据：
## 最低要求
以下是最低要求：
+ 拥有一个 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. 单击**保存**。
1. 该页面刷新后，下半部会出现一个新的预填充**密钥**字段。这是 OAuth2 规范中指定的“client\$1secret”值。将密钥的值复制到剪贴板并将妥善保管。注意：字符可能会超出文本框的宽度，因此在复制之前请务必选择所有内容。
1. 单击**保存**。
# 配置 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 Tokens for Grant Types](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/)。
要配置 Zendesk 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于 AuthorizationCode 授权类型：如果是客户托管的关联应用程序，密钥应包含关联应用程序的 Consumer Secret，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键名。
1. 注意：您必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Zendesk 实体中读取
**先决条件**
您要从中读取内容的 Zendesk 对象。您将需要工单、用户或文章等对象名称，如下表中所述。
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$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 |
| 组 | 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_cn/glue/latest/dg/zendesk-reading-from-entities.html)
**注意**
在连接器的响应中，结构和列表数据类型将转换为字符串数据类型。
## 对查询进行分区
Zendesk 中不支持分区。
# Zendesk 连接选项
Zendesk 的连接选项如下：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Zendesk 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Zendesk Rest API 版本。示例：v2。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。示例：id、name、url、created\$1at
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。例如：group\$1id = 100
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。示例："SELECT id,url FROM users WHERE role=\$1"end-user\$1""
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。支持增量导出 API 的实体，默认字段为 `update_at`（`ticket-events` 的 `created_at`，以及 `ticket-metric-events` 的 `time`）。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。可选；如果作业选项中未提供，则连接器将处理此选项。默认值：“2024-05-01T20:55:02.000Z
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。可选；如果作业选项中未提供，则连接器将处理此选项。默认值：1。
+ `IMPORT_DELETED_RECORDS`（字符串）– 默认：FALSE。用于读取。在查询时获取删除记录。
+ `ACCESS_TOKEN`：要在请求中使用的访问令牌。
+ `INSTANCE_URL`：用户要在其中运行操作的实例的 URL。例如：https://\$1subdomain\$1/.zendesk.com
# 限制
以下是 Zendesk 连接器的限制：
+ 对于基于偏移量的分页，可提取的页数上限为 100，但不建议这样做，因为可以提取的记录总数为 10,000。但是，为 Zendesk 连接器实现的基于游标的分页克服了这一限制。仅支持通过 Zendesk API 使用 EQUAL\$1TO 筛选条件运算符。
由于这一限制，Zendesk 连接器不支持分区。
+ 对于“Ticket Event”实体，速率限制为每分钟 10 个请求。运行 AWS Glue ETL 作业时，您可能会收到 429 错误（请求过多）。