创建批量写作任务
目的
创建一个批量写入作业,以将记录导入到CRM中。
端点
- POST /write
Request 详情
Request URL
{api-domain}/crm/bulk/{version}/write
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
scope=ZohoCRM.bulk.CREATE
(或)
scope=ZohoCRM.bulk.ALL
(和)
scope=ZohoCRM.modules.ALL
(或)
scope=ZohoCRM.modules.{module_name}.{operation_type}
可能的模块名称
潜在客户,账户,联系人,交易,活动,案例,解决方案,产品,供应商,价格手册,任务,报价,销售订单,采购订单,发票,以及自定义
可能的操作类型
ALL - 对记录的完全访问
CREATE - 创建批量写入任务
样本请求
Request JSON
- character_encoding字符串,可选
表示上传文件的字符集。通常会自动检测,但如果指定,则将用于读取文件。
- operation字符串,必填
表示您想要在批量写入作业上执行的操作类型。
值包括
- insert - 用于在CRM中创建CSV新记录。
- update - 用于更新CRM中的现有记录(此操作不允许创建新记录)。
- upsert - 用于更新CRM中的现有记录,并创建新记录,如果它们尚不存在。
- ignore_empty布尔值,可选
True - 忽略列中的空值,并仅更新记录中没有空值的字段
False或空 - 系统会使用给定文件列中的空值更新CRM中的记录。
默认值是false。 - callbackJSON 对象,可选
一个有效的URL,允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。示例 - "callback" : { "url": "HTTPs://sampledomain.com/getzohoresponse", "method": "POST" }。
这个JSON对象接受两个键——url和method。- url(字符串) - 一个有效的URL,应允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。
- method(字符串) - 回调url的HTTP方法。支持的值是POST。
- 资源JSON 数组,必须的
一个JSON数组,包含您想要导入的模块的API名称,它们的字段映射,以及从上传API获取的相应文件ID。
- type(字符串,必填) - 表示您想要导入的模块类型。其值为data。
- 模块(JSON 对象,必填) - 你为批量写入任务选择的模块的API名称。
对于子表单:当你想要批量写入子表单数据时,你必须在这里给出子表单的API名称。 - file_id(字符串,必填) - 从文件上传API获取的file_id。
- find_by(字符串,更新和upsert操作必须,插入操作可选) - 唯一字段或记录ID的API名称。系统使用此字段的值在CRM中查找现有记录。在插入操作中,如果提供了find_by,系统将从文件中跳过重复的记录。
field_mappings(JSON 数组,可选) - 当系统处理 CSV 文件时,第一行被视为标题行。每个标题名称都被视为字段API名称,列中的数据被填充到由API名称表示的相应字段中。此参数可帮助您跳过自动映射并定义自己的字段映射。
注意:
- 默认情况下,字段映射是自动处理的。如果你想定义自己的,你可以手动映射字段。
- 如果你在输入中包含这个数组,CSV 中的数据将仅根据此数组中的索引值进行映射。
- api_name(字符串,必填) - 您想要导入的Zoho模块对象中字段的API名称。请参考字段元数据API以获取模块中可用的字段列表。无效的字段API名称会抛出错误。
- index(数字,可选) - 您想要映射到CRM字段的字段的列索引。当您指定一个不存在的索引值时,系统会抛出一个错误。
- find_by(字符串,查找字段必填) - 模块中唯一字段的API名称,系统会根据此字段检查CRM中是否存在现有记录。您也可以使用id,系统定义的唯一字段的API名称,自定义唯一字段,查找字段,基于组织的外部ID,以及显示列/字段(基于字段显示的结果,当您搜索关联查找时列出。例如,当您在联系人中查找指向账户的查找时,账户名称就是显示列。)作为find_by字段。
- default_value(JSON 对象,可选) - 如果某些记录在某列中没有值,你想用默认值替换它,可以使用此键。例如:{"value": "Trade Show"}。以下字段在 default_value 键中不受支持:多行,唯一字段,和显示字段。
注意
对于子表单
field_mappings 数组必须有以下必需的对象,除了子表单的其他字段的详细信息。这是为了将子表单记录与相应的父记录进行映射。
"api_name":"Parent_Id", "find_by":"id", "index":"the_index_in_the_csv"自定义布局
要将批量数据映射到特定布局,您必须在"default_value" JSON 对象下指定自定义布局的唯一ID。每当指定布局时,"default_value"字段都是必填的。当您将记录批量插入模块的特定布局时,系统只验证该布局中定义的必填字段。在此操作期间,将忽略其他布局的必填字段。
示例:
"api_name": "Layout", "default_value": { "value": "{custom Layout ID}" }您可以从元数据布局API获取布局ID。
- 要在特定布局中插入记录,您必须在CSV文件中指定自定义布局的名称。如果未指定/指定了错误的值,系统将在该模块中的默认布局中插入记录。此外,您必须在输入中的field_mappings键中指定相关详细信息。有关更多详细信息,请参考样本输入。
- 对于日期和日期/时间等字段类型,有默认格式。例如,日期的默认格式是MM/dd/yyyy,日期/时间的默认格式是MM/dd/yyyy HH:mm:ss。如果你在CSV文件中以任何其他格式指定这些字段的值,你必须在输入中指定格式。请参考样本输入以获取更多详细信息。
- 日期,日期-时间,数字字段(整数,小数,百分比,长整数),货币字段,这些都是支持的格式字段。点击这里了解允许的格式。
- 默认情况下,日期和日期时间字段支持ISO格式。
- 结果文件可在七天内访问。
- 压缩的 CSV 文件格式在批量写入API中得到支持。
批量请求的样本输入
批量插入子表单数据的示例输入
Request JSON用于父子模块
父模块是主模块,而子表单、行项目、多选查找字段和多用户查找字段是父模块中的子项。您必须为父项和子项拥有单独的CSV文件。
- character_encoding字符串,可选
表示上传文件的字符集。通常会自动检测,但如果指定,则将用于读取文件。
- operation字符串,必填
表示您想要在批量写入作业上执行的操作类型。
值包括
- insert - 创建CSV记录作为CRM中的新记录。
- update - 更新CRM中的现有记录(此操作不允许创建新记录)。
- upsert - 更新CRM中的现有记录,并创建新记录(如果它们尚不存在)。
- ignore_empty布尔值,可选
True - 忽略列中的空值,并仅更新记录中没有空值的字段
False或空 - 系统将在给定文件列中有空值的情况下更新CRM中的记录。
默认值是false。 - callbackJSON 对象,可选
一个有效的URL,允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。示例 - "callback" : { "url": "HTTPs://sampledomain.com/getzohoresponse", "method": "POST" }。
这个JSON对象接受两个键——url和method。- url(字符串) - 一个有效的URL,应允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。
- method(字符串) - 回调url的HTTP方法。支持的值是POST。
- 资源JSON 数组,必填
一个包含您想要导入的父模块和子模块的API名称的JSON对象数组,它们的字段映射,以及从上传API获取的相应文件ID。请注意,此数组中的第一个对象必须包含父模块的详细信息。 请注意,当您想要将大量数据写入具有多选查找字段的父模块时,您的第一个CSV文件必须包含父模块的数据,第二个CSV文件必须包含链接模块的数据。
- type(字符串,必填) - 表示您想要导入的模块类型。值为 data。
- 模块(JSON 对象,必填) - 你为批量写入任务选择的模块的 API 名称。
对于子表单或多用户查找,给出它们各自的 API 名称。对于多选查找,指定链接模块的 API 名称。 - file_id(字符串,必填) - 从文件上传API获取的file_id。此ID必须在父模块和子模块中保持一致。
- file_names(JSON 数组,必填) - 你上传的 CSV 文件的名称。这是为了将正确的 CSV 文件与正确的模块进行匹配。
- find_by(字符串,更新和upsert操作必需,插入操作可选) - 唯一字段或记录ID的API名称。系统使用此字段的值在CRM中查找现有记录。在插入操作中,如果提供了find_by,系统将从文件中跳过重复的记录。
field_mappings(JSON数组,必填) - 当系统处理CSV文件时,第一行被视为标题行。每个标题名称都被视为字段API名称,列中的数据将填充到由API名称表示的相应字段中。此参数可帮助您跳过自动映射并定义自己的字段映射。
注意:
- 默认情况下,字段映射是自动处理的。如果你想定义自己的,你可以手动映射字段。
- 如果你在输入中包含这个数组,CSV中的数据将仅根据此数组中的索引值进行映射。
- api_name(字符串,必填) - 您想要导入的Zoho模块对象中字段的API名称。请参考字段元数据API以获取模块中可用的字段列表。无效的字段API名称会抛出错误。
- parent_column_index(数字,资源数组中的子对象必填) - 这个键有助于将正确的父记录与子记录进行映射。例如,假设你的父模块是Leads,并且它有一个子表单。父CSV包含500条记录的数据,子表单CSV包含500条子表单记录的数据。这些子表单记录每一条都属于一个特定的潜在客户。因此,要将正确的子记录与正确的父记录进行映射,你必须使用"parent_column_index"键。为了建立这种映射,父记录和子记录之间必须有一个共同的列。
对于子表单和行项目,它必须是"Parent_Id"。
对于多选查找和多用户查找,它必须是链接模块中父查找的API名称。
例如,如果你有一个父模块Leads,它有一个多选查找到Contacts,那么链接模块将是Leads vs Contacts。所以,你的父CSV将用于Leads,子CSV将用于链接模块。在这里,要将子记录与父记录进行映射,你必须为链接模块中父查找字段指定parent_column_index。
请参阅注释部分以获取更多详细信息。 - index(数字,可选) - 您想要映射到CRM字段的字段的列索引。当您指定一个不存在的索引值时,系统会抛出一个错误。
- find_by(字符串,查找字段必填) - 模块中唯一字段的API名称,系统会根据此字段检查CRM中是否存在现有记录。您也可以使用id,系统定义的唯一字段的API名称,自定义唯一字段,查找字段,基于组织的外部ID,和显示列/字段(基于字段显示的结果,当您搜索关联查找时列出。例如,当您在联系人中查找指向账户的查找时,账户名称就是显示列。)作为find_by字段。当您包含parent_column_index时,此键不需要。
- default_value(JSON 对象,可选) - 如果某些记录在某列中没有值,你想用默认值替换它,就使用这个键。例如:{"value": "Trade Show"}。以下字段在 default_value 键中不受支持:多行,唯一字段,和显示字段。
注释
- "resource"数组中的第一个对象必须是父对象的详细信息。
- 每个模块只能映射一个CSV文件。
- 对于子表单和行项目,您可以映射任何系统定义和自定义字段。
- 对于多选查找和多用户查找,您只能映射链接模块中的查找字段。
父子模块的示例输入
Response 结构
- statusstring
指定API调用的状态。示例 - "status": "success"。
- messagestring
指定作业的预定义评论。在发生任何错误时非常有用。
- detailsJSON 对象
包含批量写入作业的以下详细信息。
- id(string) - 指定批量写入作业的唯一标识符(job_id)。示例 - "id": "111111000000541958"。
- created_by(JSON 对象) - 指定启动批量写入作业的用户的ID和名称。示例 - "created_by": { "id": "111111000000035795", "name": "Patricia Boyle" }。
可能的错误
- MANDATORY_FIELDS_NOT_MAPPED HTTP 400
模块中的所有必填字段都未映射。
解决方案:映射模块中的所有必填字段。 - MANDATORY_NOT_FOUND HTTP 400
请求体中未指定必需的键或值。例如:"message": "Required key find_by is not available".
解决方案:在输入中包含所需的键。 - INVALID_FIELD HTTP 400
字段API名称无效。
解决方案:指定字段的正确API名称。 - INVALID_FORMAT HTTP 400
您输入的日期格式错误。
解决方案: 请以正确的格式输入日期。 - INVALID_FILE_ID HTTP 400
指定的文件ID无效。
解决方案:指定在上传CSV文件时收到的正确文件ID。 - HEADER_LIMIT_EXCEEDED HTTP 400
映射的字段数量已超过最大限制200。
解决方案:您只能映射最多200个字段。 - COLUMN_INDEX_NOT_FOUND HTTP 400
索引映射了负值。
解决方案: "index"只能取正整数值。 - MODULE_NOT_AVAILABLE HTTP 400
指定的模块名称无效。
解决方案:模块的API名称可能错误,或者此模块不支持批量写入作业。请参阅“可能的模块名称”部分,查看支持的模块列表。 - INVALID_URL_PATTERNHTTP 404
请检查尝试访问的URL是否正确
解决方案:指定的请求URL不正确。请指定一个有效的请求URL。请参考上面的请求URL部分。 - OAUTH_SCOPE_MISMATCHHTTP 401
未经授权
解决方案:客户端没有ZohoCRM.bulk.CREATE。创建一个具有有效范围的新客户端。请参考上面的范围部分。 - NO_PERMISSIONHTTP 403
拒绝创建权限
解决方案:用户没有创建批量写作任务的权限。请联系您的系统管理员。 - INTERNAL_ERRORHTTP 500
内部服务器错误
解决方案:服务器中出现意外且未处理的异常。请联系支持团队。 - INVALID_REQUEST_METHODHTTP 400
HTTP请求方法类型无效
解决方案:您指定了无效的HTTP方法来访问API URL。请指定一个有效的请求方法。请参考上面的端点部分。 - AUTHORIZATION_FAILEDHTTP 400
用户没有足够的权限来创建。
解决方案:用户没有创建批量写入作业的权限。请联系您的系统管理员。