Zoho crm Logo

创建批量读取任务(批量导出)

目的

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。
  • queryJSON 对象,可选

    代表包含键和它们的值的 JSON 对象,这些键和值构成了批量导出的条件。以下是 JSON 对象中的键:

    • module(JSON 对象,必填)-
      代表你想要从中导出记录的模块的API名称。例如,Leads。如果你想要将事件模块中的记录导出为ICS文件,那么请将模块名称指定为 "Events"。
  • 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。下表显示了支持的比较器。

获取单一标准记录的示例输入

此查询基于指定的条件获取记录,"."(点)运算符用于从父模块获取数据。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"。

样本回应

注意

  • 单个导出任务中最多可以导出二十万条记录。即,页码应为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

    用户没有足够的权限进行阅读。
    解决方案:用户没有阅读记录的权限。请联系您的系统管理员。

样本回应