API 调用统计
快速阅读
API 调用统计用于回答：
- 某一天各企业的开放接口调用次数是多少。
- 调用请求主要来自哪些客户端 IP。
- 某企业是否存在调用量异常升高。
- 哪些 IP 可能存在重复调用、重试放大或异常访问。
API 调用统计属于操作审计日志大类，是基于 API 访问行为形成的统计型能力。当前可确认的真实口径是按日期、企业编号、客户端 IP 统计接口调用次数。
一、文档说明
1.1 文档目的
本文档说明 API 调用统计的产品定位、统计口径、字段含义、使用场景和验收方式，帮助客户从整体视角观察开放接口调用量和调用来源。
1.2 文档范围
覆盖 API 调用次数统计，重点包括：
- 日期。
- 企业编号。
- 客户端 IP。
- 调用接口次数。
不覆盖：
- 单次 API 请求的参数、返回内容和耗时明细。
- API 成功率、失败率、超时率、平均耗时等未在当前统计接口中确认的指标。
- 平台主动向外部系统发送事件回调形成的推送量。
- 外部系统内部统计和网关统计。
二、产品总览
API 调用统计对开放接口访问行为进行轻量聚合，帮助客户判断调用量是否符合预期，以及是否存在异常来源 IP。
一句话理解：
API 请求日志看单次请求，API 调用统计看“哪天、哪个企业、哪个 IP 调了多少次”。
2.1 产品定位
API 调用统计是统计型能力，不是明细日志，也不是管理端趋势报表。它适合做调用量巡检、异常发现和治理入口；当发现异常后，需要人工按企业编号、客户端 IP 和日期回到 API 请求日志查询具体 URI、参数、状态和返回内容。
2.2 当前口径边界
当前证据确认的统计接口返回的是调用次数，且仅返回调用次数大于 300 的统计记录；不包含成功率、失败率、平均耗时、最大耗时或接口级分布。因此本文不把这些指标描述为已交付能力。
如果客户需要成功率、失败率或接口维度排行，应基于 API 请求日志另行设计统计视图或报表口径。
三、入口与接口口径
3.1 开放接口口径
开放接口提供接口调用统计数量查询能力：
- 接口用途：查询企业每个 IP 调用接口的次数。
- 请求方式：GET/POST。
- 返回形式：按日期、客户端 IP、调用次数、企业编号返回列表。
- 返回总数：返回当前结果数量。
3.2 与 API 请求日志接口的关系
API 请求日志接口用于查明细，API 调用统计接口用于看汇总调用次数。两者可以按企业编号、客户端 IP 和日期联动：
API 调用统计发现某 IP 调用量异常
→ 使用企业编号、IP 和日期回到 API 请求日志查询
→ 按 URI、方法、状态、参数进一步定位四、统计字段口径
| 字段 | 口径说明 | 使用说明 |
|---|---|---|
| 日期 | 统计日期 | 用于按天查看调用量 |
| 企业编号 | 呼叫中心或企业编号 | 用于识别调用归属 |
| 客户端 IP | API 请求来源 IP | 常见于客户出口 IP、代理 IP 或网关 IP |
| 调用接口次数 | 该日期、企业、IP 下的接口调用次数 | 用于判断调用量规模和异常波动 |
4.1 客户端 IP 说明
客户端 IP 字段可能出现多个 IP 叠加展示，例如代理链路或转发头中包含多个地址。分析时应结合客户实际网络出口、代理配置和 API 请求日志中的 IP 字段判断。
4.2 调用次数说明
调用次数表示统计周期内记录到的接口访问次数。它不直接代表业务成功次数，也不代表有效业务量。
例如：
- 客户系统重复重试会增加调用次数。
- 签名失败、参数错误等失败请求也可能计入调用次数。
- 不同接口的业务含义不同，调用次数不能直接等同于通话量、任务量或客户量。
五、数据流
外部系统调用开放接口
→ 接口访问链路累计企业编号、客户端 IP、日期维度的调用次数
→ 统计接口返回调用次数大于 300 的记录
→ 排查时再按企业编号、客户端 IP、日期回到 API 请求日志核对明细关键说明：
- 统计结果来自接口访问链路的调用计数，不是对 API 请求日志明细的 ES 聚合报表。
- 统计数据偏运行观测口径，不应作为完整持久审计账本使用。
- 统计结果适合观察数量，不适合直接解释失败原因。
- 调用次数异常时，应回到 API 请求日志查看具体接口、参数和返回结果。
六、功能说明
6.1 调用量巡检
可按日期查看企业和 IP 维度的调用量，识别：
- 调用量突然升高。
- 调用量突然下降。
- 非预期 IP 访问。
- 多个 IP 对同一企业集中调用。
6.2 异常来源识别
当某个 IP 调用量明显高于其他来源时，可进一步判断：
- 是否为客户正式出口 IP。
- 是否为测试、压测或脚本调用。
- 是否存在失败重试放大。
- 是否存在多环境同时调用同一企业。
6.3 明细联查
统计结果本身不展示 URI、参数、状态和返回内容，也未确认存在页面级下钻。排查时应按企业编号、客户端 IP 和日期回到 API 请求日志联查：
| 统计异常 | 联查方式 |
|---|---|
| 某 IP 调用量高 | API 请求日志按 IP、日期查询 |
| 某企业调用量异常 | API 请求日志按企业、时间查询 |
| 怀疑重试放大 | API 请求日志按 IP、URI、时间窗口查看重复请求 |
| 怀疑接口失败 | API 请求日志按状态、URI、时间查询 |
七、典型业务场景
7.1 调用量异常升高
查看 API 调用统计
→ 定位异常企业、日期和客户端 IP
→ 按企业编号、IP 和日期联查 API 请求日志
→ 按 URI 和返回结果判断是否为重试、压测或异常调用7.2 客户反馈接口请求量过大
按客户企业编号查看统计结果
→ 对比不同客户端 IP 的调用次数
→ 与客户确认出口 IP 和业务系统
→ 回到 API 请求日志核对具体接口7.3 安全巡检
周期性查看调用统计
→ 识别非预期 IP 或调用量异常 IP
→ 按企业编号、IP 和日期联查 API 请求日志确认 URI 和返回结果
→ 必要时调整开放接口白名单或访问策略八、与周边能力的关系
| 关联能力 | 关系说明 |
|---|---|
| API 请求日志 | 调用统计来自 API 访问行为，异常定位必须人工回到请求明细 |
| 用户操作日志 | 用户操作日志看管理端用户行为，不统计外部系统接口调用量 |
| 事件回调日志 | 事件回调是平台主动推送，不属于外部系统调用平台的 API 调用统计 |
| 开放接口鉴权 | 调用次数异常时，应结合鉴权、签名、IP 和访问策略排查 |
| 监控告警 | 若客户需要实时阈值告警，应在统计口径基础上另行设计监控规则 |
九、运营建议
建议客户和实施团队约定以下运营口径：
- 明确每个客户系统的合法出口 IP。
- 明确接口调用的正常业务峰值。
- 对测试环境、压测环境和生产环境分别管理调用来源。
- 对异常高频调用、非预期 IP、连续失败请求定期复盘。
- 统计异常时，不直接下结论，应结合 API 请求日志和客户侧日志判断。
- 当前统计仅返回调用次数大于 300 的记录，不适合用于核对低频调用是否发生。
十、验收口径
上线或交付时建议验证：
- 能返回日期、客户端 IP、调用次数、企业编号。
- 能识别同一企业下调用次数大于 300 的不同 IP 记录。
- 调用统计能与 API 请求日志按日期、企业和 IP 人工联查。
- 对统计中出现的异常 IP，可在 API 请求日志中找到对应明细。
- 文档和培训中明确当前统计不包含成功率、失败率和耗时指标。
十一、FAQ
Q1：API 调用统计是不是原始日志？
不是。它是统计型能力，不能替代 API 请求日志明细。
Q2：调用次数是否等于成功次数？
不等于。失败、鉴权错误、参数错误、重复重试等请求也可能计入调用次数。
Q3：为什么同一个客户端 IP 字段里有多个 IP？
可能是代理、网关或转发链路中保留了多个地址，需要结合客户网络架构判断真实来源。
Q4：当前能看成功率和平均耗时吗？
当前已确认的统计接口只返回调用次数大于 300 的日期、IP 和企业编号记录。成功率和耗时分析应回到 API 请求日志或另行建设统计指标。
十二、总结
API 调用统计用于从汇总视角观察开放接口调用次数，当前核心口径是按日期、企业编号和客户端 IP 返回调用次数大于 300 的记录。它适合发现异常和做接口治理入口，具体失败原因、参数问题和慢请求仍需人工联查 API 请求日志。
Updated about 2 months ago