# 查询操作日志

按条件分页查询当前身份的操作日志。服务端始终使用请求身份作为日志归属范围；请求中的 `operator_user_id` 不会扩展可查询范围。

```text
GET https://moi.matrixorigin.cn/newmoi/audit/logs
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `operator_user_id` | string | 否 | 兼容查询参数。服务端会以当前请求身份覆盖该值，因此不能据此查询其他用户的日志。 |
| `method` | string | 否 | 按 HTTP 方法筛选。服务端会将输入转换为大写后匹配已记录的方法。 |
| `result` | string | 否 | 按结果筛选。可使用 `success` 或 `failed`；服务端会将输入转换为小写。 |
| `status_code` | integer | 否 | 按 HTTP 状态码精确筛选。仅大于 `0` 的值生效。 |
| `start_time` | string | 否 | 按创建时间筛选的起始时间，使用 RFC 3339 时间格式。 |
| `end_time` | string | 否 | 按创建时间筛选的结束时间，使用 RFC 3339 时间格式。 |
| `page` | integer | 否 | 页码，从 `1` 开始。省略、`0` 或负数时使用 `1`。 |
| `page_size` | integer | 否 | 每页条数。省略、`0` 或负数时使用 `20`；大于 `200` 时按 `200` 处理。 |

## 请求示例

以下示例查询当前身份在指定时间范围内的成功操作日志：

```bash
curl -G "https://moi.matrixorigin.cn/newmoi/audit/logs" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode 'method=POST' \
  --data-urlencode 'result=success' \
  --data-urlencode 'start_time=2026-08-18T00:00:00Z' \
  --data-urlencode 'end_time=2026-08-18T01:00:00Z' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'
```

## 成功响应

成功时返回 HTTP `200`。日志按 `created_at` 降序排列。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "id": "0190e1b6-7fe3-7cc2-9d7f-f589f9d37653",
        "workspace_id": "workspace-123",
        "operator_user_id": "user-123",
        "operator_name_snapshot": "张三",
        "method": "POST",
        "path": "/workflow/v2/workflow-apps",
        "route_pattern": "/workflow/v2/workflow-apps",
        "status_code": 200,
        "result": "success",
        "duration_ms": 35,
        "created_at": "2026-08-18T00:30:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

响应字段如下。

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`data.items[].id` 表示 `data.items` 数组中每一项的 `id` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.items` | object（对象数组） | 本页的操作日志。 |
| `data.total` | integer | 符合筛选条件的日志总数。 |
| `data.page` | integer | 本次响应使用的页码。 |
| `data.page_size` | integer | 本次响应实际使用的每页条数。 |
| `data.items[].id` | string | 日志 ID。 |
| `data.items[].workspace_id` | string | 日志所属工作区 ID。 |
| `data.items[].operator_user_id` | string | 执行操作的用户 ID。 |
| `data.items[].operator_name_snapshot` | string | 记录时保存的操作人名称。 |
| `data.items[].method` | string | HTTP 方法。 |
| `data.items[].path` | string | 实际请求路径。 |
| `data.items[].route_pattern` | string | 路由模板。 |
| `data.items[].query_json` | string | 已记录的查询参数 JSON；无值时省略。 |
| `data.items[].request_body_json` | string | 已记录的请求体 JSON；无值时省略。 |
| `data.items[].response_body_json` | string | 已记录的响应体 JSON；无值时省略。 |
| `data.items[].status_code` | integer | HTTP 状态码。 |
| `data.items[].result` | string | 操作结果，`success` 或 `failed`。 |
| `data.items[].error_code` | string | 错误代码；无值时省略。 |
| `data.items[].error_message` | string | 错误信息；无值时省略。 |
| `data.items[].duration_ms` | integer | 操作耗时，单位为毫秒。 |
| `data.items[].client_ip` | string | 客户端 IP；无值时省略。 |
| `data.items[].user_agent` | string | 客户端 User-Agent；无值时省略。 |
| `data.items[].request_id` | string | 请求 ID；无值时省略。 |
| `data.items[].action_type` | string | 操作类型；无值时省略。 |
| `data.items[].resource_type` | string | 资源类型；无值时省略。 |
| `data.items[].resource_id` | string | 资源 ID；无值时省略。 |
| `data.items[].resource_name` | string | 资源名称；无值时省略。 |
| `data.items[].operation_summary` | string | 操作摘要；无值时省略。 |
| `data.items[].metadata_json` | string | 附加元数据 JSON；无值时省略。 |
| `data.items[].created_at` | string | 日志创建时间。 |

## 错误响应

错误响应使用 `code`、`msg` 和 `data` 包络，`data` 为 `null`。`msg` 为服务端返回的本地化公共错误信息，不应依赖其文本进行程序判断。

```json
{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - `start_time` 或 `end_time` 不是 RFC 3339 时间。
  - 使用完整的 RFC 3339 时间重新发起请求。
* - `500`
  - `ErrTenantDBConnection`
  - 服务无法取得当前工作区的日志存储连接。
  - 稍后重试；持续出现时联系支持人员。
* - `500`
  - `ErrServer`
  - 服务无法读取日志列表。
  - 记录请求时间、HTTP 状态和错误代码后重试；持续出现时联系支持人员。
```