Zoho crm Logo

批量更新记录

批量更新功能允许您更新模块中多个记录在区域或自定义视图中特定字段的值。当您想要为模块、区域或自定义视图中的所有记录更新相同字段时,此API非常有用。

在此 API 中,输入包含您要更新其值的字段的 API 名称以及记录 ID、CVID(自定义视图 ID)或领地 ID。
您可以使用此 API 更新最多 50,000 条记录。

记录的批量更新有两种方式:

  • 调度器类型:当您指定自定义视图ID和区域ID时,系统会在后台调度一个作业,并返回一个“job_id”。使用此job_id在获取批量UpdateStatusAPI中获取作业的Status。在这种类型中,您最多可以Update50,000条记录。
  • 非调度类型:当您指定记录ID时,系统会立即更新记录。在这种类型的大规模更新中,您可以在单个API调用中最多更新500条记录。

批量Update记录

目的

安排批量更新记录。

端点

  • POST /{module_API_name}/actions/mass_update

请求详情

请求 URL

{api-domain}/crm/{version}/{module_API_name}/actions/mass_update

支持的模块

潜在客户,Account,联系人,交易,活动,任务,电话,会议,解决方案,产品,Vendors,价格表,报价,Sales Orders,采购Orders,Invoices,以及自定义

标题

授权: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

ZohoCRM.mass_update.UPDATE
(或)
ZohoCRM.mass_update.{module_name}.UPDATE

可能的模块名称

线索、账户、联系人、交易、活动、任务、电话、会议、解决方案、产品、供应商、价格表、报价单、销售订单、采购订单、发票和自定义

示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/Accounts/actions/mass_update"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POST
CopiedrecordIDList = List();
recordIDList.add("692969000000416006");
recordIDList.add("692969000000287129");
recordIDList.add("692969000000287038");


input1 = Map();
input1.put("Lead_Source", "Advertisement");

inputList = List();
inputList.add(input1);

params = Map();
params.put("data", inputList);
params.put("over_write", true);
params.put("ids", recordIDList);

response = invokeurl
[
	url :"https://www.zohoapis.com/crm/v8/Deals/actions/mass_update"
	type :POST
	parameters: params.toString()
	connection:"crm_oauth_connection"
];
info response;

在请求中,"@input.json" 包含示例输入数据。

请求 JSON 键

  • cvid字符串,当自定义视图字段或区域字段被更新时是必填项

    要批量更新其记录的自定义视图ID。

    注意

    cvid键在以下版本中支持通过API进行批量更新:

    • 企业版
    • 终极版
    • CRM Plus
    • Zoho One 企业版
  • over_writeboolean, optional

    用于更新多选下拉列表字段。
    可能的值:

    • false: 将指定的值添加到下拉列表中。默认值为 false。
    • true: 用指定的值替换所有多选下拉列表的值进行批量更新。
  • territoryJSON 对象,当更新领土字段时是必需的

    用于更新该领土中的记录。
    可能的键 : 

    • include_child (boolean): 布尔字段,指示是否也要批量更新子领土记录。默认值为 false。
    • id (string): 要在该领土中更新记录的领土 ID。
  • idsJSON 数组,强制要求,当通过ID更新记录时

    指定要批量更新的记录的ID。

注意

  • 调度器类型(使用记录ID):
    • 在单个API调用中,您最多可以批量更新50,000条记录。
    • 当记录数少于1000时,自动化规则会自动触发。当记录数大于1000时,自动化规则不会被触发。
    • 如果某些记录包含无效数据,则只有这些记录不会在API调用中被处理。
  • 非调度器类型(使用CVID和领地ID):
    • 在单个API调用中,您最多可以批量更新500条记录。
    • 自动化规则如审批、蓝图和工作流会自动触发。
    • 当您想要在一个领地中批量更新记录时,必须指定自定义视图ID。
  • 您不能批量更新Email、查找字段、布局字段、多行字段和行项目。
  • 在单个API调用中,您可以在交易模块中批量更新最多三个字段,在所有其他模块中只能批量更新一个字段。

示例输入

CopiedWith cvid and Territory ID
{
    "data": [
        {
            "Industry": "Education"//field to be updated
        }
    ],
    "cvid": "554023000000091515", //custom view ID to mass update records in that custom view
    "territory": {
        "id": "554023000000430409",//ID of the territory to mass update records in that territory
        "include_child": true //include child territory records for mass updation
    }
}

With Record IDs in the Input 
{
    "data": [
        {
            "Lead_Source": "Advertisement",
            "Type": "Existing Business",
            "Languages_Known": [
                "English",
                "Spanish"
            ]
        }
    ],
    "over_write": true,
    "ids": [
        "554023000000497007",
        "554023000000497021"
    ]
}

在包含记录ID的示例输入中,“Languages_Known”是交易模块中的自定义多选列表。

Response JSON Keys

  • codestring

    指示批量更新的状态。

  • detailsJSON object

    指定“job_id”(用于调度器类型)、修改时间以及修改记录的用户的姓名和ID(用于非调度器类型)。

  • created_timeISO8601格式的日期和时间

    指定记录创建的时间段。

  • idstring

    指定已更新记录的ID。

  • Created_ByJSON object

    指定创建记录的用户的姓名和ID。

  • messagestring

    指定记录是否已更新或错误原因(如果有)。

  • statusstring

    指定记录的状态,如已更新、错误等。

