Zoho crm Logo

端点

  • POST /coql

Request 详情

Request URL

{api-domain}/crm/{version}/coql

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

scope=ZohoCRM.coql.READ
(和)
scope=ZohoCRM.modules.{operation_type}
(或)
scope=ZohoCRM.modules.{module_name}.{operation_type} 
 

注意:使用ZohoCRM.settings.fields.READ范围来检索字段元数据。如果没有这个范围,系统将抛出一个OAUTH_SCOPE_MISMATCH错误。 

 

可能的模块名称

潜在客户,账户,联系人,用户,交易,活动,任务,案例,事件,呼叫,解决方案,产品,供应商,价格表,报价,销售订单,采购订单,发票,以及自定义

可能的操作类型

全部 - 完全数据访问
读取 - 获取模块数据

注意

  • 尽管你从模块中“获取”记录,但HTTP方法是POST,因为你“POST”查询。请参考查询API - 概述来学习如何构建COQL查询。
  • 当您在查询中使用模块的API名称时,前缀加上!以区分模块的API名称和字段的API名称。例如,!Leads.Owner.role.id。
  • 加密数字字段支持=,!=,为空和不为空。
  • 支持在SELECT列和WHERE子句中使用加密字段。
  • 加密的非数字字段仅支持为空和不为空。
  • 元组(Tuple)在COQL中不受支持。
  • Full_Name字段包含了First_Name和Last_Name字段的连接值。这是一个只读字段,仅在Leads和Contacts模块中可用。
  • 您可以在SELECT列中最多包含五个动态公式字段。
  • 公式字段: 
    要在查询中包含公式字段,请确保您只使用支持的比较器来检索信息。可用的比较器可能会根据公式字段的返回类型而变化。下表概述了基于返回类型的支持的比较器:

    公式字段的返回类型

    字段数据类型

    支持的比较器

    小数,日期,日期时间,数字=, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
    字符串(文本)=, !=, like(用于 starts_with, ends_with, contains), not like(用于 not_contains), in, not in, is null, is not null
    布尔值is null, is not null, equals

Request JSON

  • select_queryJSON 键,必填

    表示输入是一个选择查询。

样本请求

在请求中,“@input.json”包含了样本输入数据。

字段类型及其比较器

以下部分描述了COQL查询中的字段类型及其允许的比较器,并且每种类型都有一个示例。

  • 文本,下拉列表

    =,!=,like(用于 starts_with, ends_with, contains),not like(用于 not_contains),in,not in,is null,is not null。

注意

可以使用 % 通配符与 like 操作符一起使用,以实现类似于 contains, starts_with, 和 ends_with 操作符的功能。例如,'%tech' 用于查询字段值以 'tech' 结尾,'C%' 用于查询值以 'C' 开头,'%tech%' 翻译为包含 'tech'。

请注意,对于 Not Like 操作符,只有在两端都给出 '%'(不包含)时才有效。只在开头(不以...开始)或结尾(不以...结束)使用 '%' 是无效的。

有效的情况是:

  • like "%tech" - 以 'tech' 结尾
  • like "%tech%" - 包含 'tech'
  • like "tech%" - 以 'tech' 开头
  • not like "%tech%" - 不包含 'tech'

样本查询

Response JSON 键

  • First_Name字符串

    代表联系人的名字。

  • Last_Name字符串

    代表联系人的姓氏。

  • Full_Name字符串

    代表联系人的全名。

  • id字符串

    代表联系人的唯一ID。

  • Languages_KnownJSON 数组

    代表在多选下拉列表中选中的值。

  • Lead_Source字符串

    代表在下拉列表中选中的值。

样本回应

  • 查找

    =, !=, 在, 不在, 为空, 不为空.

    注意:当你查询一个查找字段时,响应只包含该字段的ID。要获取字段的名称,你必须在查询中包含field_API_name。

样本查询

在此查询中,通过联系人模块中的查找字段Account_Name建立了连接。

