API 请求日志

快速阅读

API 请求日志用于回答：

• 外部系统的请求有没有到达呼叫中心开放接口。
• 请求访问了哪个 URI，使用了什么请求方法。
• 请求来自哪个客户端 IP。
• 请求参数是什么，平台返回了什么结果。
• 请求成功还是失败，响应耗时是多少。
• 某个时间窗口内符合条件的请求实际有多少条。

API 请求日志属于操作审计日志大类，是接口访问追溯和联调排障的明细证据。

一、文档说明

1.1 文档目的

本文档说明 API 请求日志的产品定位、记录范围、查询条件、字段口径、导出能力和验收方式，帮助客户在接口联调、接口排障、访问审计和异常追溯时快速定位请求过程。

1.2 文档范围

覆盖外部系统访问呼叫中心开放接口时形成的请求和响应概况，包括请求时间、客户端 IP、URI、参数、请求方法、响应结果、返回内容和响应时长。

不覆盖：

• 平台主动向外部系统发送事件通知形成的事件回调日志。
• 用户在管理端发起的配置、导出、重试等操作日志。
• API 调用量的汇总统计。
• 外部系统内部日志、网关日志和客户侧业务处理日志。

二、产品总览

API 请求日志记录“外部系统访问平台开放接口”的单次请求明细。它主要服务于接口联调、失败排查、慢请求分析、访问审计和调用对账。

一句话理解：

API 请求日志看“外部系统什么时候调了哪个接口，平台如何响应”。

2.1 明细型日志定位

API 请求日志是一条请求一条记录。它适合排查单次异常，但不适合直接替代 API 调用统计做趋势分析。

2.2 与 API 调用统计的关系

API 请求日志记录明细；API 调用统计按企业、IP、日期等维度统计调用次数。发现调用量异常时，回到 API 请求日志查看具体 URI、参数、状态和返回内容。

三、入口与接口口径

3.1 管理端入口

管理端 API 日志页面提供 API 请求日志查询能力，前端查询入口为 API 日志查询能力，并提供实际数量查询能力。

页面可按以下条件查询：

• 请求 IP。
• 请求 URI。
• 请求方式。
• 返回结果。
• 开始时间。
• 结束时间。

从 Monitor 侧证据看，管理端查询会限制较短时间窗口，代码校验为开始时间和结束时间不超过 5 天；前端默认查询近几天数据。开放接口文档则要求开始时间和结束时间不允许跨月。实施时应按实际入口分别说明时间限制，避免用一个时间口径覆盖所有入口。

3.2 开放接口口径

开放接口提供 API 日志查询能力：

• 接口用途：查询接口调用日志。
• 请求方式：GET/POST。
• 查询范围：开始时间和结束时间不允许跨月。
• 分页限制：limit 最大不超过 10000。
• 常用筛选：URI、返回结果、请求方式、客户端 IP、请求参数、开始时间、结束时间。

开放接口还提供实际总数查询能力：

• 适用场景：在分页查询或导出前确认符合条件的真实记录数。
• 返回字段：实际总数。
• 查询条件与 API 请求日志查询保持一致。

四、查询条件

4.1 返回结果口径

后端查询中，响应状态码为 200 视为成功；非 200 视为失败。开放接口文档中返回结果使用成功/失败枚举，页面展示时通常转换为用户可读的成功或失败。

五、字段口径

5.1 页面字段

HOME 字段定义中的 API 日志字段包括：

5.2 后端记录字段

后端 API 访问日志可确认以下字段：

5.3 导出字段

API 请求日志导出字段默认包括：

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

导出时“返回结果”会按状态码转换为成功或失败。

六、查询与导出链路

6.1 查询链路

外部系统发起开放接口请求
→ 平台记录请求时间、IP、URI、参数、方法、状态码、返回内容和耗时
→ 日志进入检索存储
→ 管理端按企业、IP、URI、方法、状态和时间查询
→ 技术人员查看列表或明细返回内容

6.2 详情查询

API 请求日志支持按日志 ID 查询详情，主要用于查看返回内容。为避免一次性加载过大结果，详情查询应在已经定位具体请求后使用。部分入口返回内容会做长度截断，因此不应承诺一定能看到完整响应体。

6.3 导出链路

API 请求日志存在独立下载任务：

• 最大导出 1000000 条。
• 每批查询 1000 条。
• 导出使用滚动查询，完成后会清理查询快照。
• 支持按勾选字段生成 CSV 表头。
• 导出文件名称在不同对象存储环境下可能使用不同语言或命名策略。

导出前建议先用实际总数查询确认数量，避免发起超大导出。

七、典型业务场景

7.1 外部系统反馈接口失败

确认调用方 IP、接口 URI 和时间窗口
→ 查询 API 请求日志
→ 查看状态码、返回内容、请求参数和耗时
→ 与外部系统请求日志对账

排查重点：

• 请求是否到达平台。
• URI 和请求方法是否正确。
• 参数是否完整。
• 状态码是否为成功。
• 返回内容中是否有明确错误描述。

7.2 请求未到达平台

按时间窗口和客户端 IP 查询
→ 若无记录，扩大时间窗口或检查调用方出口 IP
→ 联查调用方网关、网络、签名和域名配置

API 请求日志只能证明平台侧是否记录到请求。若平台侧无记录，需要回到调用方、网络或入口域名侧排查。

7.3 慢请求排查

按 URI 和时间窗口查询
→ 查看响应时长或请求时长
→ 对比同类接口请求
→ 结合 API 调用统计判断是否为集中异常

八、与周边能力的关系

九、权限与安全建议

已确认的权限常量包括：

• API 日志查看权限。
• API 日志导出权限。

建议：

• API 请求日志查看权限仅开放给技术对接人员、实施顾问和授权管理员。
• 导出权限独立控制。
• 请求参数、返回内容可能包含客户号码、账号、业务参数或鉴权相关信息，展示和导出时应遵循脱敏和最小必要原则。
• 对外排障时不要直接转发完整返回内容，应先确认是否包含敏感字段。

十、验收口径

上线或联调时建议验证：

• 成功请求可在 API 请求日志中查到。
• 失败请求可通过状态和返回内容定位原因。
• 按 IP、URI、方法、状态、时间查询可命中预期数据。
• 实际总数接口返回的数量与查询条件一致。
• 导出字段、导出上限和导出权限符合客户要求。
• 敏感请求参数和返回内容的展示边界已确认。

十一、FAQ

Q1：API 请求日志会记录完整请求体和返回内容吗？
现有字段包含请求参数和返回内容，但返回内容可能被截断，实际展示和导出也应按客户安全要求做脱敏或限制。

Q2：API 请求日志能统计某接口调用了多少次吗？
可以通过查询条件和实际总数确认某范围内数量，但趋势和汇总分析应优先看 API 调用统计。

Q3：API 请求失败是否一定是平台问题？
不一定。可能是签名、参数、权限、调用方式、网络、接口路径或平台处理异常，需要结合返回内容和调用方日志判断。

Q4：平台侧没有日志是否代表客户没有调用？
不能绝对说明。可能请求没有到达平台入口、时间窗口不对、出口 IP 不一致或调用到其他环境，需要从调用方链路继续排查。

十二、总结

API 请求日志是开放接口访问追溯的明细能力，用于确认请求是否到达、访问了哪个接口、参数是什么、平台如何响应以及耗时是否异常。它适合接口联调和单次故障定位，趋势分析应与 API 调用统计配合使用。