Possible Errors

  • ALREADY_SCHEDULEDHTTP 202

    已经有一个批量操作调度程序正在为给定的自定义视图ID运行。
    解决方案:等待调度程序完成或为另一组记录安排另一个任务。

  • INVALID_DATAHTTP 400

    您没有提供请求主体。
    解决方案:请参阅请求JSON键部分以获取输入键列表。

  • INVALID_DATAHTTP 400

    要批量更新的字段数量已超过该模块允许的限制。
    解决方案:您可以在交易模块中最多批量更新三个字段,在其他模块中只能批量更新一个字段。

  • INVALID_DATAHTTP 400

    指定的字段在模块中未找到,或者不允许进行批量更新。
    解决方案:请联系您的系统管理员。

  • INVALID_DATAHTTP 400

    指定的字段在布局规则中用作主字段或与验证规则相关联。
    解决方案:您不能批量更新与布局规则或验证规则相关联的主字段。

  • INVALID_DATAHTTP 400

    指定的字段不可见或您无权访问。
    解决方案:请联系您的系统管理员。

  • INVALID_DATAHTTP 400

    指定的记录ID、CVID或区域ID无效。
    解决方案:在输入中指定有效的ID。

  • INVALID_DATAHTTP 400

    在非调度程序类型请求中,一个或多个记录ID无效。有效的记录ID会被更新,无效的ID会抛出错误。
    解决方案:在输入中指定有效的记录ID。

  • INVALID_REQUEST_METHOD HTTP 400

    请求方法不正确。
    解决方法:使用 HTTP POST 方法来进行此 API 调用。任何其他请求方法都会导致此错误。

  • AUTHORIZATION_FAILED HTTP 400

    您没有足够的权限来批量更新记录。
    解决方案:请联系您的系统管理员。

  • RECORD_LOCKED HTTP 400

    您无法更新尚未批准的记录。
    解决方案:请等待Zia图像、合并重复项或其他审批过程完成后再试。

  • RECORD_LOCKED HTTP 400

    由于记录被锁定,您无法进行批量更新。
    解决方案:请等待记录解锁。

  • NOT_APPROVED HTTP 400

    您无法更新记录,因为它尚未获得批准。
    解决方案:

    • 情况 1:如果记录因 Zia 图像验证被拒绝,请上传新图像(或)删除失败的图像,并重新提交记录进行 Zia 图像验证。
    • 情况 2:如果记录处于 Zia 记录审批中,系统将不允许您更新记录的图像,直到审核员批准或拒绝记录。
  • CANNOT_PROCESSHTTP 400

    记录已停止处理。
    解决方法:联系您的系统管理员。

  • RECORD_IN_BLUEPRINTHTTP 400

    记录在蓝图中。
    解决方案:等待记录完成所有蓝图转换后再更新。

  • MANDATORY_NOT_FOUNDHTTP 400

    您未指定 CVID 或记录 ID。
    解决方法:您必须在输入主体中指定 CVID 或记录 ID。

  • CANNOT_PERFORM_ACTIONHTTP 400

    您没有权限对该记录执行任何操作。
    解决方案:请联系您的系统管理员。

  • LIMIT_EXCEEDEDHTTP 400

    可以批量更新的记录数量已超过允许的最大限制50000条。
    解决方案:为另一组记录安排另一个批量更新任务。

  • NOT_APPROVEDHTTP 400

    指定ID的记录未被批准。
    解决方法:等待记录被批准或联系系统管理员。

  • NO_RECORDS_FOUNDHTTP 400

    在指定的自定义视图中没有记录。

  • INVALID_MODULEHTTP 400

    您指定了无效的模块 API 名称,或者没有标签权限,或者该模块已从可用模块列表中移除。
    解决方法:使用模块 API获取模块的 API 名称。如果您没有标签权限或模块已被移除,请联系您的系统管理员。

  • OAUTH_SCOPE_MISMATCH HTTP 401

    您用于进行此 API 调用的访问令牌不具有所需的范围。
    解决方案:生成一个具有范围部分中提到的范围的新访问令牌。

  • NO_PERMISSIONHTTP 403

    您没有权限编辑该字段,或者没有访问自定义视图的权限。
    解决方案:请联系您的系统管理员。

  • INVALID_URL_PATTERN HTTP 404

    请求的URL不正确。
    解决方法:请指定一个有效的请求URL。请参阅请求URL部分以获取正确的URL。

  • INTERNAL_ERROR HTTP 500

    服务器中出现意外且未处理的异常。 
    解决方案:请联系支持团队,邮箱地址为 support@zohocrm.com。

示例响应

CopiedResponse for scheduler type
{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "job_id": "554023000000506003"
            },
            "message": "mass update scheduled successfully",
            "status": "success"
        }
    ]
}

Response for non-scheduler type (with record IDs)
{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "Modified_Time": "2021-03-03T12:17:00+05:30",
                "Modified_By": {
                    "name": "Patricia boyle",
                    "id": "554023000000497007"
                },
                "Created_Time": "2021-02-26T19:13:56+05:30",
                "id": "580845000003654076",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "580845000000242009"
                }
            },
            "message": "record updated",
            "status": "success"
        },
        {
            "code": "INVALID_DATA",
            "details": {
                "id": "554023000000497021"
            },
            "message": "the id given seems to be invalid",
            "status": "error"
        }
    ]
}