Response JSON 键

  • Account_Name.Account_Namestring

    在这里,Account_Name返回账户的ID,而Account_Name.Account_Name返回与联系人关联的账户的账户名称。

样本回应

  • 日期,日期时间,数字

    =, !=, >=, >, <=, <, 之间, 不在之间, 在, 不在, 为空, 不为空.

    注意

    使用日期时间字段,您可以根据任何时区过滤记录。

样本查询

Response JSON 键

  • Created_TimeISO 8601格式的日期时间

    表示记录创建的日期和时间。

  • Modified_TimeISO 8601格式的日期时间 

    表示记录修改的日期和时间。

  • Days_Visited数字

    潜在客户或联系人访问您客户网站的天数。

  • Annual_Revenue货币

    表示记录的姓氏。

样本回应

  • 布尔值

    =

样本请求

Response JSON 键

  • Email_Opt_Out布尔值

    代表联系人的电子邮件偏好。

样本回应

聚合函数

您现在可以在select查询中使用聚合函数SUM,MIN,MAX,AVG和COUNT。以下各节给出了每个支持的聚合函数的示例。请注意,聚合函数是区分大小写的。 

注意

  • 查询中的重复聚合字段将导致响应中出现"DUPLICATE_DATA"错误。
{ "select_query" : "select COUNT(De1), COUNT(De1) from Leads where id is not null" }
  • 聚合函数仅支持数值数据类型,例如
    • 整数
    • 小数
    • 货币
    • 大整数
    • 返回上述任何类型的公式字段。
  • 总和

    使用此函数来求模块中聚合字段的值的总和。这个示例查询获取了年收入超过1000的潜在客户生成的总年收入。

样本查询

样本回应

  • MAX

    此函数返回聚合字段的最大值。示例查询使用此函数来获取属于"ABC"公司的潜在客户的最大年收入。

样本查询

样本回应

  • MIN

    此函数返回聚合字段的最小值。示例查询使用此函数来获取属于"ABC"公司的潜在客户的最小年收入。

样本查询

样本回应

  • AVG

    使用此函数可以获取字段值的平均值。这个示例查询获取了潜在客户生成的平均年收入。

样本查询

样本回应

  • 计数

    使用计数函数来获取满足选择查询中的条件的记录数。

    示例查询检索年收入超过25,000的潜在客户记录的数量。这些记录是根据潜在客户来源使用分组子句进行分组的。例如,你可以看到有两条年收入超过25,000的记录,其潜在客户来源是“在线商店”。同样,对于“广告”这个潜在客户来源,有两条年收入超过25,000的记录。
    请注意,你只能对数字、查找和选项列表字段使用这个聚合函数。

样本查询

样本回应

  • 多模块查找和what_id支持

    =, !=, 在, 不在, 为空, 不为空.

    What_Id支持仅适用于任务,呼叫和事件。在使用What_Id检索COQL中的记录时,关联记录可能是几种不同类型的记录之一。例如,任务的What_Id字段可能是潜在客户或联系人。

样本查询

Response JSON 键

  • What_Id->Leads.Last_Name字符串

    代表为其创建活动(任务,呼叫,事件)的潜在客户的姓氏。

  • What_Id->Accounts.Account_Type字符串

    代表与其创建活动(任务,呼叫,事件)的关联账户的账户类型。

样本回应

查询多模块查找

样本回应

  • 角色和配置文件支持

    =, !=, 在, 不在, 为空, 不为空.

    您可以从模块中获取所有者的配置文件的详细信息,如ID,名称,创建者,修改者,描述,创建时间,修改时间,以及所有者的角色的详细信息,如ID,名称,报告给,与同行分享数据,描述。

样本查询

样本回应

  • 别名支持

    =, !=, 在, 不在, 为空, 不为空.

    您现在可以通过在select查询中的别名"as"获取记录的详细信息。例如,在联系人模块中,'Account_Name' AS 'Account id'在select查询中获取与字段"Account id"关联的账户的ID。参考样本输入部分以获取更多此类别名。
    请注意,您只能在选择列和"order_by"子句中使用别名。

