复合API
目的
执行一个复合API调用,包含一个或最多五个子请求。
端点
- POST /__composite_requests
Request 详情
Request URL
{api-domain}/crm/{version}/__composite_requests
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
ZohoCRM.composite_requests.CUSTOM
(和)子请求的范围
信用消费和每Request限制
API积分:1积分
注意:在复合调用中的子Request不会消耗额外的积分。
每个Request的限制:五个子Request。
有关各个API允许的记录限制的详细信息,请参阅允许的API部分。
样本请求
Request JSON
- rollback_on_fail布尔值,可选
表示如果任何子请求失败,是否回滚复合API请求。默认值为假。
- parallel_execution布尔值,可选
表示是否并行处理所有独立的子请求(没有依赖/引用的子请求)。默认值为真。如果 "rollback_on_fail" 为真,则此键的默认值为假。
- __composite_requestsJSON 数组,必填
包含子请求详细信息的 JSON 数组。
- sub_request_id (字符串,可选) - 对应子请求的请求 ID。接受的正则表达式是 [a-zA-Z0-9][a-zA-Z0-9_]*。
- uri (字符串,必填) - 对应子请求的请求 URL。接受的正则表达式是 /crm(/.*)?/v[0-9]+([.][0-9]+)?/.*。
- method (字符串,必填) - 对应子请求的请求方法。可能的方法有 GET, POST, PUT, PATCH, 和 DELETE。
- params (JSON 对象,可选) - 对应子请求的参数。
- body (JSON 对象,可选) - 对应子请求的请求体。
- headers (JSON 对象,可选) - 对应子请求的头部。请注意,您不能在此键中使用 "authorization" 或 "x-crm-org" 的头部。
注意
- 在复合API Request中使用引用:您可以在同一API调用中引用一个子Request的输出到另一个。
引用结构:@{sub_Request_id:JSON路径}
其中,
sub_Request_id 是您想要引用的Request的sub_Request_id。
JSON路径是从该Request的响应中到特定数据字段的路径。
例如,如果您在一个子Request(sub_Request_id:1)中创建了一个潜在客户,并需要在另一个中更新它,您可以使用@{1:$.data[0].details.id}动态获取子Request1中的潜在客户ID,并在子Request2中使用它来修改同一记录。请参考样本输入部分,了解如何使用这个概念的示例。 - rollback_on_fail和parallel_execution键不能同时为真。对于这样的请求,系统会抛出AMBIGUITY_DURING_PROCESSING错误。
- 所有的删除API(除了通知API)只支持在URL中使用ID。不支持批量删除选项。
- 当rollback_on_fail为假时:
- 工作流、审批和其他自动化操作按预期触发。
- 消耗一个API信用。
- 当rollback_on_fail为真时:
- 工作流程:
- 只有在所有子请求都被服务且没有执行回滚时,才会执行自动化操作。如果一个或多个子请求失败并发生回滚,自动化操作将不会被触发。
- 例如,考虑一种情况,每次创建以'S'开头的公司名称的潜在客户时,都会触发一个工作流程。在子请求1中,创建了一个公司名称以'S'开头的潜在客户,子请求2编辑了新创建的记录的公司名称,使其不以'S'开头。只有在执行了所有子请求后,工作流程才会被执行。但在这种情况下,工作流程将不会被触发,因为新创建的潜在客户的公司名称已经在子请求2中更新,且未满足工作流程的条件。再考虑另一种情况,子请求1中创建了一个公司名称为'Silicon Solutions'的潜在客户,子请求2编辑了这个新创建的记录的网站。如果其他子请求都没有改变这个新创建的记录的公司名称,那么在成功执行所有子请求后,工作流程将会被触发。
- 当发生回滚时,复合API将使用一个信用点。
- 当所有子请求都成功时,复合API将使用两个信用点。
- 工作流程:
- 每个复合API消耗五个并发信用,无论子请求的数量。
- 每个复合API将子并发数减少一个,而子请求消耗各自的子并发数。
允许的APIs
以下表格列出了在复合请求中允许的API列表。对于这些API,您在复合请求中创建、更新或删除的记录数量存在限制。
| API | 允许的记录数 |
|---|---|
| 获取组织,获取元数据,转换潜在客户,获取布局规则,获取验证规则,获取自定义链接,获取/添加/更新角色,获取配置文件,获取记录数,获取/更新蓝图,获取变量/变量组,获取标签,为记录添加/删除标签,获取附件列表,删除照片,获取货币,获取共享记录详情,获取分配规则,获取/添加/更新流水线,获取向导,获取发件地址列表,删除通知, | 无限制 |
| 添加/更新/删除用户,更新/取消关联记录,添加/删除变量,创建/更新/删除笔记,创建/更新/合并标签,添加/更新货币,添加/更新/PATCH通知,创建/更新/插入/删除记录, | 1 |
| 获取领土,获取笔记,获取电子邮件/库存模板,获取通知,获取/搜索记录,获取相关记录,通过COQL查询获取记录,获取已删除的记录,获取用户 | 25 |
样本输入
可能的错误
- API_NOT_SUPPORTEDHTTP 400
您已从不受支持的版本调用API
解决方案:您只能从V3使用Composite API。 - INVALID_DATAHTTP 400
您为rollback_on_fail或parallel_execution指定了无效的值
解决方案: 这些键的可能值要么是"true",要么是"false"。 - INVALID_DATAHTTP 400
您没有为 "composite_requests" 键指定一个 JSON 数组。
解决方案:在键中输入一个有效的 JSON 数组。 - MANDATORY_NOT_FOUNDHTTP 400
您没有指定必需的键“__composite_requests”,或者给了一个空值。
解决方案:在此键中输入有效的JSON数组。 - AMBIGUITY_DURING_PROCESSINGHTTP 400
"rollback_on_fail"和"parallel_execution"键在同一请求中不能同时为真。
解决方案:根据您的需求,将其中一个键的值指定为假。 - INVALID_DATAHTTP 400
您已使用超过5个子请求。
解决方案:对于复合API,您只能使用最多5个子请求。
样本回应
子请求可能的错误
- MANDATORY_NOT_FOUND
您在其中一个子请求中没有指定必需的键,数据类型与字段不一致,或者不符合正则表达式。
解决方案:按照正则表达式为每个子请求输入所有必需的值。确保输入的数据类型与字段的匹配。 - INVALID_DATA
您指定的 sub_request_id 无效
解决方案:请指定一个有效的 sub_request_id。接受的正则表达式是 [a-zA-Z0-9][a-zA-Z0-9_]*。 - INVALID_DATA
您为其中一个键指定了无效的值
解决方案:为所有键指定有效的值。有关更多详细信息,请参考样本输入部分。 - DUPLICATE_DATA
您为多个子请求指定了相同的sub_request_id
解决方案:为所有子请求指定唯一的sub_request_id。 - NOT_ALLOWED
您在一个或多个子请求的URL中指定了高于复合API的版本
解决方案:为所有子请求指定等于或低于复合API的版本。 - NOT_SUPPORTED
您尝试调用的API不被复合API支持
解决方案:请参考上方的支持API部分,查看在复合请求中允许的API列表。 - LIMIT_EXCEEDED
您已超过子请求中的限制
解决方案:在复合请求中,您可以创建、更新或删除的记录数量有限制。请参考"允许的API"部分,了解每个API适用的限制。 - INVALID_REFERENCE
您在请求体中给出了不正确的引用
解决方案:请参考注释部分和示例输入部分,了解如何给出正确的引用。 - INVALID_REFERENCE
给定引用中使用的响应没有适当的值
解决方案:指定一个有效的引用。 - INVALID_REFERENCE
您给出的引用尚未执行
解决方案:此错误是为顺序执行抛出的("parallel_execution"为假)。请安排子请求,以便可以正确给出引用。 - INVALID_REFERENCE
给出的引用指向的是与其引用的相同的子请求
解决方案:从另一个子请求中给出引用。 - INVALID_REFERENCE
引用中提到的子请求失败了
解决方案:此错误是为并行执行("parallel_execution"为真)抛出的。您只能使用成功的子请求作为引用。 - LOOPING_FOUND
子请求正在相互引用
解决方案:此错误是针对并行执行("parallel_execution"为true)抛出的。子请求不能相互引用。请指定引用,以避免循环。 - ROLLBACK_PERFORMED
子请求被回滚,因为复合API中的另一个子请求失败了
解决方案:只有当 "rollback_on_fail" 为真时,才会抛出此错误。进行必要的更正,使失败的API能够成功。 - PROCESSING_STOPPED
子请求被回滚,因为复合API中的另一个子请求失败了
解决方案:只有当"rollback_on_fail"为真,并且在事务回滚时还有未执行的子请求时,才会抛出此错误。进行必要的更正,使失败的API可以成功。 - REQUEST_TIMEOUT
并行完成所有子请求所需的执行时间已超过默认的五分钟超时期限
解决方案:检查网络是否存在连接问题,或执行时间超过五分钟的其他原因。即使出现此错误,已触发的子请求可能在后端成功执行。 - REQUEST_TIMEOUT
当在NIO流程中发生连接超时,且CRM尚未接收到请求时,会抛出此错误
解决方案:此错误是针对并行执行("parallel_execution"为true)抛出的。检查网络是否存在连接问题。 - INTERNAL_ERROR
内部服务器错误
解决方案:联系您的系统管理员或支持团队。
Status Code对于一个复合Request
以下是复合请求响应中的状态代码。
- 当"rollback_on_fail"为真时:
- 当执行回滚(一个或所有子请求失败)时,状态码为400。
- 当不执行回滚时,状态码为200。
- 当"rollback_on_fail"为假时:
- 当没有触发任何子请求时,状态码为400。
- 当触发了部分子请求时,状态码为207。
- 当所有子请求都被触发时,状态码为200。请注意,当所有子请求都被触发时,无论这些子请求的成功或失败,复合请求都被视为成功。