本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 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
您必須先符合下列要求，才能使用 從 Zoho CRM AWS Glue 傳輸資料：
## 最低需求
以下是最低要求：
+ 您具有 Zoho CRM 帳戶。
+ 您的 Zoho CRM 帳戶已啟用 API 存取。
+ 您可以在 API 主控台下擁有已註冊的 API 用戶端，來取得 OAuth 憑證。
# 設定 Zoho CRM 連線
授予類型決定 如何與 Zoho CRM AWS Glue 通訊，以請求存取您的資料。您的選擇會影響您在建立連線之前必須滿足的要求。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 文件，請參閱[身分驗證](https://www.zoho.com/crm/developer/docs/api/v7/oauth-overview.html)。
若要設定 Zoho CRM 連線：
1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線：
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. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。
1. 如果想要使用您的網路，請選取網路選項。
1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。
1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。
# 從 Zoho CRM 實體中讀取
**必要條件**
您想要讀取的 Zoho CRM 物件。將需要物件名稱。
**同步來源支援的實體**
| 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- |
| 產品 | 是 | 是 | 是 | 是 | 是 |
| 報價 | 是 | 是 | 是 | 是 | 是 |
| 購買訂單 | 是 | 是 | 是 | 是 | 是 |
| 解決方案 | 是 | 是 | 是 | 是 | 是 |
| 呼叫 | 是 | 是 | 是 | 是 | 是 |
| 任務 | 是 | 是 | 是 | 是 | 是 |
| 事件 | 是 | 是 | 是 | 是 | 是 |
| 發票 | 是 | 是 | 是 | 是 | 是 |
| 帳戶 | 是 | 是 | 是 | 是 | 是 |
| 聯絡 | 是 | 是 | 是 | 是 | 是 |
| 廠商 | 是 | 是 | 是 | 是 | 是 |
| 行銷活動 | 是 | 是 | 是 | 是 | 是 |
| 交易 | 是 | 是 | 是 | 是 | 是 |
| 潛在客戶 | 是 | 是 | 是 | 是 | 是 |
| 自訂模組 | 是 | 是 | 是 | 是 | 是 |
| 銷售訂單 | 是 | 是 | 是 | 是 | 是 |
| 價目表 | 是 | 是 | 是 | 是 | 是 |
| 案例 | 是 | 是 | 是 | 是 | 是 |
**範例**：
```
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/"
}
```
**非同步來源支援的實體**：
| 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- |
| 產品 | 是 | 否 | 否 | 是 | 否 |
| 報價 | 是 | 否 | 否 | 是 | 否 |
| 購買訂單 | 是 | 否 | 否 | 是 | 否 |
| 解決方案 | 是 | 否 | 否 | 是 | 否 |
| 呼叫 | 是 | 否 | 否 | 是 | 否 |
| 任務 | 是 | 否 | 否 | 是 | 否 |
| 事件 | 是 | 否 | 否 | 是 | 否 |
| 發票 | 是 | 否 | 否 | 是 | 否 |
| 帳戶 | 是 | 否 | 否 | 是 | 否 |
| 聯絡 | 是 | 否 | 否 | 是 | 否 |
| 廠商 | 是 | 否 | 否 | 是 | 否 |
| 行銷活動 | 是 | 否 | 否 | 是 | 否 |
| 交易 | 是 | 否 | 否 | 是 | 否 |
| 潛在客戶 | 是 | 否 | 否 | 是 | 否 |
| 自訂模組 | 是 | 否 | 否 | 是 | 否 |
| 銷售訂單 | 是 | 否 | 否 | 是 | 否 |
| 價目表 | 是 | 否 | 否 | 是 | 否 |
| 案例 | 是 | 否 | 否 | 是 | 否 |
**範例**：
```
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_tw/glue/latest/dg/zoho-crm-reading-from-entities.html)
## 分區查詢
非同步模式中不支援分區。
**基於篩選條件的分區 (同步模式)**：
如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。
+ `PARTITION_FIELD`：用來分區查詢的欄位名稱。
+ `LOWER_BOUND`：所選分區欄位的**包含**下限值。
對於 Datetime 欄位，我們接受 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`(String) - (必要) 用於讀取。Zoho CRM 中的物件名稱。
+ `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Zoho CRM 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) - (必要) 用於讀取。有效的 Zoho CRM 執行個體 URL。
+ `TRANSFER_MODE`(String) - 用於指示是否應在非同步模式下執行查詢。
# Zoho CRM 連接器的限制和備註
以下是 Zoho CRM 連接器的限制或備註：
+ 使用 API 版本 v7，最多可以擷取 100,000 筆記錄。請參閱 [Zoho 文件](https://www.zoho.com/crm/developer/docs/api/v7/get-records.html)。
+ 對於 Event 實體，會顯示標籤 "Meeting"，如 [Zoho 文件](https://www.zoho.com/crm/developer/docs/api/v7/modules-api.html)所述。
+ 對於「選取所有功能」：
+ 對於 GET 和 POST 呼叫，最多可以從 SaaS 中擷取 50 個欄位。
+ 如果想要獲取不屬於前 50 個欄位的某些特定欄位的資料，則需要手動提供所選欄位的清單。
+ 如果選取超過 50 個欄位，則會修剪 50 個欄位以外的任何欄位，並在 Amazon S3 中包含 null 資料。
+ 如果是篩選條件表達式，若使用者提供的 50 個欄位清單不包含 "id" 和 "Created\$1Time"，則會引發自訂例外狀況，以提示使用者包含這些欄位。
+ 即使具有相同的資料類型，篩選條件運算子也可能因欄位而有所不同。因此，必須為 SaaS 平台中觸發錯誤的任何欄位手動指定不同的運算子。
+ 對於「排序依據」功能：
+ 如果沒有篩選條件表達式，則只能按單一欄位對資料進行排序，而當套用篩選條件表達式時，可以按多個欄位對資料進行排序。
+ 如果未指定所選欄位的排序順序，則預設會以遞增順序擷取資料。
+ 支援 Zoho CRM 連接器的區域為美國、歐洲、印度、澳洲和日本。
+ 非同步讀取功能[限制：](https://www.zoho.com/crm/developer/docs/api/v7/bulk-read/limitations.html)
+ 非同步模式中不支援限制排序依據和分區。
+ 在非同步模式中，我們最多可以傳輸 500 頁的資料，每頁 200,000 筆記錄。
+ 在一分鐘間隔內，僅允許下載 10 個請求。當超過下載限制時，系統會傳回 HTTP 429 錯誤，並將所有下載請求暫停一分鐘，然後才能繼續處理。
+ 完成大量任務後，只能在一天內存取可下載的檔案。之後，就無法透過端點存取檔案。
+ 透過端點最多可提供 200 個選取欄位。如果在端點中指定超過 200 個選取欄位，系統會自動匯出該模組的所有可用欄位。
+ Bulk Read API 不支援在任何模組中建立的外部欄位。
+ 透過此 API 端點不支援排序和 `Group_by` 子句。
+ 只有當合規設定中的**透過 API 限制資料存取**選項**停用**時，才會擷取具有敏感運作狀態資料的欄位值。如果啟用該選項，則結果中的值將為**空**。
+ 篩選/條件限制
+ 可在查詢中使用的條件數目上限為 25。
+ 不支援多行文字欄位的篩選/條件。