API 调用量统计

快速阅读

API 调用量统计用于回答：

• 哪些企业在某一天产生了较高的开放接口调用量。
• 调用请求主要来自哪些客户端 IP。
• 某个客户端 IP 是否存在异常高频调用。
• 调用量异常时，应如何回到 API 请求日志核对明细。

当前可确认的真实口径是：

按日期、企业编号、客户端 IP 统计开放接口调用次数，并返回调用次数大于 300 的记录。

本文档只描述当前已确认的 API 调用量统计能力，不把成功率、失败率、耗时、接口排行、实时告警或明细下钻写成已交付能力。

一、文档说明

1.1 文档目的

本文档说明 API 调用量统计的产品定位、统计口径、字段含义、使用场景、边界限制和验收方式，帮助客户识别开放接口调用量异常，并建立与 API 请求日志的联查路径。

1.2 文档范围

覆盖：

• API 调用次数统计。
• 日期、企业编号、客户端 IP 维度。
• 高频调用来源识别。
• 与 API 请求日志的人工联查。

不覆盖：

• 单次 API 请求明细。
• API 成功率、失败率、超时率、平均耗时、最大耗时。
• 按 URI、接口名称、应用、AccessKey 的排行分析。
• 事件回调或推送日志的调用量。
• 管理端图表报表、实时监控告警和导出能力。

二、产品定位

API 调用量统计是一项偏运维观测和接口治理的统计能力。它从开放接口访问链路中累计调用次数，用于发现调用量较高的企业和客户端 IP。

一句话理解：

API 调用量统计看“哪天、哪个企业、哪个 IP 调用了多少次开放接口”。

它不是 API 请求日志明细，也不是完整的 API 质量报表。若客户要定位具体失败原因、请求参数、接口 URI 或响应内容，应回到 API 请求日志。

三、核心口径

3.1 统计对象

统计对象是开放接口访问行为，即外部系统主动访问平台开放接口形成的调用。

不纳入本文口径的对象包括：

• 平台主动向外部系统发送的事件回调。
• 管理端用户在页面上的操作。
• 内部服务之间的调试或运行日志。
• 客户外部系统内部的接口转发和业务处理记录。

3.2 统计维度

当前统计维度为：

3.3 返回阈值

当前统计结果只返回调用次数大于 300 的记录。它更适合发现高频调用来源，不适合核对低频请求是否发生。

例如：

• 某 IP 当天调用 500 次，会进入统计结果。
• 某 IP 当天调用 50 次，可能不会出现在统计结果中。
• 是否发生过低频调用，应使用 API 请求日志查询。

3.4 数据属性

当前统计更接近运行态调用计数，不是对 API 请求日志明细的完整离线聚合报表。使用时应注意：

• 它适合做异常发现和治理入口。
• 它不适合作为完整审计账本。
• 多实例、重启、统计刷新等运行因素可能影响完整性。
• 最终排障应以 API 请求日志和客户侧日志共同确认。

四、入口与接口口径

当前可确认的能力是开放接口查询：

• 查询企业每个客户端 IP 调用接口的次数。
• 返回日期、客户端 IP、调用次数、企业编号。
• 返回结果中包含结果数量。

当前未确认：

• 独立管理端菜单页。
• 独立图表看板。
• 独立导出能力。
• 页面级从统计结果一键下钻明细。
• 成功率、失败率、耗时等质量指标。

因此，产品说明和客户沟通时应把它定位为“调用量统计接口”，而不是“API 监控报表”。

五、字段说明

5.1 客户端 IP 的解释

客户端 IP 可能是：

• 客户业务系统的公网出口 IP。
• 客户网关或代理服务器 IP。
• 多层代理转发后形成的 IP 串。
• 测试、压测或脚本调用来源。

当一个字段中出现多个 IP 时，应结合客户网络架构和 API 请求日志共同判断真实来源。

5.2 调用次数的解释

调用次数表示接口访问次数，不直接等于业务成功次数。

以下情况都会提高调用次数：

• 正常业务量增加。
• 客户系统失败后自动重试。
• 定时任务高频轮询。
• 测试脚本、压测脚本或异常程序重复调用。
• 参数错误、签名失败等失败请求重复发生。

六、数据流

外部系统调用开放接口
→ 接口访问链路记录企业编号、客户端 IP 和日期
→ 同一日期、企业、IP 下累计调用次数
→ 统计查询返回调用次数大于 300 的记录
→ 发现异常后按日期、企业、IP 回到 API 请求日志联查

6.1 与 API 请求日志的关系

API 调用量统计和 API 请求日志都来自开放接口访问行为，但用途不同：

