数据库导出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 日志查询任务。请将命令中的占位符替换为实际值。

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返回唯一的数据库表示。

响应示例

{
  "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。

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 记录。

{
  "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 日志时，应实施最小权限控制和必要的脱敏处理。

接入流程

Agent 专题

API Reference

数据库导出API

功能说明

接入前提

请求约定

创建 SQL 日志任务

请求示例

业务请求参数

响应示例

响应参数

查询 SQL 日志任务

请求示例

业务请求参数

响应示例

响应参数

分页与任务状态处理

成功判断与问题排查

安全要求

​功能说明

​接入前提

​请求约定

​创建 SQL 日志任务

​请求示例

​业务请求参数

​响应示例

​响应参数

​查询 SQL 日志任务

​请求示例

​业务请求参数

​响应示例

​响应参数

​分页与任务状态处理

​成功判断与问题排查

​安全要求

功能说明

接入前提

请求约定

创建 SQL 日志任务

请求示例

业务请求参数

响应示例

响应参数

查询 SQL 日志任务

请求示例

业务请求参数

响应示例

响应参数

分页与任务状态处理

成功判断与问题排查

安全要求