# 审计日志查询

本页介绍如何通过 API 查询账号级审计日志，支持按时间范围和操作人筛选，适用于排障分析和操作审计取证。

## 接口说明

`GET /public_api/v1/audit_logs`

查询当前 API Key 所属账号的审计日志。

**权限要求：** API Key 需具备 `Audit_Log_Query` 权限。

**限流：** 每个 API Key 每小时最多 60 次请求。

## 查询参数

| 参数        | 类型    | 必填 | 默认值      | 说明                                                                                                                              |
| ----------- | ------- | ---- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `auditType` | String  | 否   | —           | 按操作类型精确匹配，例如 `PLATFORM_API_KEY_CREATED`。                                                                             |
| `operator`  | String  | 否   | —           | 按操作人筛选。可传入 `system`（系统操作）、主账号邮箱、子用户邮箱或 16 位字母数字 appKey。                                        |
| `startTime` | String  | 否   | —           | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS`。不允许早于当前 UTC 日期往前 90 天的 0 点。                                              |
| `endTime`   | String  | 否   | —           | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS`。不得晚于当前时间。                                                                     |
| `_page`     | Integer | 否   | `1`         | 页码，最小值为 1。                                                                                                                |
| `_limit`    | Integer | 否   | `20`        | 每页条数，最小值为 1。                                                                                                            |
| `_sort`     | String  | 否   | `auditTime` | 排序字段。                                                                                                                        |
| `_order`    | String  | 否   | `desc`      | 排序方向，可选值：`asc`、`desc`。                                                                                                 |

::: warning 查询时间范围限制
- 单次查询时间窗口不得超过 90 天。
- `startTime` 不允许早于"当前 UTC 日期往前 90 天的 0 点"，否则返回 `400`。
:::

## 请求示例

使用 API Key 作为 Basic Auth 的用户名，使用 API Secret 作为密码。

```bash
curl -u key:secret -X GET "{api}/audit_logs?startTime=2026-04-15%2016:00:00&endTime=2026-04-22%2016:00:00&operator=system&_page=1&_limit=20"
```

## 响应示例

```json
{
  "items": [
    {
      "auditTime": "2026-04-30 10:30:00",
      "auditType": "PLATFORM_API_KEY_CREATED",
      "ip": "203.0.113.8",
      "description": "Created Platform API Key: xxx.",
      "userType": "api",
      "appKey": "app_k_xxx",
      "subuserID": null,
      "userID": "user_xxx",
      "operator": "app_k_xxx"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "count": 37
  }
}
```

## 响应字段说明

| 字段          | 类型    | 说明                                                                                  |
| ------------- | ------- | ------------------------------------------------------------------------------------- |
| `auditTime`   | String  | 操作时间，格式 `YYYY-MM-DD HH:MM:SS`。                                                |
| `auditType`   | String  | 操作类型。                                                                             |
| `ip`          | String  | 操作来源 IP。                                                                          |
| `description` | String  | 操作描述。                                                                             |
| `userType`    | String  | 操作人类型，枚举值：`system`、`user`（主账号）、`subuser`（子用户）、`api`（API Key）。 |
| `appKey`      | String  | 操作所使用的 API Key，仅 `userType=api` 时有值。                                       |
| `subuserID`   | String  | 子用户 ID，仅 `userType=subuser` 时有值，其余场景为 `null`。                           |
| `userID`      | String  | 账号 ID。                                                                              |
| `operator`    | String  | 操作人展示值：主账号邮箱、子用户邮箱、`system` 或 appKey。                             |

## 错误响应

| HTTP 状态码 | 说明                                             |
| ----------- | ------------------------------------------------ |
| `400`       | 参数校验失败，例如时间格式非法或超出 90 天限制。 |
| `401`       | 未认证，API Key 无效或未提供。                   |
| `403`       | 无权限，API Key 缺少 `Audit_Log_Query` 权限。    |
| `429`       | 请求超出频率限制（每 API Key 每小时 60 次）。    |