创建批量读取任务(批量导出)
目的
Bulk Read API用于创建批量读取作业以导出Zoho CRM的记录。这允许在不消耗标准API限制的情况下有效地检索大型数据集。
端点
- POST /read
Request 详细信息
Request URL
{api-domain}/crm/bulk/{version}/read
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
scope=ZohoCRM.bulk.read
(和)
scope=ZohoCRM.modules.{module_name}.{operation_type}
可能的模块名称
潜在客户,账户,联系人,交易,活动,任务,案例,事件,呼叫,解决方案,产品,供应商,价格书,报价,销售订单,采购订单,发票,以及自定义
可能的操作类型
ALL - 对记录的完全访问
READ - 获取批量读取任务
样本请求
Request JSON
- 回调JSON 对象,可选
这个 JSON 对象代表了批量读取任务的以下细节。
- url(字符串)-
一个有效的URL,应该允许 HTTP Post方法。批量读取任务的详细信息在任务成功完成或任务失败时发布到此URL。 - method(字符串)-
回调url的 HTTP 方法。支持的值是 post。
- url(字符串)-
- queryJSON 对象,可选
代表包含键和它们的值的 JSON 对象,这些键和值构成了批量导出的条件。以下是 JSON 对象中的键:
- module(JSON 对象,必填)-
代表你想要从中导出记录的模块的API名称。例如,Leads。如果你想要将事件模块中的记录导出为ICS文件,那么请将模块名称指定为 "Events"。
- module(JSON 对象,必填)-
- file_type(字符串,当你想将事件导出为ICS文件时必填)
如果从事件模块导出记录,将此设置为ics,以接收ICS文件,而不是CSV。
示例输入以获取模块中的所有记录
此查询以ICS格式获取Events模块中的所有记录。
使用"page_token"键获取下一组记录的示例输入
如果您的批量读取API调用中要导出的记录超过200,000条,请使用"page_token"键来获取下一组记录。您可以从第一次获取批量读取作业状态API的响应中的"next_page_token"键获取"page_token"键的值。
根据条件获取记录
在使用批量读取API时,您可以定义筛选条件来过滤和检索特定记录。以下是关键参数及其描述:
- cvid(字符串,必填) -
当您想要导出自定义视图中的记录时,代表自定义视图的唯一ID。您可以从自定义视图元数据API获取cvid。 - fields(JSON数组,可选) -
要导出的字段API名称列表(例如,"First_Name","Email","Owner.last_name")。注意:如果以ICS文件形式导出事件,不要包含此键。 - 页面(整数,可选) -
默认值为1,表示将导出与您的查询匹配的前200,000条记录。如果您想要获取范围在200,001到400,000的记录,那么请将值设为'2'。 - page_token(字符串,可选)
用于获取结果下一页的令牌。您可以使用"page"键来获取最多200,000条记录,而无需"page_token"。要获取超过200,000条记录,您必须在请求体中包含"page_token"键。此键从第一个获取批量读取作业状态API的响应中的"next_page_token"键获取值。- 注意:
- 此令牌值是用户特定的。如果您使用其他用户的令牌,系统将抛出错误。
- 页面令牌将最多保持活动状态24小时。
- 注意:
- criteria(JSON object, optional) -
Represents the details that the system uses to filter records. Example, the API Name of a module or field, comparators used to add two or more criteria, a group which the record/module/field belongs to etc. the following are the keys of this JSON object:- group_operator(字符串,如果未指定api_name、comparator和value,则必须) -
代表逻辑运算符。支持的值 - and,or。 - group(JSON 数组,如果未指定 api_name、comparator 和 value,则必须指定) -
代表标准对象的数组。每个标准对象中的键如下:- field(JSON 对象,如果未指定 group 和 group_operator,则必须指定)-
此 JSON 对象中的键代表要比较的字段的 API 名称。例如:First_Name、Last_Name、Owner.last_name 等。 - value(字符串/JSON 数组,如果未指定 group 和 group_operator,则必须指定)-
在此示例中,键作为 group JSON 数组的一部分给出。您也可以直接在标准 JSON 对象内指定它。键代表必须用来过滤记录的值。 - comparator(字符串,如果未指定 group 和 group_operator,则必须指定.)-
在此示例中,键作为 group JSON 数组的一部分给出。您也可以直接在 criteria JSON 对象内指定它。键代表比较器。例如:equal、greater_than。下表显示了支持的比较器。
- field(JSON 对象,如果未指定 group 和 group_operator,则必须指定)-
- group_operator(字符串,如果未指定api_name、comparator和value,则必须) -
获取单一标准记录的示例输入
此查询基于指定的条件获取记录,"."(点)运算符用于从父模块获取数据。Account_Name是Contacts模块中的默认查找字段。在这里,Owner.last_name返回联系人所有者的姓氏,Account_Name返回ID,Account_Name.Account_Name返回与联系人关联的账户的名称,Account_Name.Phone返回与联系人关联的账户的电话号码。
允许的比较器
| 数据类型 | 比较器 | 值和限制 |
|---|---|---|
| 数字(整数)/小数/大整数/货币/百分比 | 等于,不等于,包含,不包含,小于,小于等于,大于,大于等于 | 任何数字值或${EMPTY}表示空值。大整数不超过19位,小数和货币字段的值为小数。在启用多货币的账户中,只支持主货币值。 |
| 文本(电子邮件,电话,URL,下拉列表,多选等) | 等于,不等于,包含,不包含,包含,不包含,以...开始,以...结束 | 任何文本值或${EMPTY}表示空值。字符数不超过255个。 |
| 日期和日期时间 | 等于,不等于,包含,不包含,介于...之间,不在...之间,大于,大于等于,小于,小于等于 | 任何符合ISO 8601格式的日期值或${EMPTY}表示空值。对于日期时间字段,不支持毫秒。 |
| 布尔值 | 等于 | 真或假。 |
| 查找 | 等于,不等于,包含,不包含 | 查找的大整数值,${EMPTY}表示空值,或使用.(点)运算符建立两个模块之间的关系。例如:"Owner"获取所有者的ID,而"Owner.last_name"获取所有者的姓。"Account_Name"获取与基础模块关联的账户的ID,而"Account_Name.Phone"获取与基础模块关联的账户的电话号码。 |
获取具有多个条件和CVID的记录的示例输入
Response 结构
- 状态字符串
指定API调用的状态。示例 - "状态": "成功"。
- 消息字符串
指定工作的预定义评论。在出现任何错误的情况下很有用。示例 - "message": "成功添加。"
- 详情JSON 对象
包含批量读取作业的以下详细信息。
- operation(字符串)-
指定API完成的操作类型。示例 - "operation" : "read”。 - created_by(JSON 对象)-
指定启动批量读取作业的用户的ID和名称。示例 - "created_by": { "id": "1000000031045", "name": "Patricia Boyle" }。 - created_time (字符串)-
指定批量读取作业的创建时间。 - state(字符串)-
指定批量读取作业的当前状态。示例:"state": "ADDED" 或 "IN PROGRESS" 或 "COMPLETED"。 - id(字符串)-
指定批量读取作业的唯一标识符。使用此ID检查作业状态并下载结果。示例 - "id": "1000010760002"。
- operation(字符串)-
样本回应
注意
- 单个导出任务中最多可以导出二十万条记录。即,页码应为1,该页中的记录数应为200,000。要了解更多关于批量API限制的信息,请参阅限制文档。
- 如果页面的值为1,则将按条件匹配的前200,000条记录用于导出。
- 要从父模块获取数据,请使用"."(点)运算符。例如,联系人模块有默认的Account_Name查找字段。要获取联系人关联的账户的名称,请使用Contacts.Account_Name.Account_Name。
- 仅在输入中使用字段和模块的API名称。
- 如果查询中的字段属性JSON留空,则在CSV文件中列出了相应基础模块的所有可用字段。如果您只需要特定字段,请指定用于导出的字段API名称。
- Bulk Read API在请求模块的所有字段时,响应中的字段不遵循任何特定顺序。然而,如果你使用字段JSON数组指定一组字段,响应将保持与提供的顺序相同。
- 如果您想要导出自定义视图下的记录,必须指定cvid。
- 除了cvid,您还可以指定其他条件。这些条件将附加到自定义/标准视图的现有条件中。
关于ICS文件类型
- 仅支持在会议模块中以ICS格式导出记录。
- 您每批次最多可以从会议模块导出20,000 条记录。
- 当您想将会议导出为ICS文件时,不支持fields属性。
- 如果您没有指定file_type为ics,那么默认情况下,记录将以CSV格式导出。
- 如果在获取作业详情API调用的响应中,more_records的值为true,则表示还有更多记录需要获取。
工作完成的回调示例
作业失败的示例回调
批量导出子表单记录
要从模块中导出CSV格式的子表单记录,请使用相应子表单的模块API名称。请参考Kaizen #124 - 使用Zoho CRM操作子表单了解更多关于使用批量读取API的子表单的详细信息。
导出子表单记录的示例输入
导出满足指定条件的子表单记录
导出满足特定父记录指定条件的子表单记录
批量导出多选查找(MxN)数据
要导出MxN记录,请使用相应链接模块的API名称。有关使用批量读取API导出多选查找数据的更多详细信息,请参考Kaizen #125 - 使用Zoho CRM APIs操作多选查找字段。
导出链接模块记录的样本输入
可能的错误
- MEDIA_TYPE_NOT_SUPPORTEDHTTP 415
不支持的媒体类型。
解决方案:您没有在请求中传递'Content-Type'头。 - INVALID_URL_PATTERNHTTP 404
请检查尝试访问的URL是否正确
解决方案:指定的请求URL不正确。请指定一个有效的请求URL。请参考上面的请求URL部分。 - OAUTH_SCOPE_MISMATCHHTTP 401
未经授权
解决方案:客户端没有ZohoCRM.bulk.read或ZohoCRM.modules.{module_name}.READ。创建具有有效范围的新客户端。请参考上面的范围部分。 - NO_PERMISSIONHTTP 403
读取权限被拒绝
解决方案:用户没有读取记录的权限。请联系您的系统管理员。 - INTERNAL_ERRORHTTP 500
内部服务器错误
解决方案:服务器中出现意外且未处理的异常。请联系支持团队。 - INVALID_REQUEST_METHODHTTP 400
HTTP请求方法类型无效
解决方案:您指定了无效的HTTP方法来访问API URL。请指定一个有效的请求方法。请参考上述端点部分。 - AUTHORIZATION_FAILEDHTTP 400
用户没有足够的权限进行阅读。
解决方案:用户没有阅读记录的权限。请联系您的系统管理员。