Zoho crm Logo

复合API - 概述

复合API允许您在单个请求中组合多达五个API调用，每个复合调用只消耗一个信用点。此API减少了往返时间，并允许您在需要时在单个数据库事务中执行API。
单个数据库事务，我们的意思是您的请求可以有多个子请求（单个API），并且可以按顺序执行。当所有子请求成功执行后，或者由于单个子请求失败导致整个复合请求回滚（所有更改都被撤销）后，您将得到响应。
 

什么是往返时间（RTT），这个API如何减少它？
客户端请求到达服务器并在客户端中渲染响应所需的时间被称为往返时间。 
由于你将所有请求集中在一个复合API中，所以可以节省往返时间。如果一个或多个子请求失败，你可以选择回滚（撤销所有更改）整个事务。

键 "rollback_on_fail" 和 "parallel_execution"

  • rollback_on_fail：这个布尔键表示当一个或多个子请求失败时，您是否希望回滚复合请求。
  • parallel_execution：这个布尔键表示您是否希望并行处理所有独立的子请求。

让我们讨论这个API最出色的两种情况。

  1. 子请求不在同一事务下执行并行执行为假

    • 当存在通过自动化操作内部依赖的子请求时，使用此流程。
      例如，您配置了一个工作流，当供应商的名称为Zylker时触发。在子请求1中，您将现有供应商的名称从Zoho更新为Zylker。在子请求2中，您使用其ID创建一个与最近更新的供应商关联的联系人。这两个看起来像是独立的请求，但是通过工作流有内部依赖性。也就是说，要触发工作流，您必须先执行子请求1，然后执行第二个。因此，您不能使用并行执行。

      {
    "parallel_execution" : false,
    "__composite_requests": [
        {
            "sub_request_id":"1",
            "method":"PUT",
            "uri":"/crm/v3/Vendors/111111000000050313",
            "headers":{},
            "body":
            {
                "data":[
                    {
                        "Email":"v@gmail.com",
                        "Vendor_Name":"V1"
                    }
                ]
            }
        },
        {
            "sub_request_id":"2",
            "method":"POST",
            "uri":"/crm/v3/Contacts",
            "body":{
                "data":[
                    {
                        "Vendor_Name":"111111000000050313",
                        "Last_Name":"composite",
                        "Email":"composite2@test.test"
                    }
                ]
            }
        }
    ]
}

    • 并行执行为真

      • 情况1：具有独立的子请求
         

        当你的子请求彼此独立，你希望通过并行执行它们来节省时间时，使用这个流程。例如，获取潜在客户，获取另一个模块的元数据等。

      • 情况2：具有依赖和独立的子请求
         

        当你的子请求彼此独立，你希望通过并行执行它们来节省时间时，使用这个流程。例如，获取潜在客户，获取另一个模块的元数据等。

      {
    "parallel_execution" : true,
    "__composite_requests": [
        {
            "sub_request_id":"1",
            "method":"POST",
            "uri":"/crm/v3/Leads",
            "headers":{},
            "body":
            {
                "data":[
                    {
                        "Last_Name":"composite",
                        "Email":"composite@test.test"
                    }
                ]
            }
        },
        {
            "sub_request_id":"2",
            "method":"POST",
            "uri":"/crm/v3/Contacts",
            "body":{
                "data":[
                    {
                        "Account_Name":"@{1:$.data[0].details.id}",
                        "Last_Name":"composite",
                        "Email":"composite2@test.test"
                    }
                ]
            }
        },
        {
            "sub_request_id":"3",
            "method":"POST",
            "uri":"/crm/v3/Accounts",
            "body":{
                "data":[
                    {
                        "Account_Name":"A1"
                    }
                ]
            }
        }
    ]
}

  2. 子Request在同一事务下执行 (rollback_on_fail:true, parallel_exec:false)
    当存在依赖的子Request，且一个的执行依赖于另一个子Request的响应时。在这里，你必须引用你想在另一个子Request中使用的数据的子Request。
    例如，你想在联系人模块中插入或更新一条记录（子Request1），在账户模块中插入或更新一条记录（子Request2），并在将潜在客户转化为实际客户的同时，将其关联到之前插入或更新的联系人和账户（子Request3）。子Request3依赖于子Request1和2的执行。这允许你在其中一个子Request失败时回滚复合Request。也就是说，联系人和账户将不会被插入或更新。
    输入将如下所示。

    {
    "rollback_on_fail": true,
    "parallel_execution" : false,
    "__composite_requests": [
        {
            "sub_request_id":"1",
            "method":"POST",
            "uri":"/crm/v3/Contacts/upsert",
            "headers":{},
            "body":
            {
                "data":[
                    {
                        "Last_Name":"composite",
                        "Email":"composite@test.test"
                    }
                ]
            }
        },
        {
            "sub_request_id":"2",
            "method":"POST",
            "uri":"/crm/v3/Accounts/upsert",
            "body":{
                "data":[
                    {
                        "Account_Name":"C1",
                        "Email":"composite2@test.test"
                    }
                ]
            }
        },
        {
            "sub_request_id":"3",
            "method":"POST",
            "uri":"/crm/v3/Leads/111111000000095001/actions/convert",
            "body":{
                "data":[
                    {
                        "Accounts":"@{2:$.data[0].details.id}",
                        "Contacts":"@{1:$.data[0].details.id}"
                    }
                ]
            }
        }
    ]
}