# 连接到 Zoho CRM
Zoho CRM 作为单一存储库，将销售、营销和客户支持活动整合在一起，并在一个平台上简化流程、策略和人员。Zoho CRM 可以轻松定制，以满足任何企业类型和规模的特定需求。
Zoho CRM 的开发者平台为企业提供低代码和专业代码工具的适当组合，使工作自动化，跨企业堆栈整合数据，并创建 Web 版和移动版自定义解决方案。
**Topics**
+ [AWS Glue 对 Zoho CRM 的支持](zoho-crm-support.md)
+ [包含创建和使用连接的 API 操作的策略](zoho-crm-configuring-iam-permissions.md)
+ [配置 Zoho CRM](zoho-crm-configuring.md)
+ [配置 Zoho CRM 连接](zoho-crm-configuring-connections.md)
+ [从 Zoho CRM 实体中读取](zoho-crm-reading-from-entities.md)
+ [Zoho CRM 连接选项](zoho-crm-connection-options.md)
+ [Zoho CRM 连接器的限制和说明](zoho-crm-connector-limitations.md)
# AWS Glue 对 Zoho CRM 的支持
AWS Glue 对 Zoho CRM 的支持如下：
**是否支持作为来源？**
是，支持同步和异步。您可以使用 AWS Glue ETL 作业查询 Zoho CRM 中的数据。
**是否支持作为目标？**
不支持。
**支持的 Zoho CRM API 版本**
支持以下 Zoho CRM API 版本：
+ v7
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Zoho CRM
您必须满足以下要求，才能使用 AWS Glue 从 Zoho CRM 传输数据：
## 最低要求
以下是最低要求：
+ 您有一个 Zoho CRM 账户。
+ 您的 Zoho CRM 账户已启用 API 访问权限。
+ 您在 API 控制台下有一个注册的 API 客户端用于获取 OAuth 凭证。
# 配置 Zoho CRM 连接
授权类型决定了 AWS Glue 如何与 Zoho CRM 通信以请求访问您的数据。您选择的授权类型会影响您在创建连接之前必须满足的要求。Zoho CRM 仅支持 OAuth 2.0 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Zoho CRM，用户必须登录并向 Glue 授予所请求的权限，以访问其 Zoho CRM 实例。
+ 用户仍然可以选择在 Zoho CRM 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID、身份验证 URL、令牌 URL 和实例 URL。在这种情况下，他们仍会重定向到 Zoho CRM，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期为一小时，可以通过刷新令牌在不需要用户互动的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的公共 Zoho CRM 文档，请参阅 [Authentication](https://www.zoho.com/crm/developer/docs/api/v7/oauth-overview.html)。
要配置 Zoho CRM 连接：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Zoho CRM。
1. 提供您想要连接到的 Zoho CRM 实例的 `INSTANCE_URL`。
1. 提供用户客户端应用程序的客户端 ID。
1. 从下拉列表中选择相应的**身份验证 URL**。
1. 从下拉列表中选择相应的**令牌 URL**。
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` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Zoho CRM 实体中读取
**先决条件**
您要从中读取内容的 Zoho CRM 对象。您将需要对象名称。
**同步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 产品 | 支持 | 是 | 是 | 是 | 是 |
| 报价 | 支持 | 是 | 是 | 是 | 是 |
| 采购订单 | 支持 | 是 | 是 | 是 | 是 |
| 解决方案 | 支持 | 是 | 是 | 是 | 是 |
| Call | 支持 | 是 | 是 | 是 | 是 |
| 任务 | 支持 | 是 | 是 | 是 | 是 |
| 事件 | 支持 | 是 | 是 | 是 | 是 |
| 发票 | 支持 | 是 | 是 | 是 | 是 |
| Account | 支持 | 是 | 是 | 是 | 是 |
| 联系人 | 支持 | 是 | 是 | 是 | 是 |
| Vendor | 支持 | 是 | 是 | 是 | 是 |
| 活动 | 支持 | 是 | 是 | 是 | 是 |
| 交易 | 支持 | 是 | 是 | 是 | 是 |
| 线索 | 支持 | 是 | 是 | 是 | 是 |
| 自定义模块 | 支持 | 是 | 是 | 是 | 是 |
| 销售订单 | 支持 | 是 | 是 | 是 | 是 |
| 价目表 | 支持 | 是 | 是 | 是 | 是 |
| 案例 | 支持 | 是 | 是 | 是 | 是 |
**示例：**
```
zoho_read = glueContext.create_dynamic_frame.from_options(
connection_type="ZOHO",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v7",
"INSTANCE_URL": "https://www.zohoapis.in/"
}
```
**异步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 产品 | 是 | 否 | 否 | 是 | 否 |
| 报价 | 是 | 否 | 否 | 是 | 否 |
| 采购订单 | 是 | 否 | 否 | 是 | 否 |
| 解决方案 | 是 | 否 | 否 | 是 | 否 |
| Call | 是 | 否 | 否 | 是 | 否 |
| 任务 | 是 | 否 | 否 | 是 | 否 |
| 事件 | 是 | 否 | 否 | 是 | 否 |
| 发票 | 是 | 否 | 否 | 是 | 否 |
| Account | 是 | 否 | 否 | 是 | 否 |
| 联系人 | 是 | 否 | 否 | 是 | 否 |
| Vendor | 是 | 否 | 否 | 是 | 否 |
| 活动 | 是 | 否 | 否 | 是 | 否 |
| 交易 | 是 | 否 | 否 | 是 | 否 |
| 线索 | 是 | 否 | 否 | 是 | 否 |
| 自定义模块 | 是 | 否 | 否 | 是 | 否 |
| 销售订单 | 是 | 否 | 否 | 是 | 否 |
| 价目表 | 是 | 否 | 否 | 是 | 否 |
| 案例 | 是 | 否 | 否 | 是 | 否 |
**示例：**
```
zoho_read = glueContext.create_dynamic_frame.from_options(
connection_type="ZOHO",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v7",
"INSTANCE_URL": "https://www.zohoapis.in/",
"TRANSFER_MODE": "ASYNC"
}
```
**Zoho CRM 字段详细信息**：
Zoho CRM 提供用于动态获取所支持实体元数据的端点。因此，可在数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/zoho-crm-reading-from-entities.html)
## 对查询进行分区
异步模式下不支持分区。
**基于筛选条件的分区（同步模式）**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-09-30T01:01:01.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
zoho_read = glueContext.create_dynamic_frame.from_options(
connection_type="zohocrm",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v7",
"PARTITION_FIELD": "Created_Time"
"LOWER_BOUND": "2022-01-01T01:01:01.000Z"
"UPPER_BOUND": "2024-01-01T01:01:01.000Z"
"NUM_PARTITIONS": "10"
}
```
# Zoho CRM 连接选项
以下是 Zoho CRM 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Zoho CRM 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Zoho CRM Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 Zoho CRM 实例 URL。
+ `TRANSFER_MODE`（字符串）– 用于指示是否应在异步模式下运行查询。
# Zoho CRM 连接器的限制和说明
以下是 Zoho CRM 连接器的限制或说明：
+ 使用 API 版本 v7，您最多可以获取 100000 条记录。请参阅 [Zoho 文档](https://www.zoho.com/crm/developer/docs/api/v7/get-records.html)。
+ 对于事件实体，将显示“会议”标签，如 [Zoho 文档](https://www.zoho.com/crm/developer/docs/api/v7/modules-api.html)中所述。
+ 对于“全选”功能：
+ 您可以从 SaaS 中通过 GET 和 POST 调用来获取最多 50 个字段。
+ 如果您想要获取不属于前 50 个字段的某些特定字段的数据，则需要手动提供所选字段的列表。
+ 如果选择的字段超过 50 个，则超过 50 个字段的任何字段都将被修剪，并将在 Amazon S3 中包含空数据。
+ 使用筛选表达式时，如果用户提供的 50 个字段列表中不包括“id”和“Created\$1Time”，则会引发自定义异常，提示用户包含这些字段。
+ 尽管数据类型相同，但筛选运算符可能因字段而有所不同。因此，您必须为 SaaS 平台中触发错误的任何字段手动指定不同的运算符。
+ 对于“排序依据”功能：
+ 如果没有筛选表达式，则数据只能按单个字段进行排序；而应用筛选表达式后，数据可以按多个字段进行排序。
+ 如果没有为所选字段指定排序顺序，则默认情况下将按升序检索数据。
+ Zoho CRM 连接器的支持区域包括美国、欧洲、印度、澳大利亚和日本。
+ 异步读取功能[限制](https://www.zoho.com/crm/developer/docs/api/v7/bulk-read/limitations.html)：
+ 异步模式下不支持限制排序和分区。
+ 在异步模式下，我们可以传输多达 500 页的数据，每页 20 万条记录。
+ 在一分钟的间隔内，只允许 10 个下载请求。如果超过下载限制，系统会返回 HTTP 429 错误，并暂停所有下载请求一分钟，之后才能恢复处理。
+ 完成批量作业后，只能在一天内访问可下载的文件。之后则无法通过端点访问该文件。
+ 通过一个端点最多可以指定 200 个选择字段。如果在端点中指定超过 200 个选择字段，系统会自动导出该模块的所有可用字段。
+ 批量读取 API 不支持在任何模块中创建的外部字段。
+ 此 API 端点不支持排序和 `Group_by` 子句。
+ 仅当合规性设置中的**限制通过 API 访问数据**选项为**禁用**时，才会检索包含敏感运行状况数据的字段的值。如果启用该选项，则结果中的值将为**空**。
+ 过滤/条件限制
+ 查询中最多可以使用 25 个条件。
+ 不支持多行文本字段的筛选/条件。