API 管理

千桐科技2025/8/27大约 15 分钟用户手册

功能概览

功能定位

API 管理 是数据服务的服务定义与联调入口，用于把数据库表、SQL 查询或可转发资产配置成可调用的 API，并在同一流程中维护 API 属性、请求参数、返回字段和测试结果。配置完成后的 API 可继续用于应用授权、业务调用和调用记录查看。

简单理解：先在这里定义“接口叫什么、从哪里取数、需要传什么、返回什么”，测试通过后再交给应用使用。

使用建议

开始配置前，先确认【服务分类】、数据源或可转发资产已经准备完成；新增 API 时建议按属性配置 → 参数配置 → 测试 → 返回列表核对 → 详情复测的顺序操作。

主要特性

三步配置：通过“属性配置 → 参数配置 → 测试”向导新增或修改 API。
多种数据来源：支持单表向导式、SQL 脚本式和第三方转发三种参数配置方式。
参数与访问控制：维护请求参数、返回字段、IP 黑名单、限流和 API 状态。
在线验证：在配置向导或详情页测试 API，并查看必填校验、调用失败或成功返回数据。
访问鉴权指引：说明应用身份、API 授权、访问 Token 和业务接口调用之间的关系，并标注历史版本与当前版本的核对边界。

作用范围

【API 管理】用于把数据库表、SQL 查询或可转发资产配置为可调用的 API 服务。上游依赖【服务分类】、数据源、数据库表、SQL 或可转发资产；下游可供应用授权、业务调用和调用记录使用。本页不说明独立【接口测试】页面、SQL 完整保存规则、第三方转发协议、删除结果或状态切换联动。

前置步骤

前置条件

已登录 qData 平台。
当前账号能够访问【数据服务】模块和【API 管理】菜单。
已准备可用的数据源、数据库表、SQL 数据源或可转发资产。
已在【服务分类】中准备 API 所属类目。
已明确 API 名称、地址、版本、请求方式和返回格式。

导航路径

数据服务 > API 管理

页面总览

进入【API 管理】后，左侧显示 API 服务类目搜索框和类目树；页面上方显示查询区；中部显示 API 列表；列表上方提供【新增】；每条记录提供【修改】【详情】【删除】和状态开关。

API 列表字段

字段名	说明	是否必填
编号	当前列表中的 API 记录编号。	不适用（系统展示）
API名称 / 版本号 / 描述	组合展示 API 名称、版本标识和用途说明。	不适用（系统展示）
所属类目	展示 API 所属的服务分类。	不适用（系统展示）
API路径 / 请求类型 / 返回格式	组合展示调用路径、请求方式和响应结构。	不适用（系统展示）
状态	通过开关展示当前 API 状态。	不适用（系统展示）
操作	显示【修改】【详情】【删除】入口。	不适用（系统展示）

列表底部显示记录总数、每页条数和分页控件；本页不说明分页切换后的页面结果。

功能操作说明

查询 API

在左侧类目区域定位并选择目标 API 服务类目。
在“API服务名称”输入框中填写名称关键字。
在“状态”下拉框中选择目标状态。
在“创建时间”中选择查询时间范围。
点击【查询】。
在 API 列表中查看结果。
需要清空查询条件时，点击【重置】。

查询匹配方式和点击【重置】后的刷新时机以页面实际行为为准。

进入 API 配置

新增 API 时，点击列表上方的【新增】。
修改 API 时，点击目标记录右侧的【修改】。

页面顶部显示“属性配置 / 参数配置 / 测试”三步结构。

第一步：配置 API 属性

填写基础属性

在“API类目”中选择所属类目。
在“API名称”中填写服务名称。
在“API地址”中填写调用路径。
在“API版本”中填写版本标识。
在“请求方式”中选择 GET 或 POST。
在“返回格式”中选择当前页面提供的响应结构。
在“描述”中填写 API 用途。

配置访问限制和状态

在“IP黑名单”中填写限制调用来源的 IP 地址。
在“是否限流”中选择“否”或“是”。
启用限流时，设置限流时间窗口。
启用限流时，设置允许请求次数。
在“状态”中选择“下线”或“上线”。
在“备注”中填写补充说明。
点击【下一步】。

属性配置字段

