Zoho crm Logo

创建导出审计日志

审计日志 提供了 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" 
请注意,审计时间范围不应超过 180 天。

使用单一筛选条件导出审计日志数据的示例输入

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。

  • NOT_SUPPORTEDHTTP 400
    • 在 "field JSON object" 的 "api_name" 键中提供的值不受支持 
      解决方案:指定一个有效的值。请参阅支持的值。
    • 在 "criteria JSON object" 的 "value" 键中提供的值不受支持
      解决方案:指定一个有效的值。请参阅上面的示例输入部分。
  • EXPECTED_FIELD_MISSINGHTTP 400

    缺少一个或多个预期字段 
    解决方案:“criteria JSON 对象”不应为空。请参阅上面的 示例输入部分。

  • DEPENDENT_MISMATCHHTTP 400

    条件中的 "value" 键的数据类型似乎无效。
    解决方案:请指定有效的数据类型。请参考上面的示例输入部分。

  • LIMIT_EXCEEDEDHTTP 400
    • "audit_log_export" JSON 数组的大小已超过允许的限制
      解决方法:请在允许的范围内指定"audit_log_export" JSON 数组。支持的上限为1。有关示例 JSON 结构,请参阅上方的示例输入部分。
    • "group" JSON 数组的大小已超过允许的限制
      解决方法:请在给定的范围内指定"group" JSON 数组。支持的上限为2。 请参阅上方的示例输入部分。
  • MANDATORY_NOT_FOUNDHTTP 400
    • 必需的键 "ID" 似乎缺失。
      解决方案: 当 "api_name" 的值为 "done_by" 时,必须指定 Zoho CRM Users 的唯一 ID。要获取 Zoho CRM Users 的唯一 ID,请使用 GET Users API。
    • 缺少必填字段
      解决方案:
      • 给定的条件似乎为空。请在条件中指定有效的值。参见上面的 示例输入部分。
      • 字段 JSON 对象中缺少 "api_name" 键。请确保包含带有有效值的 "api_name" 键。
      • 提供了一个或多个筛选器但没有相应的条件。请为每个筛选器指定有效的条件。参见上面的 示例输入部分。
      • "field" JSON 对象中的 "api_name" 不应为空。参见上面的 示例输入部分。
  • DEPENDENT_FIELD_MISSINGHTTP 400

    缺少依赖键 
    解决方案:

    • 当你包含用于应用多个筛选器的 group JSON array 时,请指定 group_operator 键,反之亦然。 请参阅上面的 示例输入部分。
    • 当你包含 "field JSON object" 时,请指定 "comparator" 和 "value" 键,反之亦然。请参阅上面的 示例输入部分。
  • 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"
            }
        }
    ]
}