> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据库导出API

当一个项目包含开发、线上等多个环境，且不同环境使用不同数据库时，可以分别创建 SQL 日志查询任务，并通过任务查询接口分页获取 SQL 记录。返回结果中的 `env` 字段用于标识数据所属环境。

## 功能说明

SQL 日志导出包含以下两个接口：

| 接口 | Action | 说明 |
| :- | :- | :- |
| 创建 SQL 日志任务 | `CreateSqlLogTask` | 为指定项目和数据库实例创建 SQL 日志查询任务。 |
| 查询 SQL 日志任务 | `DescribeSqlLogTask` | 查询任务状态，并分页获取任务返回的 SQL 记录。 |

## 接入前提

本文描述 SQL 日志任务的业务协议，不公开内部网关地址和认证凭据。接入方需从正式开放 API 平台请求ACCESS\_TOKEN。若实际开放接口使用其他认证协议，应以开放 API 平台的认证文档为准，不应直接复用内部控制台的 Cookie。

## 请求约定

两个接口均使用 `POST` 方法，请求内容类型为 `application/x-www-form-urlencoded`。业务参数以 JSON 字符串形式写入 `params` 表单字段，返回的数据包含数据库的所有基础数据（数据，auth，文件元数据，定时任务元数据），未提及的不涉及。

## 创建 SQL 日志任务

调用 `CreateSqlLogTask`，为指定项目和数据库实例创建 SQL 日志查询任务。

### 请求示例

执行以下命令，创建 SQL 日志查询任务。请将命令中的占位符替换为实际值。

```text theme={null}
curl --request POST '/database/createSqlLogTask' \ 
  --data-urlencode 'params={"type":"dev","name":"export-project-sql","startTime":1789479821000,"endTime":1789480320000,"filters.1.Key":"query","filters.1.Value":"sql:\"INSERT\"","projectUrlId":"<PROJECT_URL_ID>"}'
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
```

### 业务请求参数

以下参数均位于 `params` JSON 对象中。

| 参数 | 类型 | 是否必填 | 示例值 | 说明 |
| :- | :- | :- | :- | :- |
| `type` | String | 否 | `dev`/prod | 开发环境dev，不传默认导出线上环境prod |
| `name` | String | 是 | `export-project-sql` | 任务名称，用于识别本次查询。 |
| `startTime` | Long | 是 | `1789479821000` | 查询开始时间，使用毫秒级 Unix 时间戳。 |
| `endTime` | Long | 是 | `1789480320000` | 查询结束时间，使用毫秒级 Unix 时间戳，且必须晚于 `StartTime`。 |
| `filters.1.Key` | String | 按查询条件 | `query` | 第一个过滤条件的类型。与 `Filters.1.Value` 配合使用。 |
| `filters.1.Value` | String | 按查询条件 | `sql:"INSERT"` | 第一个过滤条件的表达式。示例表示筛选包含 `INSERT` 的 SQL。完整语法以服务端支持范围为准。 |
| `projectUrlId` | String | 是 | `<PROJECT_URL_ID>` | 项目标识，用于关联项目上下文。接口实现需根据该项目和type返回唯一的数据库表示。 |

### 响应示例

```text theme={null}
{
  "code": "200",
  "data": {
      "status": "INIT",
      "taskId": "<TASK_ID>",
      "start": 1789479821000,
      "createTime": 1789480324000,
      "end": 1789480320000,
      "env": "dev"
  },  
  "httpStatusCode": "200",
  "requestId": "<REQUEST_ID>",
  "successResponse": true
}
```

### 响应参数

| 参数路径 | 类型 | 说明 |
| :- | :- | :- |
| `code` | String | 外层业务状态码。成功时为 `200`。 |
| `data` | Object | 接口业务响应。 |
| `requestId` | String | 内层请求追踪标识。 |
| `data` | Object | 任务创建结果。 |
| `data.status` | String | 任务状态。创建成功后观测到的初始状态为 `INIT`，运行中RUNNING, 成功COMPLETED。 |
| `data.taskId` | String | 任务标识。查询任务时需传入该值。 |
| `data.projectUrlId` | String | 目标项目标识。 |
| `data.start` | Long | 查询开始时间，使用毫秒级 Unix 时间戳。 |
| `data.createTime` | Long | 任务创建时间，使用毫秒级 Unix 时间戳。 |
| `data.end` | Long | 查询结束时间，使用毫秒级 Unix 时间戳。 |
| `data.env` | String | 数据库所属环境。成功响应中应返回非空值，取值来自项目配置；例如，项目可配置为 `dev` 或 `prod`，但示例值不构成固定枚举。 |
| `data.code` | Integer | 内层业务状态码。成功时为 `200`。 |
| `data.success` | Boolean | 内层请求是否成功。 |
| `httpStatusCode` | String | HTTP 状态码的字符串形式。 |
| `requestId` | String | 外层请求追踪标识。排查问题时可记录该值。 |
| `successResponse` | Boolean | 外层请求是否成功。 |

