相关记录数据
Zoho CRM 中的一条记录可以拥有相关数据,例如备注、附件、产品、交易和联系人。使用 关联记录 API(Related Records API),你可以获取与特定模块记录相关的所有关联记录。
获取相关记录
目的
获取相关列表记录。
端点
- GET /{module_api_name}/{record_id}/{related_list_api_name}
- {module_api_name} :要从中获取相关记录的模块 API 名称。例如,线索(Leads)、Account、联系人(Contacts) 等。
- {record_id}:指定模块中记录的唯一 ID。
- {related_list_api_name} :要检索的相关列表的 API 名称。例如,Notes、Attachments、Emails 等。相关列表元数据 API 响应中的 href 属性提供了获取相关记录的精确端点。
请求详情
请求 URL
{api-domain}/crm/{version}/{module_api_name}/{record_id}/{related_list_api_name}
支持的关联
支持所有模块及其相关记录。使用相关列表元数据 API获取某个模块可用的相关列表。相关列表元数据 API 的响应中的 href 属性提供了用于获取相关记录的精确端点。
标题
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
If-Modified-Since: 使用此标头获取最近修改的记录列表。示例:2019-07-25T15:26:49+05:30
范围
scope=ZohoCRM.modules.ALL
(或)
scope=ZohoCRM.modules.{module_API_name}.{operation_type}
可能的模块名称
线索、账户、联系人、交易、活动、任务、服务单、事件、通话、解决方案、产品、供应商、价格表、报价、销售订单、采购订单、发票、自定义、预约、预约改期历史和服务。
可能的操作类型
ALL - 完全访问相关记录
READ - 读取相关记录
参数
- 字段字符串,必填
指定要在响应中接收其详细信息的字段的 API 名称。使用 GET - 字段元数据 API 来检索模块中可用字段的列表。
- page整数,可选
用于从相应的页面获取记录列表。page 的默认值为 1。
可能的取值:仅限正整数。 - per_page整数,可选
获取每页可用的记录列表。默认值和最大可能值为200。
可选值:仅限正整数值。 - page_token字符串,进行分页以获取超过 2000 条记录时必填
在不使用 page_token 的情况下,你可以使用 page 参数来获取最多 2000 条记录。若要获取超过 2000 条记录,必须在请求中包含 page_token 参数。此参数取值自第一次调用“获取关联记录”(Get Related Records)接口返回结果中的 next_page_token 键。请注意,该 token 值是与用户绑定的。如果你使用了其他用户的 token,系统会报错。
请注意,不能同时在请求中使用此参数和 page 参数。 - ids字符串,可选
根据记录的唯一 ID 获取特定记录。使用 GET - Records API 来获取模块中有效的记录 ID。
可能的取值:记录的有效唯一 ID。示例:4150868000001944196 - sort_order字符串,可选
用于将可用的记录列表按升序或降序排序。
可能的取值:
- desc (默认)- 降序。
- asc - 升序
- sort_by字符串,可选
根据字段 id、Created_Time 和 Modified_Time 对记录进行排序。默认值为 id。请注意,不能将此参数与 cvid 参数一起使用。
- converted字符串,可选
获取已转换记录的列表。
可能的取值:- false(默认)- 仅获取未转换的记录
- true - 仅获取已转换的记录
- both - 获取所有记录。
注意
- page 和 per_page 参数用于根据记录在 CRM 中的位置来获取记录。假设用户需要获取 400 条记录。单次 API 调用可获取的最大记录数为 200 条。因此,超过第 200 条位置的记录无法一次性获取。通过使用 page(1 和 2) 和 per_page(200) 参数,用户可以通过 2 次 API 调用获取全部 400 条记录。
- 如果请求的相关列表在布局中不存在或被隐藏,系统将返回 INVALID_DATA 响应。
示例请求
Copied```bash
curl "https://www.zohoapis.com/crm/v8/Leads/4876876000000376008/Notes?fields=Owner,Parent_Id"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
```Copiedresponse = invokeurl
[
url: "https://www.zohoapis.com/crm/v8/Leads/4876876000000376008/Notes?fields=Owner,Parent_Id"
type: GET
connection:"crm_oauth_connection"
];
info response;响应 JSON 键
- 所有者JSON 对象
表示记录所有者的姓名、ID 和电子邮件。
- Modified_Timestring
关联记录上次被修改的日期和时间。
- Created_Timestring
相关记录创建的日期和时间。
- $editableboolean
表示用户是否可以编辑当前关联记录。
可能的取值:
- true: 用户可以编辑当前关联记录。
- false: 用户不能编辑当前关联记录。
- Modified_ByJSON 对象
包含最后修改相关记录的用户的姓名、ID 和电子邮件。
- idstring
表示相关记录的唯一ID。
- Created_ByJSON 对象
表示创建相关记录的用户的姓名、ID 和电子邮件。
注意
- 上面列出的键适用于所有相关记录。除了上述键之外,响应中还会返回与相关记录特定的键。
- 对于包含敏感健康数据的字段,只有在合规设置中禁用通过 API 限制数据访问选项时,才会返回其值。如果启用了该选项,则 HIPAA 合规字段的值将为 null。有关更多详细信息,请参阅HIPAA 合规性。
示例回复
Copied{
"data": [
{
"Owner": {
"name": "Patricia Boyle",
"id": "4876876000000327001",
"email": "patricia.boyle@zohocorp.com"
},
"Parent_Id": {
"name": "Brian Dylan",
"id": "4876876000000376008"
},
"id": "4876876000001017003"
}
],
"info": {
"per_page": 200,
"next_page_token": null,
"count": 1,
"page": 1,
"previous_page_token": null,
"page_token_expiry": null,
"more_records": false
}
}与 Activities_Chronological_View 相关列表的响应 JSON
Activities_Chronological_View 相关列表按时间顺序排列,提供记录的未完成活动(电话、任务和会议)的详细信息。
在 API 响应中,$module 键用于标识每条相关记录的模块类型(电话、任务或会议),并且所有请求的字段都会包含在响应中。
按时间顺序获取未完成活动的示例请求
Copied```bash
curl "https://www.zohoapis.com/crm/v8/Leads/Leads/554023000003136003/Activities_Chronological_View?fields=Call_Start_Time"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
```示例回答
Copied{
"data": [
{
"Call_Start_Time": "2023-06-25T20:00:00-11:00",
"id": "554023000003136019",
"$module": "通话"
}
],
"info": {
"per_page": 200,
"next_page_token": null,
"count": 1,
"page": 1,
"previous_page_token": null,
"more_records": false
}
}与 Activities_Chronological_View_History 相关列表的响应JSON
Activities_Chronological_View_History 相关列表按时间顺序为您提供该记录的已关闭活动(电话、任务、会议)的详细信息。
在 API 响应中,$module 键用于标识每条相关记录的模块类型(电话、任务或会议),并且所有请求的字段都会包含在响应中。
可能的错误
- INVALID_MODULEHTTP 400
提供的模块名称似乎无效
解决方案: 您指定了无效的模块名称,或者没有选项卡权限,或者该模块已从可用模块中移除。请指定一个有效的模块 API 名称。 - NOT_SUPPORTED HTTP 400
给定的模块在 API 中不受支持
解决方法:诸如 Documents 和 Projects 等模块在当前 API 中不受支持。(一旦这些模块获得支持,此错误将不再显示)。请指定一个有效的模块 API 名称。 - INVALID_URL_PATTERNHTTP 404
请检查尝试访问的 URL 是否正确
解决方法: 请求的 URL 不正确。请指定一个有效的请求 URL。请参阅上方的请求 URL 部分。 - OAUTH_SCOPE_MISMATCHHTTP 401
未授权
解决方法:客户端没有 ZohoCRM.modules.{module_name}.READ 作用域。请创建具有有效作用域的新客户端。请参考上文的作用域部分。 - NO_PERMISSIONHTTP 403
无权读取相关记录
解决方法:用户没有读取相关记录数据的权限。请联系系统管理员。 - INTERNAL_ERRORHTTP 500
内部服务器错误
解决方案:服务器中出现意外且未处理的异常。请联系支持团队。 - INVALID_REQUEST_METHODHTTP 400
HTTP 请求方法类型无效
解决方案:您为访问 API URL 指定了无效的 HTTP 方法。请指定有效的请求方法。参阅上方的端点部分。 - AUTHORIZATION_FAILEDHTTP 400
用户没有足够的权限读取相关记录数据
解决方案:用户没有读取相关记录数据的权限。请联系系统管理员。 - REQUIRED_PARAM_MISSINGHTTP 400
缺少一个预期的参数
解决方法:请指定必填参数。有关更多详细信息,请参阅上面的参数部分。
按时间顺序获取已关闭活动的示例请求
Copied```bash
curl "https://www.zohoapis.com/crm/v8/Leads/554023000003136003/Activities_Chronological_View_History?fields=Status,Call_Start_Time,Owner,Status,Subject"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
```示例回复
Copied{
"data": [
{
"Status": "已完成",
"id": "554023000003140004",
"$module": "任务",
"Subject": "跟进"
}
],
"info": {
"per_page": 200,
"next_page_token": null,
"count": 1,
"page": 1,
"previous_page_token": null,
"more_records": false
}
}