调用量统计发现异常后，不能直接判断原因，应回到 API 请求日志查看：

• URI。
• 请求方式。
• 请求参数。
• 返回结果。
• 返回内容。
• 响应时长。

七、功能说明

7.1 高频调用发现

API 调用量统计最核心的用途是发现高频来源。

适合回答：

• 某天是否有企业接口调用量明显偏高。
• 调用量来自一个 IP 还是多个 IP。
• 某个 IP 是否连续多天高频调用。
• 是否可能出现客户侧重试放大。

7.2 调用来源巡检

系统管理员或实施顾问可以定期查看统计结果，与客户确认：

• 这些 IP 是否为客户正式出口。
• 是否有测试 IP 混入生产。
• 是否有代理、网关或中间系统产生集中调用。
• 是否有未知来源访问开放接口。

7.3 异常初筛

API 调用量统计适合作为异常初筛入口，但不能直接给出最终原因。

八、典型业务场景

8.1 客户反馈接口调用量异常

查看 API 调用量统计
→ 定位日期、企业编号、客户端 IP、调用次数
→ 与客户确认 IP 是否为正式出口
→ 回到 API 请求日志按 IP 和日期查询
→ 查看 URI、参数、结果和返回内容
→ 判断是否为业务增长、重试放大或异常脚本

8.2 排查失败重试放大

发现某 IP 调用次数高
→ API 请求日志按 IP、日期、URI 查询
→ 查看同一参数是否短时间重复请求
→ 查看返回结果是否持续失败
→ 与客户确认重试策略和定时任务

8.3 安全与来源巡检

周期性查看高频调用 IP
→ 与客户白名单或备案出口 IP 比对
→ 对非预期 IP 回查 API 请求日志
→ 评估是否需要调整访问策略

九、边界与限制

9.1 不提供质量指标

当前 API 调用量统计不提供：

• 成功率。
• 失败率。
• 超时率。
• 平均耗时。
• 最大耗时。
• 慢请求占比。

如需这些指标，应基于 API 请求日志或监控体系另行设计。

9.2 不提供接口排行

当前统计维度不包含 URI 或接口名称，因此不能直接回答“哪个接口调用量最高”。如果需要接口排行，应从 API 请求日志按 URI 做统计分析。

9.3 不适合低频核对

由于当前只返回调用次数大于 300 的记录，低频调用不会稳定出现在统计结果中。核对某次或某少量请求是否发生，应使用 API 请求日志。

9.4 不替代审计明细

API 调用量统计不能替代 API 请求日志。审计取证时应以请求明细、客户侧日志和必要的业务记录共同确认。

十、与周边能力的关系

十一、权限与安全建议

API 调用量统计可能暴露客户企业编号、访问来源 IP 和调用规模。建议：

• 仅开放给系统管理员、实施顾问、技术对接负责人和授权运营人员。
• 对客户侧 IP、调用次数和异常结论谨慎对外披露。
• 与客户沟通时先说明统计口径和阈值，避免把调用次数解读成业务成功量。
• 对异常 IP 的处置应结合客户白名单、API 请求日志和客户侧日志。

十二、验收口径

交付或使用前建议确认：

• 能返回日期、企业编号、客户端 IP 和调用次数。
• 统计结果只承诺调用次数大于 300 的记录。
• 不承诺成功率、失败率、耗时、接口排行和导出。
• 能按日期、企业编号、客户端 IP 回到 API 请求日志人工联查。
• 客户已理解调用次数不等同于成功次数或业务量。

十三、FAQ

Q1：API 调用量统计是不是 API 请求日志？
不是。API 调用量统计是数量统计，API 请求日志是单次请求明细。

Q2：为什么某个低频 IP 查不到？
当前统计只返回调用次数大于 300 的记录。低频调用应通过 API 请求日志查询。

Q3：调用次数高是否代表接口失败？
不一定。调用次数高可能是业务增长，也可能是重试、轮询、压测或异常脚本，需要联查 API 请求日志判断。

Q4：能不能看成功率和平均耗时？
当前调用量统计不提供成功率和耗时指标。如需分析，应基于 API 请求日志或监控体系另行建设。

Q5：能不能直接导出统计结果？
当前未确认独立导出能力。若客户需要导出，应按实际产品能力或项目方案确认。

十四、总结

API 调用量统计是一项面向开放接口调用来源和调用规模的观测能力。当前真实口径是按日期、企业编号、客户端 IP 返回调用次数大于 300 的记录。它适合发现高频调用和异常来源，但不替代 API 请求日志，也不承诺成功率、耗时、接口排行、页面下钻或导出能力。