样本查询

Response JSON 键

  • 账户idJSON 对象

    代表与联系人关联的账户的ID。

  • 账户名称字符串

    代表与联系人关联的账户的名称。

  • 父账户idJSON 对象

    代表与联系人的账户关联的父账户的ID。

  • id字符串

    代表联系人的ID。

样本回应

带有两个关系(连接)的样本查询

select Last_Name, Account_Name.Parent_Account, Account_Name.Parent_Account.Account_Name from Contacts where Last_Name is not null and Account_Name.Parent_Account.Account_Name is not null

在此查询中,使用联系人模块中的查找字段Account_Name和账户模块中的另一个查找字段Parent_Account建立了两个连接。

样本查询

Response JSON 键

  • Account_Name.Parent_Account.Account_Namestring

    在这里,关系 Account_Name.Parent_Account 返回与联系人关联的账户的父账户的 ID。关系 Account_Name.Parent_Account.Account_Name 返回与联系人关联的账户的父账户的名称。

样本回应

带有用户/所有者查找字段的示例查询

select Last_Name, First_Name, Full_Name, Owner from Contacts where Last_Name = 'Boyle' and Owner = '554023000000235011' limit 3

在此查询中,所有者是联系人模块中的查找字段。此查询从联系人模块中获取指定姓氏的记录,其所有者id为554023000000235011。

样本查询

Response JSON 键

  • 所有者JSON 对象

    代表记录所有者的唯一ID。

样本回应

带有多个条件的样本查询在where子句中

为了防止歧义,列在WHERE子句中的条件必须适当地用括号括起来。如果WHERE有超过两个条件,如A、B和C,可以按以下任一方式使用它们:

  • (A和(B和C))
  • ((A和B)和C)
  • A和(B和C)
  • (A和B)和C。

 

样本查询

查询多模块查找模块名称 

要了解与Appointments模块中的"Appointment_For"字段相关联的每个记录的模块。

样本查询

样本回应

  • 使用外部ID的示例查询

    您可以在select查询和"where"子句中使用模块的外部字段。在此示例中,External_Account_ID是Accounts模块中外部字段的API名称。

样本查询

样本回应

  • 使用CVID检索数据的示例查询

    基于自定义视图过滤和检索记录。COQL API以以下格式支持CVID:FROM {module_API_name}#{CVID}。

    不支持的自定义视图:以下自定义视图在任何模块中都不受支持。

    • 我分享的
    • 共同所有者
    • 分享给我的

样本查询

样本回应

  • 获取选定字段的字段元数据的示例查询

    您可以使用 include_meta 键来检索在 SELECT 列中指定的 字段 的 元数据。

注意

要检索字段元数据,ZohoCRM.settings.fields.READ 范围是必需的。没有这个范围,系统将抛出一个 OAUTH_SCOPE_MISMATCH 错误。

样本查询

样本回应

  • 使用领土字段获取数据的示例查询

    要检索与模块中的记录相关联的领土,请在SELECT列中指定字段API名称。 

    支持的模块:账户,联系人,潜在客户和交易。

     

    注意

    领土字段API名称因模块而异:

    • 账户,联系人和潜在客户 - 领土
    • 交易 - 领土

样本查询

样本回应

  • 获取查找字段的示例查询 

    从V7开始,当你在SELECT列中指定它们时,显示名称可用于查找和用户查找字段,但它不适用于同意查找和多模块查找(MML)字段。 
    请注意,对于用户模块,只有"last_name"作为用户模块的显示字段是last_name。

样本查询

样本回应

  • 同意查找

    要通过同意查找从同意模块检索信息,请确保启用了GDPR并正确配置了所需的模块。有关更多详细信息,请参阅同意管理文档。

    注意: 
    一旦为模块启用并配置了GDPR,将在相应模块中创建一个新的数据处理基础详情字段,数据类型为consent_lookup ("data_type": "consent_lookup")。您可以使用GET字段元数据API检索这些详细信息。要获取同意模块的字段,请对同意模块进行GET字段元数据API调用。 
     