字段名	说明	是否必填
API类目	选择 API 所属服务分类。	是
API名称	填写 API 展示名称。	是
API地址	填写 API 调用路径；页面提示可使用字母、数字、下划线、中划线和斜杠。	是
API版本	填写服务版本标识，例如 `v2.0.0`。	是
请求方式	选择 GET 或 POST。	是
返回格式	选择响应结构；当前页面可见列表、详情、分页示例。	是
描述	填写 API 业务用途，最多 500 个字符。	否
IP黑名单	填写限制调用来源的 IP；多个 IP 使用英文逗号分隔。	否
是否限流	设置是否启用请求频率限制。	页面未定义
限流配置	启用限流后设置时间窗口和允许请求次数。	页面未定义
状态	设置 API 为下线或上线。	页面未定义
备注	填写补充说明，最多 500 个字符。	否

第二步：配置 API 参数

进入“参数配置”步骤后，在“配置方式”中选择单表向导式、SQL 脚本式或第三方转发。

使用单表向导式

配置数据源和数据库表

在“配置方式”中选择“单表向导式”。
在“数据源”中选择目标数据源。
在“数据库表”中选择目标表。

配置请求参数

在“请求参数”区域点击【新增参数】。
在字段弹窗中选择请求参数字段。

点击【确定】。
在请求参数表中设置是否允许为空。
在请求参数表中填写描述。
在请求参数表中选择参数类型。
在请求参数表中填写示例值。
在请求参数表中填写默认值。

配置返回字段

在“返回字段”区域点击【新增参数】。
在字段弹窗中选择返回字段。

点击【确定】。
核对系统形成的返回字段名称。
在返回字段表中填写描述。
在返回字段表中选择数据类型。
数据类型为时间时，设置时间格式。
在返回字段表中填写示例值。
点击【下一步】。

请求参数字段

字段名	说明	是否必填
参数名称	由字段选择或解析结果形成的调用参数名称。	系统形成
是否允许为空	设置调用时是否可以不填写该参数。	页面未定义
描述	填写参数业务含义。	页面未定义
参数类型	选择参数数据类型。	页面未定义
示例值	填写参数示例。	页面未定义
默认值	填写未传值时使用的默认内容。	页面未定义

返回字段

字段名	说明	是否必填
中文名称	由字段选择或解析结果形成的返回字段名称。	系统形成
描述	填写返回字段业务含义。	页面未定义
数据类型	选择返回字段数据类型。	页面未定义
时间格式	数据类型为时间时设置展示格式。	页面未定义
示例值	填写返回字段示例。	页面未定义

使用 SQL 脚本式

在“配置方式”中选择“SQL脚本式”。
在“数据源”中选择目标数据源。
在 SQL 编辑区域输入查询脚本。
点击【SQL解析】。
查看解析后的请求参数区域。
查看解析后的返回字段区域。

本页只说明 SQL 脚本式的数据源、SQL 编辑区和解析入口，不说明完整保存规则、SQL 语法支持范围或解析失败分类。

使用第三方转发

在“配置方式”中选择“第三方转发”。
在“转发类型”中选择“API资产服务”或“地理空间数据”。
在“资产列表”中选择目标资产。
查看请求参数区域。
查看返回参数区域。

第三步：测试 API

发起接口调用

在测试页核对 API 名称、API 版本、请求类型、返回格式和调用地址。
在“请求数据”表中填写参数值。
点击【接口调用】。
在“返回数据”区域查看调用结果。

完成配置

完成参数配置后，点击【下一步】进入测试步骤。
确认测试内容后，点击【确定并测试】。
在 API 列表中查看完成配置后的记录。

完成测试后，页面返回 API 列表。

必填参数校验

当不允许为空的参数未填写时，页面会提示具体参数不能为空。当前页面示例包括“输入参数 station_code 不能为空”和“输入参数 id 不能为空”。

查看调用结果

调用失败时，页面显示“API调用查询结果出错”。
调用成功时，页面显示“接口调用成功”，并在返回数据表格中展示字段和值。

查看 API 详情并再次测试

进入详情页

返回 API 列表并定位目标 API。

点击目标记录右侧的【详情】。

详情页显示 API 描述、创建人、创建时间、更新时间和备注等基础信息，并显示【参数信息】【测试信息】【详细信息】页签。

