通过COQL查询获取记录
目的
通过COQL查询从模块中获取记录。
目录
端点
- 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子句中的字段数量在允许的限制内。允许的限制是四个字段。 - 查询中的聚合字段数量已超过限制
解决方案:查询中允许的最大聚合字段数量为五个。
- ORDER 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数组。
- 在include_meta键中给出的值似乎无效
- 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。请指定一个有效的请求方法。请参考上面的端点部分。