## 查询 SQL 日志任务

调用 `DescribeSqlLogTask`，查询任务状态并分页获取 SQL 记录。

### 请求示例

执行以下命令，查询 SQL 日志任务。请使用创建任务时对应的 `InstanceId`、`projectUrlId` 和返回的 `TaskId`。

```text theme={null}
curl --request POST '/database/describeSqlLogTask' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'params={"taskId":"<TASK_ID>","pageNo":1,"pageSize":10,"projectUrlId":"<PROJECT_URL_ID>"}' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
```

### 业务请求参数

以下参数均位于 `params` JSON 对象中。

| 参数 | 类型 | 是否必填 | 示例值 | 说明 |
| :- | :- | :- | :- | :- |
| `projectUrlId` | String | 是 | `<PROJECT_URL_ID_ID>` | 创建任务时使用的项目标识。 |
| `taskId` | String | 是 | `<TASK_ID>` | `CreateSqlLogTask` 返回的任务标识。 |
| `pageNo` | Integer | 是 | `1` | 查询页码。当前请求示例使用 `1` 表示第一页。 |
| `pageSize` | Integer | 是 | `10` | 每页返回的 SQL 记录数量。支持范围以服务端限制为准。 |

### 响应示例

以下示例表示任务已完成，并返回一条脱敏后的 SQL 记录。

```text theme={null}
{
  "code": "200",
  "data": { 
      "status": "COMPLETED",
      "expire": false,
      "filters": [
        {
          "Value": "or",
          "Key": "logicalOperator"
        }
      ],
      "queries": [
        {
          "executeTime": "2026-09-15T13:51:26.000Z",
          "sqlText": "SELECT * FROM example_table WHERE id = ?",
          "hostAddress": "192.0.2.10",
          "returnRows": 1,
          "sqlId": "<SQL_ID>",
          "updateRows": 0,
          "originTime": 1789480286000,
          "consume": 92,
          "scanRows": 10,
          "threadId": 6524,
          "state": "0",
          "dBName": "example_database",
          "sqlType": "select"
        }
      ],
      "taskId": "<TASK_ID>",
      "start": 1789479821000,
      "taskType": "Query",
      "createTime": 1789480324000,
      "total": 10000,
      "end": 1789480320000,
      "name": "export-project-sql",
      "env": "dev"
    },
  "httpStatusCode": "200",
  "requestId": "<REQUEST_ID>",
  "successResponse": true
}
```

### 响应参数

| 参数路径 | 类型 | 说明 |
| :- | :- | :- |
| `code` | String | 外层业务状态码。成功时为 `200`。 |
| `data` | Object | 接口业务响应。 |
| `data` | String | 响应消息。 |
| `data.requestId` | String | 内层请求追踪标识。 |
| `data` | Object | 任务详情和查询结果。 |
| `data.status` | String | 任务状态。任务完成时为 `COMPLETED`。已观测到 `INIT` 和 `COMPLETED`，完整状态范围以服务端实现为准。 |
| `data.expire` | Boolean | 任务结果是否已过期。`true` 表示结果已过期。 |
| `data.filters` | Array | 任务实际使用的过滤条件。 |
| `data.filters[].Key` | String | 过滤条件名称。 |
| `data.filters[].Value` | String | 过滤条件取值。 |
| `data.queries` | Array | 当前页返回的 SQL 记录。任务未完成或当前页无数据时可能为空数组。 |
| `data.taskId` | String | 任务标识。 |
| `data.start` | Long | 查询开始时间，使用毫秒级 Unix 时间戳。 |
| `data.taskType` | String | 任务类型。当前已知取值为 `Query`。 |
| `data.createTime` | Long | 任务创建时间，使用毫秒级 Unix 时间戳。 |
| `data.total` | Long | 符合条件的 SQL 记录总数。调用方可结合 `PageSize` 计算总页数。 |
| `data.end` | Long | 查询结束时间，使用毫秒级 Unix 时间戳。 |
| `data.name` | String | 任务名称。 |
| `data.env` | String | 当前任务对应的项目环境。成功响应中应返回非空值，取值来自项目配置；示例中的 `dev` 和 `prod` 不构成固定枚举。 |
| `data.code` | Integer | 内层业务状态码。成功时为 `200`。 |
| `data.success` | Boolean | 内层请求是否成功。 |
| `httpStatusCode` | String | HTTP 状态码的字符串形式。 |
| `requestId` | String | 外层请求追踪标识。排查问题时可记录该值。 |
| `successResponse` | Boolean | 外层请求是否成功。 |

