3.4.5 数据接口（API）

数据接口把一个数据集包装成一个 HTTP 接口。整体是四步：建分组 → 生成 API（四步向导）→ 发布上线 → 签发凭证并调用。

3.4.5.1 API 分组

功能说明：用分组把接口按业务归类，便于查找和授权；每个 API 必须归属一个分组。

适用场景：接口数量较多时，按业务域（例如「订单分析」「华东销售」）建立分组。

操作步骤

1. 点击「数据服务 > 数据接口（API） > API 分组」。
2. 在「分组名称」中输入关键词（可选），点击「查询」。
3. 点击「创建分组」，填写分组名称后保存。
4. 在「操作」列对分组执行编辑、删除；分组下仍有 API 时建议先迁移再删除。

表52　API 分组的列表字段

列名	含义说明
序号	列表序号
分组名称	分组名称，例如 订单分析、华东销售
创建时间	分组创建时间
操作	编辑、删除

左右滑动查看完整表格

3.4.5.2 API 列表

功能说明：列出当前项目下的全部 API，显示路径、请求方式、所属分组、关联数据集、状态和调用指标，是 API 的日常管理入口。

适用场景：查看某个接口是否已发布；对比各接口的调用量与成功率；进入详情查看接口文档。

操作步骤

1. 点击「数据服务 > 数据接口（API） > API 列表」。
2. 用「关键字（搜索 API 名称 / 路径）」「所属分组」「状态」组合筛选，点击「查询」。
3. 点击「生成 API」开始创建；对已有 API，点击行末「详情」或「编辑」。
4. 需要展开查看时点击「展开」。

表53　API 列表的字段

列名	含义说明
API 名称	接口名称
API Path	调用路径，形如 /api/v1/2/1/aaaaaa，其中 /api/v1/2/1/ 为项目前缀
方式	请求方式，GET / POST
所属分组	该 API 归属的分组
数据集	该 API 取数的数据集
状态	草稿 / 已发布 / 已下线。草稿只能内部联调，已发布才可对外调用
今日调用	当天被调用次数
成功率	调用成功占比，无调用时显示「—」
平均耗时	平均响应耗时，无调用时显示「—」
QPS 上限	该接口允许的最大每秒请求数
备注 / 创建时间	说明文字与创建时间

左右滑动查看完整表格

3.4.5.3 生成 API（四步向导）

点击「生成 API」后，弹窗顶部显示四个步骤：1 基本信息 → 2 定义查询逻辑 → 3 请求/返回参数 → 4 联调测试。

第一步：基本信息

表54　生成 API 第一步的字段

字段	是否必填	填写说明
API 模式	—	接口的生成模式，按页面默认值即可
API 名称	必填	接口的业务名称，例如「每日活跃用户查询」，用于列表展示与识别
API Path	必填	前缀固定为 /api/v1/2/1/（当前项目编号），只需填写后面的路径段，例如 manual_demo
请求方式	必填	GET 或 POST，下拉选择
协议	必填	默认 HTTPS，一般不需要修改
所属分组	必填	选择一个已创建的 API 分组，决定接口归类
描述	选填	接口的业务备注，最多 500 字，建议写清数据口径与更新频率

左右滑动查看完整表格

填写完成后点击「下一步」。

第二步：定义查询逻辑

• 选择数据集（必填）：下拉只列出已发布的数据集，格式为「数据集编号 数据集名称 (来源表)」。
• 字段表格：列出所选数据集的全部字段（字段、别名、类型），可对每个字段设置：是否作为请求参数、是否作为返回参数、返回排序。
• 返回排序：最多可设置 2 个字段，表格中越靠前的字段优先级越高，用于分页以及按时间或指标取数。
• 操作列：字段确定后可执行「输出」，把该字段纳入返回结果。

经验 先把「要返回哪些字段」定下来，再决定「哪些字段允许调用方作为过滤条件」。请求参数越多，接口越灵活，但也越难维护。

第三步：请求/返回参数

这一步决定接口的入参和出参结构：

• 请求参数：如果在第二步没有把任何字段设为请求参数，这里会提示「未勾选请求参数，接口将不接收过滤条件」，即接口只能整表返回，调用方无法按条件过滤。
• 返回参数：逐个字段确认参数名、绑定字段、类型、返回排序、示例值、描述。示例值会出现在接口文档里，建议填写真实格式的样例，方便调用方理解。

表55　返回参数的配置项

字段	说明
参数名	对外暴露的参数名称
绑定字段	对应数据集中的字段
类型	string / number 等
返回排序	参与排序时为排序依据，否则为「不排序」
示例值	文档中展示的样例值
描述	参数含义说明，建议填写

左右滑动查看完整表格

第四步：联调测试并发布

这一步会给出可直接复制的调用命令，并提供在线测试入口：

