插入或更新记录(上插)
目的
Upsert API 允许您根据重复检查字段的值插入新记录或更新已有记录。
工作原理:
- 系统使用查重字段的值来检查重复记录。
- 如果存在匹配的记录,则会进行更新。
- 如果未找到匹配的记录,则插入一条新记录。
端点
- POST /{module_api_name}/upsert
{module_api_name} : 要执行 upsert 操作的模块的 API 名称。
请求详情
请求 URL
{api-domain}/crm/{version}/{module_api_name}/upsert
支持的模块
潜在客户,Account,联系人,交易,活动,案例,解决方案,产品,Vendors,价格表,报价单,SalesOrders,采购Orders,Invoices,预约,预约改期历史,服务和自定义
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
If-Unmodified-Since:2024-01-15T15:26:49+05:30
范围
scope=ZohoCRM.modules.ALL
(或者)
scope=ZohoCRM.modules.{module_api_name}.{operation_type}
可能的模块名称
线索、客户、联系人、交易、活动、案例、解决方案、产品、供应商、价目表、报价、销售订单、采购订单、发票、预约、预约重排历史、服务以及自定义。
可能的操作类型
ALL - 完全访问该记录
WRITE - Edit模块中的记录
CREATE - 在模块中创建记录
样本请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/upsert"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@upsertlead.json"
-X POSTCopied{
LeadData = Map();
LeadData.put("Last_Name", "Patricia");
LeadData.put("Email", "patricia@zoho.com"); //unique field
LeadData.put("Company", "Zoho");
LeadDataList = List();
LeadDataList.add(LeadData);
paramsMap = Map();
paramsMap.put("data", LeadDataList);
response = invokeurl
[
url: "https://www.zohoapis.com/crm/v8/Leads/upsert"
type: POST
parameters: paramsMap.toString()
connection: "zohocrm"
];
info response;
}
在请求中,"@upsertlead.json" 包含了示例输入数据。
输入JSON
- $skip_feature_executionJSON 数组, 可选
默认情况下,如果模块配置了Cadence,则在通过API对记录执行upsert操作(Insert 或 Update 操作)时会自动执行Cadence。此键允许你在记录upsert期间跳过Cadences功能的执行。要跳过该记录的Cadences执行,请将"name"键的值指定为"cadences"。请确保在请求中此键与"data"键一起包含。
- name字符串,必填
表示功能名称。
可能值: cadences
- action字符串,必填
表示根据哪个操作跳过此功能。系统会根据此操作跳过功能执行。支持的值:“Insert”和“Update”。例如,如果 "action": "Insert",则当通过upsert API插入记录时,系统将跳过该功能的执行。
注意
- 在使用 Upsert API 时,系统会根据重复检查字段验证记录是否重复。重复检查字段分为两种类型:
- 系统定义的重复检查字段
- 这些是在每个模块中预定义的唯一字段。
- 系统会自动检查这些字段,以防止重复条目。
- 有关各模块详细信息,请参阅系统定义的重复检查字段部分。
- 用户自定义唯一字段
- 这些字段启用了“不允许重复值”选项。
- Users可以定义自定义唯一字段以防止数据重复。
- 了解更多关于如何启用将字段标记为唯一的信息。
- 系统定义的重复检查字段
当一条记录被插入或更新时,系统会首先检查这些字段中的重复项。如果存在匹配的记录,则会被更新;否则,将插入一条新记录。
- 您可以在 API 请求中的 duplicate_check_fields 数组中设置系统验证重复记录的顺序。
- 允许的字段:
- 系统定义的重复检查字段。例如,Email用于线索。
- 用户自定义的唯一字段。例如,电话和传真。
- 允许的字段:
示例:在线索模块中:
"duplicate_check_fields":
[
"Email",
"电话",
"传真"
]
如果您没有指定 duplicate_check_fields,系统将按照以下默认顺序进行操作:
一、系统定义的重复检查字段
二、用户自定义唯一字段
- 如果字段的取值长度超过该字段定义的最大长度,则会抛出“INVALID_DATA”错误。
- 如果在函数中使用了 API 并且字段值的长度超出限制,那么该函数会从 API 收到一个错误响应。例如:如果“文本字段”的最大长度被定义为 10,那么在 API 中为其提供的值不能是“12345678901”,因为它有 11 个字符。
- 每次 API 调用最多可以插入/更新 100 条记录。
- 请参考我们的 Kaizen 文章:Upsert 记录 API 和 重复检查 Preferences API 与 Upsert API 对比,了解包含实时用例的更多详情。
- 您必须仅在输入中使用字段 API Name。您可以通过以下方式获取字段 API Name:
- 字段元数据 API(每个字段的键“api_Name”对应的值)。(或者)
- 设置 > 开发者中心 > API 和 SDK > API Name > {模块}。在“筛选方式”下拉菜单中选择“字段”。
- 触发器输入可以是工作流、审批或蓝图。如果未提及触发器,将会执行与 API 相关的工作流、审批和蓝图。输入触发器值为 [] 时,将不会执行工作流。
- 带有子表单详细信息的记录也可以通过记录API插入或更新到CRM。要了解如何在记录中添加子表单信息,请参阅子表单API。如需获取有关子表单的详细信息,请参考我们的Kaizen文章:使用Zoho CRM API 操作子表单。
- $append_values 键表示您是否希望将输入中指定的多选列表的值追加到现有值后。请在此 JSON 对象中,以多选列表的 API 名称为键,"true" 或 "false" 为值,作为键值对进行指定。值为 "true" 时会将输入中的值追加到多选列表中,值为 "false" 时会用输入中的值替换现有值。
如果您希望
- 在 API 级别的必填项检查中包含布局特定的必填字段
仅在 API 级别处理中包含您在布局中定义的字段,并忽略其他字段
,则必须提供 布局 ID 字段。
系统定义的重复检查字段
以下是不同模块的默认重复检查字段。
| 模块 | 系统定义的重复检查字段 |
|---|---|
| 线索 | |
| Account | Account_Name |
| 联系人 | |
| 交易 | 交易_Name |
| 市场活动 | 市场活动_Name |
| 案件 | 主题 |
| 解决方案 | 解决方案标题 |
| 产品 | 产品_Name |
| Vendors | 供应商_Name |
| 价格手册 | 价格手册_Name |
| 报价 | 主题 |
| SalesOrders | 主题 |
| 采购Orders | 主题 |
| Invoices | 主题 |
| 自定义模块 | Name |
要了解 Zoho CRM 中每个模块的具体细节及其限制,请参阅 示例Attributes 部分,详见 Insert记录 API。
重复检查是如何工作的?
考虑一种情况,用户为某个模块配置了两个唯一字段 unique1 和 unique2(用户自定义唯一字段),而Email是系统定义的唯一字段。
下表解释了对于不同用户输入 duplicate_check_fields 数组时,如何进行重复检查。
| 用户输入到 "duplicate_check_fields" 数组 | 查重模式 |
|---|---|
| unique1 | unique1,unique2 |
| unique2 | unique2,unique1 |
| unique1,unique2 | unique1,unique2 |
| Email,unique1,unique2 | |
| 无输入 | 该模块的系统定义查重字段,后跟唯一字段。即Email,unique1,unique2 |
如果您没有在数组中指定系统定义的重复检查字段,系统将忽略这些字段,并只检查用户自定义的唯一字段。
示例输入
Copied{
"data": [
{
"Last_Name": "Lead_changed",
"Email": "newcrmapi@zoho.com",
"Company": "abc",
"Lead_Status": "Contacted",
"Foreign_Languages": [ //multi-select picklist
"Korean"
],
"$append_values": {
"Foreign_Languages": false
}
},
{
"Last_Name": "New Lead",
"First_Name": "CRM Lead",
"Email": "newlead@zoho.com",
"Lead_Status": "Attempted to Contact",
"Mobile": "7685635434",
"Foreign_Languages": [ //multi-select picklist
"Korean",
"Spanish"
],
"$append_values": {
"Foreign_Languages": true
}
}
],
"skip_feature_execution": [
{
"name": "cadences",
"action": "insert"
}
],
"duplicate_check_fields": [
"Email",
"Mobile"
],
"trigger": [
"workflow"
]
可能的错误
- INVALID_MODULEHTTP 400
所提供的模块名称似乎无效
解决方法:您指定了一个无效的模块名称,或者没有选项卡权限,或者该模块已从可用模块中移除。请指定有效的模块 API 名称。 - INVALID_MODULEHTTP 400
所提供的模块在 API 中不受支持
解决方法: 诸如文档和项目等模块在当前 API 中不受支持。(一旦这些模块被支持,该错误将不会显示。)请指定有效的模块 API 名称。 - INVALID_DATAHTTP 400
无效数据
解决方法:指定的输入不正确。请指定有效的输入。 - INVALID_URL_PATTERNHTTP 404
请检查尝试访问的URL是否正确
解决方法:指定的请求URL不正确。请指定有效的请求URL。请参考上面的请求URL部分。 - OAUTH_SCOPE_MISMATCHHTTP 401
未授权
解决方法:客户端没有 ZohoCRM.modules.{module_name}.WRITE/ZohoCRM.modules.{module_name}.CREATE 权限范围。请使用有效的权限范围创建新的客户端。详见上面的权限范围部分。 - NO_PERMISSIONHTTP 403
无权限进行插入或更新操作
解决方法: 用户没有插入或更新记录的权限。请联系您的系统管理员。 - ALREADY_MODIFIEDHTTP 412
记录的更新时间已经晚于 if-unmodified-since 时间
解决方法:该记录在指定的 If-Unmodified-Since 时间戳之后已被更新。请使用更新的 If-Unmodified-Since 请求头值重试。 - DUPLICATE_DATAHTTP 400
数据重复
解决方法:您为一个或多个唯一字段指定了重复的值。响应中的 "details" 键提供了输入中包含重复值的字段的 API 名称。请为唯一字段指定唯一的值。 - INTERNAL_ERRORHTTP 500
服务器内部错误
解决方法:服务器中出现了意外且未处理的异常。请联系支持团队。 - INVALID_REQUEST_METHODHTTP 400
HTTP 请求方法类型无效
解决方案:您为访问 API URL 指定了无效的 HTTP 方法。请指定有效的请求方法。参考上面的端点部分。 - AUTHORIZATION_FAILEDHTTP 400
用户没有足够的权限来插入或更新记录。
解决方法:该用户没有插入或更新记录详情的权限。请联系您的系统管理员。 - MANDATORY_NOT_FOUNDHTTP 400
未找到必填字段
解决方法:您未在输入中指定一个或多个必填字段。请参考字段元数据 API了解必填字段。
示例回复
Copied{
"data": [
{
"code": "SUCCESS",
"duplicate_field": "Email",
"action": "update",
"details": {
"Modified_Time": "2020-10-14T10:31:43+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "4150868000000225013"
},
"Created_Time": "2019-09-11T16:21:15+05:30",
"id": "4150868000000376008",
"Created_By": {
"name": "Patricia Boyle",
"id": "4150868000000225013"
}
},
"message": "record updated",
"status": "success"
},
{
"code": "SUCCESS",
"duplicate_field": null,
"action": "insert",
"details": {
"Modified_Time": "2020-10-14T10:31:43+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "4150868000000225013"
},
"Created_Time": "2020-10-14T10:31:43+05:30",
"id": "4150868000003194003",
"Created_By": {
"name": "Patricia Boyle",
"id": "4150868000000225013"
}
},
"message": "record added",
"status": "success"
}
]
}