样本查询

样本回应

  • 使用个人资料图片ID检索数据的示例查询

    您可以使用记录图片的ID来获取相关数据。例如,如果您只有记录图片的ID,并希望检索相应记录的姓氏,您可以在查询中包含记录图片ID。

    使用COQL检索个人资料图片ID:

    要检索模块中不同记录的记录图片字段的唯一ID,使用以下查询:

     { "select_query": "select Record_Image from Leads where Record_Image is not null" } 


    这将返回模块中每个记录的记录图片ID。

    注意:
    您可以通过指定个人资料图片字段ID来下载图片,该ID可以使用上述查询检索。您可以使用GET - 文件API 来下载图片。

样本查询

样本回应

  • 访问子表单数据的示例查询

    您可以使用其对应的模块API名称查询子表单数据,因为子表单被视为一个独立的模块。 

    示例查询从购买项目子表单中检索数据,以及其父模块采购订单的相关信息。它检索诸如主题、总计、产品名称、数量、列表价格、折扣、税费和净总计等字段,其中采购订单号(PO_Number)为101。

    注意

    请参阅Kaizen #124 - 使用Zoho CRM APIs操作子表单以获取更多详细信息。

样本查询

样本回应

  • 访问多选查找字段(MxN)的示例查询

    您可以使用其对应的链接模块查询多选查找字段(MxN字段)。

    示例查询检索具有内容营销技能的员工,以及他们的姓名和电子邮件地址。

    注意

    有关更多详细信息,请参阅Kaizen #125 使用Zoho CRM APIs操作多选查找字段(MxN)。

样本查询

样本回应

  • 使用汇总字段的示例查询

    汇总字段支持的比较器包括 "=", "!=", ">=", ">", "<=", "<", "between", "not between", "in", "not in", "is null" 和 "is not null"。

注意

从V7开始,Rollup Summary字段的日期和日期时间返回类型的响应将按照各自的格式提供。

样本查询