在详情页测试 API

点击【测试信息】页签。
在请求参数中填写参数值。
点击【接口调用】。
在返回数据区域查看调用结果。

查看【详细信息】页签入口。
操作结束后，点击【返回】。

查看存量 API 维护入口

入口	说明
【修改】	进入三步配置页面调整现有 API。
【详情】	进入 API 详情页查看信息和测试入口。
状态开关	查看当前 API 状态；本页不说明切换结果。
【删除】	查看删除入口；本页不说明删除确认和删除结果。

服务访问与鉴权指引

API 完成配置和页面测试后，还需要为实际调用方建立应用身份和 API 授权关系。当前版本的【应用管理】页面已经确认可查看“应用编号”“应用秘钥”，并可为应用新增 API 授权、设置永久有效或指定有效期。Token 获取接口及参数细节可参考 v1.0.0 API 管理说明，但使用前必须按当前部署环境复核。

鉴权准备流程

进入应用管理，创建或选择用于调用 API 的应用。
进入应用详情，核对应用编号和应用秘钥。
切换到【API授权】页签，为该应用新增目标 API 服务授权。
根据实际需要设置永久有效或指定授权有效期。
核对授权列表中的目标 API 和有效期配置。
通过当前部署环境提供的应用鉴权接口获取访问 Token。
调用业务 API 时携带有效 Token，并使用 API 管理页面确认的请求方式、调用路径和请求参数。

当前版本已确认的范围

当前版本材料已确认应用身份、应用秘钥、API 授权和授权有效期配置。Token 接口地址、凭证参数名称、请求提交格式、Token 携带位置及刷新方式没有在当前视频和 PRD 中展示，应以当前环境的 API 文档或管理员提供的信息为准。

Token 获取参考

用户手册记录的应用鉴权接口如下：

请求方式：POST
历史接口路径：http://<地址>:<端口>/prod-api/oauth2/client_token
用途：使用应用标识和应用密钥获取访问 Token。

请求参数：

参数名	类型	是否必填	v1.0.0 说明
`grant_type`	string	是	固定值为 `client_credentials`。
`client_id`	string	是	应用标识。
`client_secret`	string	是	应用密钥。
`scope`	string	否	用于限定接口访问范围。

主要返回字段：

字段名	类型	v1.0.0 说明
`code`	integer	状态码。历史说明中 200 表示成功、500 表示失败。
`msg`	string	返回消息。
`token_type`	string	Token 类型，历史说明一般为 `bearer`。
`client_token`	string	调用业务 API 时使用的访问 Token。
`expires_in`	integer	Token 有效期，单位为秒。
`client_id`	string	返回的应用标识。
`scope`	string	Token 对应的作用域。

携带 Token 调用业务 API

使用鉴权接口返回的 client_token 作为访问凭证。
按当前环境 API 文档要求，将 Token 放入指定的请求头、查询参数或请求体位置。
使用 API 管理页面展示的 API 路径、请求方式和参数结构发起调用。
如果请求被拒绝，依次核对 Token 是否过期、应用是否已获得目标 API 授权、授权有效期、API 状态、IP 黑名单和限流配置。
需要进一步定位时，在【调用记录】中查看对应调用结果。

常见问题

测试时提示输入参数不能为空，如何处理？
返回“请求数据”区域，为提示中的参数填写参数值，再点击【接口调用】。
API 调用后显示“API调用查询结果出错”，如何处理？
该提示表示本次调用失败。页面未提供更细的错误分类，本页不展开固定排查路径。
独立【接口测试】页面可以测试 API 吗？
当前独立【接口测试】页面显示“功能建设中”。需要测试已配置 API 时，使用 API 管理配置向导的“测试”步骤或 API 详情页的【测试信息】页签。
API 配置和测试完成后，业务系统可以直接调用吗？
还需要在【应用管理】中准备调用应用、配置目标 API 授权及有效期，并按当前环境的鉴权接口获取和携带访问 Token。

总结

【API 管理】用于查询、配置和测试 API，并查看 API 详情。使用时重点核对 API 所属类目、调用路径、请求参数、返回字段、应用授权、访问凭证和测试结果；v1.0.0 Token 接口仅作为历史接入参考，当前部署参数仍需按实际环境确认。