• 提示语：「联调将按当前配置真实查库。本步点『发布』只生成草稿，列表里再点发布才对外可用。」这句话很重要：向导里的「发布」只是生成草稿，真正对外提供还要回到列表再发布一次。
• 请求信息：给出 curl 示例，调用时需要两个请求头 X-Credential-Id（凭证编号）与 X-Credential-Secret（凭证密钥）。
• 测试参数（JSON）：按请求参数填写 JSON 后点击「发送测试」。
• 响应结果：测试后在此展示返回的 JSON，用于确认字段与数据是否符合预期。

安全提醒 凭证编号与凭证密钥相当于接口的钥匙，不要写在文档、代码仓库或聊天记录里。本手册截图中的凭证已做脱敏处理。

3.4.5.4 API 详情：文档、监控、日志

在 API 列表点击「详情」进入详情页，顶部有三个页签：

表56　API 详情的三个页签

页签	内容	用途
API 文档	名称、编码、路径、方式、分组、数据集、协议、状态、描述，以及「参数定义」（JSON 形式的 request / response 数组，含 name、field、type、desc、example、sort）	把这段 JSON 或页面内容直接给到调用方，就是接口说明
调用监控	今日调用、今日失败、近 24 小时成功率、近 24 小时峰值 QPS、近 24 小时平均耗时、今日配额，以及近 7 日趋势和调用记录	判断接口是否稳定、是否触达配额上限
访问日志	逐条调用流水：时间、API、请求 IP、耗时、结果、请求凭证（脱敏显示）	排查某次调用为什么失败、被谁调用

左右滑动查看完整表格

提示 「今日配额」形如 0 / 500000，前面是当天已用次数，后面是上限。接近上限时调用会受限，需要联系管理员调整。

3.4.5.5 凭证：项目访问凭证（应用授权）

功能说明：签发调用 API 所需的凭证（相当于应用的 AppKey/Secret）。页面顶部明确写着：「项目凭证仅对应当前访问项目（编号：1），切换项目后重新申请。」

适用场景：业务系统要调用本项目的 API 时，先在这里签发一对凭证，再把凭证编号与密钥交给对方。

操作步骤

1. 点击「租户工作台（系统管理） > 应用授权」。
2. 确认右上角当前项目是否正确；凭证与项目绑定，切项目后需重新申请。
3. 点击「签发凭证」，按页面提示填写名称等信息后确认。
4. 在列表中记录「凭证」编号；密钥在签发时提供，请立即妥善保存。
5. 凭证泄露或需要定期更换时使用「轮换」；不再使用时使用「撤销」。

表57　项目访问凭证的字段

列名	含义说明
编号	凭证的系统编号
凭证	凭证标识，调用时作为 X-Credential-Id（截图中已脱敏）
类型	凭证类型，例如「项目业务凭证」
项目	该凭证可访问的项目
到期时间	凭证有效期，到期后需轮换或重新签发
状态	启用 / 停用
操作	轮换（换新密钥）、撤销（立即失效）

左右滑动查看完整表格

注意 「撤销」会让正在使用该凭证的所有调用立即失败，属于高风险操作；操作前请确认下游系统已切换到新凭证。

3.4.5.6 调用日志

功能说明：按时间倒序记录每一次接口调用，用于回溯「谁在什么时候调了哪个接口、耗时多少、是否成功」。

操作步骤

1. 进入「数据服务 > 数据接口（API） > 调用日志」。
2. 按接口、时间或结果筛选后点击「查询」。
3. 在列表中定位异常记录，结合「请求 IP」「请求凭证」判断是哪个调用方。

表58　调用日志的列表字段

列名	含义说明
调用时间	请求发生时间
API	被调用的接口名称
请求 IP	调用方来源 IP
耗时	本次请求的响应耗时，例如 170ms
结果	成功 200 / 失败等状态
请求凭证	本次调用使用的凭证，列表中脱敏显示

左右滑动查看完整表格

3.4.5.7 API 从创建到调用的完整流程

按顺序完成以下 8 步，缺任何一步都会导致「调不通」：

1. 确认数据集可用：数据集存在且已发布，在第二步下拉里能看到它。
2. 建分组：在 API 分组页创建业务分组，API 必须归属一个分组。
3. 生成 API：填写基本信息 → 选择数据集并配置字段 → 确认请求/返回参数。
4. 联调测试：在向导第四步用「发送测试」确认返回数据正确。
5. 生成草稿：点击向导里的「发布」，此时只生成草稿，列表状态为「草稿」。
6. 正式发布：回到 API 列表，对该 API 执行发布，状态变为「已发布」。
7. 签发凭证：在「租户工作台 > 应用授权」签发项目访问凭证，拿到凭证编号与密钥。
8. 调用：业务方用 GET/POST 请求接口地址，并在请求头带上 X-Credential-Id 与 X-Credential-Secret。

最容易漏的一步 向导最后一步的「发布」只产生草稿，必须回到列表再发布一次，接口才真正对外可用。很多「接口 404 / 403」的问题都出在这里。