创建导出审计日志
审计日志 提供了 Zoho CRM 中用户执行操作的时间顺序记录。
目的
要从您的 Zoho CRM 导出审计日志数据。
这是一个异步 API,系统将安排一个导出作业来导出审计日志的详细信息。导出的审计日志将以 CSV 文件或 ZIP 文件的形式下载。您可以使用 获取导出审计日志作业 Status 的 API 来查看作业的 Status。作业完成后,您可以使用 下载导出审计日志结果 API 下载结果。
端点
- POST /settings/audit_log_export
请求详情
请求 URL
{api-domain}/crm/{version}/settings/audit_log_export
标题
授权: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
作用域 = ZohoCRM.settings.audit_logs.CREATE
一般注意事项
- Users 在 Administrator 配置文件或 CEO Role 中可以访问审计日志。但是,其他 Users 只能查看他们自己及其下属的审计日志。
- 默认情况下,示例请求会导出您在 Zoho CRM 中所有模块过去最多 三年 的审计日志数据。
- 输入请求为可选项,即如果您跳过输入请求,系统仍会导出 Zoho CRM 中的所有操作。
- 使用 用于导出特定审计条目的筛选器,详见下文。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/settings/audit_log_export"
-X POST
-d "@input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"使用单个过滤器导出审计日志的输入 JSON 键
- audit_log_exportJSON array,必填
包含审计日志导出请求的详细信息。
- 条件JSON object,必需
根据特定条件导出数据日志。系统将仅导出与指定条件匹配的数据日志。
- fieldJSON object,必填
表示要筛选的字段。系统将仅根据指定字段导出数据日志。
- api_namestring,必填
表示要筛选字段的 API 名称。
支持的取值:
- action - 根据已在记录上执行的操作筛选条目。
- done_by - 导出由特定组织用户执行的操作日志。
- module - 导出在特定模块上执行的操作日志。
audited_time - 导出在选定时间范围内执行的操作日志。
注意:每个属性支持的比较符及其对应的取值列于下方的表格中。
- comparatorJSON object,必填
表示在导出数据日志的条件中使用的比较运算符。"comparator" 键的值将根据 api_name 中提供的值而变化。
- 支持的比较符:" between", "in", 和 "equal"。
- value(“value” 键的数据类型会根据 “api_name” 键的属性而变化),必填
表示在条件中使用的值。根据该值及其对应的比较运算符,数据日志将被导出。
下表展示了 "api_name" 键中各属性支持的比较符及其对应的取值:
| api_name | 支持的比较符 | 支持的取值 |
|---|---|---|
| action | "equal" 和 "in" | "added"、"updated" 和 "deleted" |
| done_by | "equal" 和 "in" | 指定 Zoho CRM Users 的唯一 ID。 要获取唯一 ID,请使用 GET Users API。 |
| module | "equal" 和 "in" | 使用 GET 模块元数据 API 指定模块 API 名称和唯一 ID。 |
| audited_time | "between" | 在 JSON 数组中指定审计时间范围。 示例 : "2024-07-13T00:00:00+05:30" |
使用单一筛选条件导出审计日志数据的示例输入
Copied{
"audit_log_export": [
{
"criteria": {
"comparator": "between",
"field": {
"api_name": "audited_time"
},
"value": [
"2024-07-13T00:00:00+05:30",
"2024-07-20T23:59:59+05:30"
]
}
}
]
}使用多个筛选条件导出审计日志的输入 JSON 键
- audit_log_exportJSON array,必填
包含审计日志导出请求的详细信息。
- 条件JSON object,必需
根据特定条件导出数据日志。系统将只导出与给定条件匹配的数据日志。
- group_operatorstring(当指定 group 键时,必须包含 group_operator 键。)
表示在条件中使用的组运算符。支持的值:"and"。
- groupJSON array
表示用于导出CRM数据日志的条件组。
- fieldJSON object,必填
表示要筛选的字段。系统将仅根据指定字段导出数据日志。
- api_namestring,必填
表示要筛选字段的 API 名称。要了解支持的取值,请参阅上文的示例输入部分。
- comparatorJSON object,必填
表示在导出数据日志的条件中使用的比较运算符。支持的比较运算符:"between", "in", 和 "equal"。
- value("value" 键的数据类型将根据 "api_name" 键的属性而变化),必填
表示在条件中使用的值。根据该值及其对应的比较运算符,将导出数据日志。
筛选注意事项(单一和多重条件)
- 在不使用筛选条件的情况下,您最多可导出最近3年的审计日志数据。使用筛选条件(单一或多重条件)时,您最多可导出最近6个月(180天)的审计日志数据。请注意,审计的时间范围不应超过180天。
可下载文件的特定注意事项
- 导出的审计日志将根据结果中的条目数量,采用 CSV 或 ZIP 格式。如果审计日志包含 100,000 或更少的条目,系统将自动将日志导出为 CSV 文件。如果有 超过 100,000 条目,日志将被拆分为一个 ZIP 文件内的多个 CSV 文件,每个 CSV 文件最多包含 100,000 条目。
- 最多会在一个 ZIP 文件中导出 10,00,000 条审计条目。
使用多个筛选条件导出审计日志数据的示例输入
Copied{
"audit_log_export": [
{
"criteria": {
"group_operator": "and",
"group": [
{
"field": {
"api_name": "action"
},
"comparator": "equal",
"value": "updated"
},
{
"group_operator": "and",
"group": [
{
"field": {
"api_name": "done_by"
},
"comparator": "in",
"value": [
{
"name": "Kane",
"id": "2276164000000799020"
},
{
"name": "Patricia",
"id": "2276164000000799326"
}
]
},
{
"group_operator": "and",
"group": [
{
"field": {
"api_name": "audited_time"
},
"comparator": "between",
"value": [
"2023-12-05T00:00:00+05:30",
"2024-01-04T23:59:59+05:30"
]
},
{
"field": {
"api_name": "module"
},
"comparator": "in",
"value": [
{
"api_name": "Leads",
"id": "2276164000000000125"
},
{
"api_name": "Contacts",
"id": "2276164000000000129"
}
]
}
]
}
]
}
]
}
}
]
}上述输入表示导出在指定的 时间 和 日期 范围内,潜在客户 和 联系人 模块中由 Patricia 或 Boyle(或两者)更新的审计日志数据的条件。
可能的错误
- INVALID_DATAHTTP 400
- 审计时间范围超出支持的限制
解决方案: 若要导出审计日志,请确保在 "value" JSON 数组 中指定的审计时间范围不超过 180 天。 - 提供的值似乎无效
解决方案:- "group_operator" 键中提供的值似乎无效。支持的值:"and"
- 请为 "comparator" 键指定有效的值。请参阅上面的 示例输入部分。
- 审计时间范围超出支持的限制
- ALREADY_SCHEDULEDHTTP 400
数据日志已安排
解决方案:您可以使用获取导出审计日志作业Status API来查看导出的审计日志的详细信息。 - AMBIGUITY_DURNG_PROCESSINGHTTP 400
处理请求时出现歧义
解决方案: 为模块和 Zoho CRM Users 指定正确的 API 名称和 ID。- 若要获取模块的 API 名称和唯一 ID,请使用 GET Module Metadata API。
- 若要获取 Zoho CRM Users 的唯一 ID,请使用 GET Users API。
- NOT_SUPPORTEDHTTP 400
- EXPECTED_FIELD_MISSINGHTTP 400
缺少一个或多个预期字段
解决方案:“criteria JSON 对象”不应为空。请参阅上面的 示例输入部分。 - DEPENDENT_MISMATCHHTTP 400
条件中的 "value" 键的数据类型似乎无效。
解决方案:请指定有效的数据类型。请参考上面的示例输入部分。 - LIMIT_EXCEEDEDHTTP 400
- MANDATORY_NOT_FOUNDHTTP 400
- 必需的键 "ID" 似乎缺失。
解决方案: 当 "api_name" 的值为 "done_by" 时,必须指定 Zoho CRM Users 的唯一 ID。要获取 Zoho CRM Users 的唯一 ID,请使用 GET Users API。 - 缺少必填字段
解决方案:
- 必需的键 "ID" 似乎缺失。
- DEPENDENT_FIELD_MISSINGHTTP 400
- INVALID_REQUEST_METHODHTTP 400
HTTP 请求方法类型无效
解决方案:您为访问 API 的URL指定了无效的 HTTP 方法。
请指定有效的请求方法。请参阅上面的端点部分。 - OAUTH_SCOPE_MISMATCHHTTP 401
未授权
解决方法: 客户端没有导出 Zoho CRM 审计日志所需的有效作用域。请创建具有有效作用域的新令牌。请参阅上面的作用域部分。 - Authentication_失败HTTP 401
Authentication 失败
解决方案: 在 API 调用的请求头中传递访问令牌。 - NO_PERMISSIONHTTP 403
权限被拒绝
解决方案:请联系系统管理员。 - INVALID_URL_PATTERNHTTP 404
请检查您尝试访问的URL是否正确
解决方案:指定的请求URL不正确。请指定一个有效的请求URL。请参考上面的请求URL部分。 - INTERNAL_ERRORHTTP 500
内部服务器错误
解决方法:服务器中出现了意外且未处理的异常。请联系支持团队。
示例响应
Copied{
"audit_log_export": [
{
"status": "success",
"code": "SCHEDULED",
"message": "ExportAuditlog scheduled successfully.",
"details": {
"id": "2276164000001019012"
}
}
]
}