`Queries` 数组中每条 SQL 记录包含以下字段：

| 参数路径 | 类型 | 说明 |
| :- | :- | :- |
| `data.queries[].ExecuteTime` | String | SQL 执行时间，采用 ISO 8601 UTC 时间格式。 |
| `data.queries[].SqlText` | String | SQL 文本。SQL 中可能包含业务数据，导出和存储时需采取访问控制和脱敏措施。 |
| `data.queries[].HostAddress` | String | 发起 SQL 请求的客户端地址。 |
| `data.queries[].ReturnRows` | Long | SQL 返回的记录数。 |
| `data.queries[].SqlId` | String | SQL 指纹或 SQL 记录标识。 |
| `data.queries[].UpdateRows` | Long | SQL 更新的记录数。 |
| `data.queries[].OriginTime` | Long | SQL 原始执行时间。根据当前样例判断为毫秒级 Unix 时间戳，正式单位以接口实现为准。 |
| `data.queries[].Consume` | Long | SQL 执行耗时指标。当前材料未提供单位，调用方不应自行换算。 |
| `data.queries[].ScanRows` | Long | SQL 扫描的记录数。 |
| `data.queries[].ThreadId` | Long | 数据库会话或执行线程标识。 |
| `data.queries[].State` | String | SQL 执行状态码。完整取值和含义以服务端实现为准。 |
| `data.queries[].NodeId` | String | 执行 SQL 的数据库节点或实例标识。 |
| `data.queries[].DBName` | String | 数据库名称。 |
| `data.queries[].SqlType` | String | SQL 类型，例如 `select` 或 `set`。完整取值范围以实际 SQL 类型为准。 |
| `data.queries[].AccountName` | String | 执行 SQL 的数据库账号。 |

## 分页与任务状态处理

调用 `DescribeSqlLogTask` 后，应先判断 `datastatus`：

| 状态 | 处理建议 |
| :- | :- |
| `INIT` | 任务已创建但尚未完成。调用方应等待一段时间后再次查询，避免高频轮询。 |
| `COMPLETED` | 任务已完成。读取 `Queries` 和 `Total`，并按需查询后续页面。 |
| RUNNING | 任务运行中 |

当 `Expire` 为 `true` 时，任务结果已过期，原任务通常无法继续提供完整的分页结果。调用方可重新调用 `CreateSqlLogTask` 创建任务；具体处理方式以服务端约定为准。

## 成功判断与问题排查

成功响应同时包含 HTTP 状态、外层业务状态和内层业务状态。调用方建议同时检查以下字段：

* `httpStatusCode` 为 `200`。
* `code` 为 `200`。
* `successResponse` 为 `true`。
* `data.code` 为 `200`。
* `data.success` 为 `true`。

如果任一字段表示失败，应停止解析业务数据，并记录响应中实际存在的追踪标识、任务标识和错误消息。当前材料未提供错误响应样例和完整错误码，因此本文不定义错误码枚举；发布正式 API 参考前，应补充参数错误、无权限、任务不存在、任务过期、限流和服务端错误等异常契约。

## 安全要求

* 不得在请求示例、应用日志、代码仓库或工单中记录真实 Cookie、Token、账号标识和网关地址。
* `sec_token`、Cookie 等认证信息应通过安全配置或密钥管理服务注入，不得硬编码。
* `sqlText`、`hostAddress`、`dBName`、`accountName`、projectUrlId 可能包含敏感信息。导出、传输和存储 SQL 日志时，应实施最小权限控制和必要的脱敏处理。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.