可能的错误

  • SYNTAX_ERRORHTTP 400

    查询中不包含适当的条件、基表或where子句。
    解决方案:形成一个包含适当的条件、基表和where子句的查询。

  • SYNTAX_ERRORHTTP 400

    查询中不包含from子句。
    解决方案:形成包含from子句的查询。

  • SYNTAX_ERRORHTTP 400

    请求包含了除select之外的查询。
    例如:"select_query" : "update Leads set Last_Name = 'Last' where id = 12356"。
    解决方案:你只能在你的select查询中使用Select语句。

  • SYNTAX_ERRORHTTP 400

    给定查询的解析时间过长。请验证查询。
    解决方案:给定的查询可能过于复杂或括号不平衡。请指定一个有效且优化的查询。

  • LIMIT_EXCEEDEDHTTP 400

    限制子句的值或选择列(字段API名称)已超过最大限制200和50。
    解决方案:您只能在单个API调用中获取最多200条记录和50个字段。

  • LIMIT_EXCEEDEDHTTP 400

    查询中有超过两个连接。
    示例:"select_query":"select Account_Name.Account_Name, Account_Name.Parent_Account.Account_Name, Vendor_Name.Vendor_Name from Contacts where Lead_Source = Advertisement"
    解决方案:在select查询中,最多只能有两个连接。

  • LIMIT_EXCEEDEDHTTP 400

    您在select查询的“in”或“not in”比较器中指定了超过50个值。
    解决方案:您只能为“in”或“not in”比较器指定最多50个值。

  • LIMIT_EXCEEDEDHTTP 400

    超过最大记录限制
    解决方案:您可以使用分页,并仅使用COQL查询获取最多1,00,000条记录。

  • LIMIT_EXCEEDEDHTTP 400

    您在查询中为SELECT列的“in”或“not in”比较器指定了超过100个值
    解决方案:您只能为“in”或“not in”比较器指定最多100个值。

  • LIMIT_EXCEEDEDHTTP 400
    • ORDER BY子句中的字段数量超过了允许的限制
      解决方案:确保在ORDER BY子句中指定的字段数量不超过10个字段的允许限制。
    • GROUP BY子句中的字段数量已超过其限制
      解决方案:确保并指定GROUP BY子句中的字段数量在允许的限制内。允许的限制是四个字段。
    • 查询中的聚合字段数量已超过限制
      解决方案:查询中允许的最大聚合字段数量为五个。
  • INVALID_QUERYHTTP 400

    查询包含无效的列名(field_API_name)。
    例如:"select Last_Name, Testing from Leads where Last_Name is not null"
    解决方案:提供有效的字段API名称。

  • INVALID_QUERYHTTP 400

    查询包含不支持的数据类型。
    示例:"select Last_Name, Contacts from Leads where Last_Name is not null"
    这里,Contacts是一个多选查找字段,COQL不支持。
    解决方案:提供具有有效数据类型的字段API名称。

  • INVALID_QUERYHTTP 400

    选择列的值的数据类型无效。
    示例:"select_query":"select Last_Name from Leads where Last_Name is not null and No_of_Employees = 'adfkahfd'"
    在这里,No_of_Employees的预期数据类型是数字,而给出的值是字符串。
    解决方案:提供与其数据类型相对应的选择列的值。

  • INVALID_QUERYHTTP 400

    查询包含无效的运算符。
    示例:"select_query":"select Last_Name from Leads where Last_Name is not null and Last_Name >= 'adfkahfd'" 解决方案:只使用各自字段接受的运算符。

  • INVALID_QUERYHTTP 400
    • 在include_meta键中给出的值似乎无效
      解决方案:为include_meta键指定一个有效的值。支持的值是fields。
    • 在include_meta键中为fields指定的数据类型无效
      解决方案:为fields键指定一个有效的数据类型。支持的数据类型是text。
    • include_meta键的数据类型无效
      解决方案:指定一个有效的数据类型。支持的数据类型是JSON数组。
  • INVALID_QUERYHTTP 400

    领域字段仅在SELECT子句中受支持
    解决方案:仅在SELECT列中指定领域字段。

  • INVALID_QUERYHTTP 400

    查询中提供的CVID无效
    解决方案:在查询中指定一个有效的自定义视图ID。使用自定义视图元数据API 获取您的自定义视图ID。

  • INVALID_ALIASHTTP 400

    别名不能是空字符串
    示例:"select Account_Name 'Account_as','Account_Name.Account_Name' \" \"
    解决方案: 提供一个有效的别名。

  • OAUTH_SCOPE_MISMATCHHTTP 401

    用户没有访问该模块所需的范围。
    解决方案:联系您的管理员以获取所需的权限。

  • DUPLICATE_DATAHTTP 401

    查询中包含重复的选择列(field_API_names)。例如:"select_query":"select Last_Name, First_Name, Full_Name, Created_Time, Full_Name from Contacts where Lead_Source = Advertisement limit 2"
    这里,查询中包含了两次Full_Name。
    解决方案:确保查询中没有重复的选择列。

  • DUPLICATE_ALIASHTTP 400

    同一个别名不能引用超过一个选择列
    解决方案:确保您为每个选择列使用唯一的别名。

  • DUPLICATE_DATAHTTP 400
    • 查询中的ORDER BY子句包含重复字段
    • ORDER BY子句中的字段数量超过了允许的限制

    解决方案:确保查询的ORDER BY和GROUP BY子句中没有重复字段。

    • 查询中包含重复的聚合字段 
      解决方案:查询中不要重复聚合字段。
  • INTERNAL_ERRORHTTP 500

    内部服务器错误
    解决方案:服务器中出现意外且未处理的异常。请联系支持团队。

  • INVALID_REQUEST_METHODHTTP 400

    请求的HTTP方法类型无效
    解决方案:您指定了无效的HTTP方法来访问API URL。请指定一个有效的请求方法。请参考上面的端点部分。

样本回应