API 事件记录字段引用

API 事件记录中存储的数据的参考表和示例。

当用户调用某个已发布的 API 时，处理 API 调用的网关将创建 API 事件记录。 每个 API 事件记录都包含 API 调用的详细信息，例如应用程序标识，当前时间，结果代码等。 表 1 显示可以包含在 API 事件记录中的所有数据。

活动日志设置

API 事件记录的内容取决于每个 API的活动日志设置，以及配置的任何定制网关脚本和采集过滤器。 要了解有关活动日志记录 和定制 API 事件内容的更多信息，请参阅 定制分析数据。

重要： API 事件记录的最大大小为 19 Mb。 分析子系统拒绝任何大于 19 Mb 的 API 事件记录。

API 事件记录字段

表 1. API 事件记录字段
字段名称 Type 描述
@timestamp 日期 Logstash 数据收集引擎 (将数据提供给 OpenSearch) 写入记录时记录的时间戳记。
ai_cache_hit 布尔值 布尔值，表示响应是否由 AI Gateway 缓存提供
模型 字符串 该人工智能网关呼叫中使用的人工智能模型名称
ai_request_tokens 整数 本次 AI Gateway 调用的请求令牌数量
响应标记 整数 本次 AI Gateway 调用的响应标记数
ai_total_tokens 整数 本次 AI Gateway 调用的令牌总数（请求和响应之和）
api_ref 字符串 应用程序接口引用（api_name:api_version）
api_type 字符串 应用程序接口类型：rest、soap、graphql、asyncapi
api_id 字符串 API 标识。
api_name 字符串 API 的名称。
api_resource_id 字符串 字段格式为: api_name:api_version:method:path。 仅在 API Gateway v10.5.3 或更高版本上可用。
api_version 字符串 API 的版本号。
app_id 字符串 已注册的应用程序的标识。
app_name 字符串 已注册的应用程序的名称。
注: 如果在 API 上未使用客户机标识或客户机标识无效，那么此属性将设置为 undefined 。 网关需要客户机标识来确定哪个应用程序在调用 API。 网关可从此应用程序确定应用程序在包含 API 的产品上预订的计划。 如果没有客户机标识，那么网关无法确定调用了哪些套餐，产品或应用程序，因为单个 API 可以属于多个产品 (每个产品都有多个套餐以及预订了具有客户机标识的那些套餐的应用程序)。
app_type 字符串 应用程序类型，值为 Production 或 Development。
后端方法 字符串 后台调用中使用的 HTTP 方法
后端请求正文 字符串 发送到后台的请求正文
后端请求标头 对象 后端请求的 HTTP 标头
后端响应正文 字符串 来自后台的响应正文
响应头 对象 后台响应的 HTTP 标头
后端状态代码 字符串 后台响应的 HTTP 状态代码
后端服务时间请求 整数 为后台请求提供服务所需的时间
backend_url 字符串 后台调用的完整 URL
billing 对象 对象包含使用货币化的事件的计费信息
bytes_received 编号 从请求中的使用者接收到的字节数。
bytes_sent 编号 在响应中发送到使用者的字节数。
缓存响应 布尔值 布尔值，表示该 API 调用是否由网关缓存提供
client_geoip.area_code 编号 客户机（通过其 IP 地址标识）的公共交换电话网 (PSTN) 区域代码。
client_geoip.asn 编号 客户机 IP 地址的自治系统编号。
client_geoip.as_org 字符串  
client_geoip.city_name 字符串 客户机（通过其 IP 地址标识）所在城市的名称。
client_geoip.continent_name 字符串 客户机的大陆名称 (从其 IP 地址标识)。
client_geoip.continent_code 字符串 客户机（通过其 IP 地址标识）所在洲的代码（两个字母）。
client_geoip.country_code2 字符串 客户机（通过其 IP 地址标识）所在国家或地区的代码（两个字母）。
client_geoip.country_code3 字符串 客户机（通过其 IP 地址标识）所在国家或地区的代码（三个字母）。
client_geoip.country_name 字符串 客户机（通过其 IP 地址标识）所在国家或地区的名称。
client_geoip.dma_code 编号 客户机（通过其 IP 地址标识）的指定市场区域 (DMA) 代码。
client_geoip.domain 字符串 客户机 IP 地址的域。
client_geoip.ip 字符串 客户机的 IP 地址。
client_geoip.isp 字符串 客户机的因特网服务提供者。
client_geoip.latitude 编号 客户机（通过其 IP 地址标识）位置的纬度。
client_geoip.location 字符串 客户机（通过其 IP 地址标识）位置的经度和纬度（以逗号分隔）。
client_geoip.location.lat 编号 客户机（通过其 IP 地址标识）位置的纬度。
client_geoip.location.long 编号 客户机（通过其 IP 地址标识）位置的经度。
client_geoip.longitude 编号 客户机（通过其 IP 地址标识）位置的经度。
client_geoip.organization 字符串 客户机的组织 (从其 IP 地址标识)。
client_geoip.postal_code 字符串 客户机（通过其 IP 地址标识）的邮政编码。
client_geoip.region_iso_code 字符串 客户机区域的 ISO 代码 (从其 IP 地址标识)。
client_geoip.region_name 字符串 与客户机 IP 地址对应的区域的缩写形式。
client_geoip.timezone 字符串 客户机（通过其 IP 地址标识）的时区。
client_id 字符串 附加到 API 请求的客户机的唯一标识。
client_ip 字符串 消费者的 IP 地址
自定义数据 数组映射 可以将定制数据添加到此字段。
datetime 日期 用于记录调用 API 时的时间戳记。 时间戳记始终以全球标准时间显示。
developer_org_id 字符串 拥有该应用程序的使用者组织的标识。
developer_org_name 字符串 拥有该应用程序的使用者组织的名称。
endpoint_url 字符串 当请求失败时， endpoint_url 识别请求失败的代理或调用目标 URL。 成功请求不会随附此 URL。 在兼容 V5 的网关上，只有当调用的后端服务器 URL 返回 HTTP 404 代码时，才会填充此字段。
env_id 字符串 目录标识。
env_name 字符串 目录的名称。
event_id 字符串 网关分配给事件的唯一标识。

使用 SHA1 算法，根据 datetime 、 transaction_id 和 client_id 字段的散列版本合并生成。
gateway_geoip.area_code 编号 网关（通过其 IP 地址标识）的公共交换电话网 (PSTN) 区域代码。
gateway_geoip.asn 编号 客户机 IP 地址的自治系统编号。
gateway_geoip.as_org 字符串  
gateway_geoip.city_name 字符串 网关（通过其 IP 地址标识）所在城市的名称。
gateway_geoip.continent_code 字符串 网关（通过其 IP 地址标识）所在洲的代码（两个字母）。
gateway_geoip.continent_name 字符串 网关的大陆名称 (从其 IP 地址标识)。
gateway_geoip.country_code2 字符串 网关（通过其 IP 地址标识）所在国家或地区的代码（两个字母）。
gateway_geoip.country_code3 字符串 网关（通过其 IP 地址标识）所在国家或地区的代码（三个字母）。
gateway_geoip.country_name 字符串 网关（通过其 IP 地址标识）所在国家或地区的名称。
gateway_geoip.dma_code 编号 网关（通过其 IP 地址标识）的指定市场区域 (DMA) 代码。
gateway_geoip.domain 字符串 网关 IP 地址的域。
gateway_geoip.ip 字符串 网关的 IP 地址。
gateway_geoip.isp 字符串 网关的因特网服务提供者。
gateway_geoip.latitude 编号 网关（通过其 IP 地址标识）位置的纬度。
gateway_geoip.location 字符串 网关（通过其 IP 地址标识）位置的经度和纬度（以逗号分隔）。
gateway_geoip.location.lat 编号 网关（通过其 IP 地址标识）位置的纬度。
gateway_geoip.location.long 编号 网关（通过其 IP 地址标识）位置的经度。
gateway_geoip.longitude 编号 网关（通过其 IP 地址标识）位置的经度。
gateway_geoip.organization 字符串 网关的组织 (从其 IP 地址标识)。
gateway_geoip.postal_code 字符串 网关（通过其 IP 地址标识）的邮政编码。
gateway_geoip.region_name 字符串 与网关 IP 地址对应的区域的缩写形式。
gateway_geoip.region_iso_code 字符串 网关区域的 ISO 代码 (从其 IP 地址标识)。
gateway_geoip.timezone 字符串 网关（通过其 IP 地址标识）的时区。
gateway_host 字符串 网关主机名（不为所有网关类型设置
gateway_ip 字符串 网关的 IP 地址。
gateway_port 整数 网关端口号（并非为所有网关类型都设置）
网关服务名称 字符串 DataPower® API 网关服务的名称。 由云管理用户在注册网关服务时配置。 仅适用于 DataPower API Gateway v10.5.3 或更高版本。
网关服务请求时间 浮点 网关处理此 API 请求所需的时间（提供请求的总时间 - 提供请求的后台时间
网关类型 字符串 处理呼叫的网关类型和版本，格式为 / ： typeversion / 除 v5c 外，所有网关类型都会设置，且仅适用于 v10.0.8.0 或更高版本。
global_transaction_id 字符串 DataPower 全局事务标识。 参见 https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varserviceglobal-transaction-id-servicevarsglobaltransactionid.
graphql_request_field_cost 编号 仅限 GraphQL API。 查询中访问的所有字段的最大成本。 在模式中配置每个字段访问的成本。
graphql_request_max_nesting 编号 仅限 GraphQL API。 组合件验证操作在查询中找到的最大嵌套深度。 模式配置用于确定嵌套的类型，因此此值可能小于组合件解析操作找到的嵌套深度。
graphql_request_top_field_counts 对象 仅限 GraphQL API。 查询可以检索每个字段的最大次数。 此数字等于解析器需要运行的次数。

此字段以 JSON 格式进行存储且不建立索引，因此不可用于可视化。 根据每个条目包含的数据量，为每个条目存储有限数量的查询请求和响应。 可存储的最大数据量可随时进行更改。
graphql_request_top_type_counts 对象 仅限 GraphQL API。 查询可以检索每种类型的对象的最大次数。

此字段以 JSON 格式进行存储且不建立索引，因此不可用于可视化。 根据每个条目包含的数据量，为每个条目存储有限数量的查询请求和响应。 可存储的最大数据量可随时进行更改。
graphql_request_type_cost 编号 仅限 GraphQL API。 在查询中检索到的所有类型的最大成本。 在模式中配置每个类型的成本。
graphql_response_field_cost 编号 仅限 GraphQL API。 查询中访问的所有字段的成本。 在模式中配置每个字段访问的成本。
graphql_response_max_nesting 编号 仅限 GraphQL API。 组合件验证操作在查询中找到的嵌套深度。 模式配置用于确定哪种类型被视为嵌套，因此该值可能小于组合件解析操作所找到的嵌套深度。
graphql_response_top_field_counts 对象 仅限 GraphQL API。 查询检索每个字段的次数。 此数字等于解析器需要运行的次数。

此字段以 JSON 格式进行存储且不建立索引，因此不可用于可视化。 根据每个条目包含的数据量，为每个条目存储有限数量的查询请求和响应。 可存储的最大数据量可随时进行更改。
graphql_response_top_type_counts 对象 仅限 GraphQL API。 查询检索每种类型的对象的次数。

此字段以 JSON 格式进行存储且不建立索引，因此不可用于可视化。 根据每个条目包含的数据量，为每个条目存储有限数量的查询请求和响应。 可存储的最大数据量可随时进行更改。
graphql_response_type_cost 编号 仅限 GraphQL API。 在查询中检索到的所有类型的成本。 在模式中配置每个类型的成本。
主机 字符串 接收 API 事件的摄入节点的主机名或 IP 地址。
http_user_agent 字符串 入站请求的“用户代理”头的值。
immediate_client_ip 字符串 网关正前面的客户机 IP 地址。 通常， immediate_client_ip 是负载均衡器的 IP。
latency_info.started 编号 从接收到请求到网关启动相应任务之间的时间延迟 (以毫秒为单位)。 启动任务包含多个步骤以准备执行 API；例如，完成 TCP/TLS 握手、验证应用程序的客户机标识和秘钥，以及将请求 URI 与目录、API 和计划进行匹配。 当网关接收到请求时， "开始" 持续时间将设置为 0。 然后，将 "启动" 任务中每个步骤的持续时间相加，总数表示 "启动" 任务的持续时间。
latency_info.task 字符串 已处理的 API 事务。
log_policy 字符串 已定义的日志记录策略。 值包括“无”、“事件”、“头”和“有效内容”。
org_id 字符串 拥有该 API 和关联产品的提供者组织的标识。
org_name 字符串 拥有该 API 和关联产品的提供者组织的名称。
opentracing_info 对象 中人工智能测试生成调用的开放跟踪信息 cp4i
操作路径 字符串 与开放式 API 文档中的路径一致的 API 请求路径
path_id 字符串 路径标识符
plan_id 字符串 计划标识。
plan_name 字符串 计划的名称。
注: 如果在 API 上未使用客户机标识或客户机标识无效，那么此属性将设置为 undefined 。 网关需要客户机标识来确定哪个应用程序在调用 API。 网关可从此应用程序确定应用程序在包含 API 的产品上预订的计划。 如果没有客户机标识，那么网关无法确定调用了哪些套餐，产品或应用程序，因为单个 API 可以属于多个产品 (每个产品都有多个套餐和应用程序预订了具有客户机标识的那些套餐)。
plan_version 字符串 计划的版本号。
product_id 字符串 产品标识符
product_name 字符串 产品的名称。
注: 如果在 API 上未使用客户机标识或客户机标识无效，那么此属性将设置为 undefined 。 网关需要客户机标识来确定哪个应用程序在调用 API。 网关可从此应用程序确定应用程序在包含 API 的产品上预订的计划。 如果没有客户机标识，那么网关无法确定调用了哪些套餐，产品或应用程序，因为单个 API 可以属于多个产品 (每个产品都有多个套餐和应用程序预订了具有客户机标识的那些套餐)。
产品参考 字符串 产品参考信息（product_name:product_version）
product_title 字符串 产品的标题。
product_version 字符串 产品的版本号。
query_string 字符串 入站请求的 URL 查询字符串值。
rate_limit.count 编号 在指定的速率限制时间范围内剩余的 API 调用数。
rate_limit.interval 编号 允许一定数量的API调用总时间窗口。
rate_limit.limit 编号 在指定的期限内允许应用程序对 API 发出的最大请求数。
rate_limit.period 编号 用于为 API 调用设置速率限制的期限。
rate_limit.reject 字符串 指示是否拒绝超过指定速率限制的调用。 如果为 true ，那么将拒绝具有 429 状态码的 API 调用。 如果此字段为 false，那么会在“活动”日志中创建一条记录。
rate_limit.shared 字符串 指示是所有操作在计划级别共享速率限制，还是针对个别操作指定速率限制。
rate_limit.unit 编号 用于计算速率限制的时间单位。
备注： 允许的值为秒、分、时、日和周
request_body 字符串 入站请求的主体。
request_http_headers。field_name 字符串 入站请求的 HTTP 头部分的组件；例如，可接受的编码、用户代理程序的标识字符串或用于发送请求的代理。
注: 以下类型的头被视为敏感头，出于安全原因不会显示在分析数据中:
  • API 安全性中配置的任何密钥
  • 包含 secret 的任何头
  • 包含 Authorization 的任何头
request_method 字符串 入站请求的方法。
request_protocol 字符串 入站请求的协议。
资源 字符串 操作的名称。
resource_id 字符串 操作标识。
resource_path 字符串 操作路径。
response_body 字符串 出站响应的主体。
response_http_headers.field_name 字符串 出站响应的 HTTP 头部分的组件；例如，内容的 MIME 类型或发送消息的日期和时间。
作用域 字符串 不用于 DataPower API Gateway 或 DataPower Gateway。
space_id 字符串 发布到空间的产品的空间标识符
space_name 字符串 发布到空间的产品的空间名称
status_code 字符串 出站响应设置的状态码。
time_to_serve_request 编号 网关从收到请求到发出响应所经过的时间（毫秒）。
transaction_id 字符串 API 事务的标识。 参见 https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varservicetransaction-id-servicevarstransactionid.
uri_path 字符串 入站请求的 URI 路径。
user_agent 对象 http_user_agent 字段的解析内容，其中包含发出 API 调用的用户信息。
user_agent.device 字符串 设备名称。
user_agent.major 字符串 用户代理主要版本号。
user_agent.minor 字符串 用户代理次版本号。
user_agent.name 字符串 用户代理名称。
user_agent.os_full 字符串 检测到的操作系统全名。
user_agent.os_major 字符串 检测到的操作系统主要版本号。
user_agent.os_minor 字符串 检测到的操作系统次版本号。
user_agent.os_name 字符串 检测到的操作系统名称。
user_agent.os_patch 字符串 检测到的操作系统补丁版本。
user_agent.os_version 字符串 检测到的操作系统版本。
user_agent.patch 字符串 用户代理补丁版本。
user_agent.version 字符串 检测到用户代理版本。
api_type 字符串 指定与事件相关联的 API 类型。 支持的值有 rest、 soap 和 graphql。
注： v5c gateway 不发送此字段，但 API Gateway 和 Converged Gateway 支持此字段。
注：

  • 为确保 client_geoip 字段中的值准确无误，网关必须在所有 API 调用中接收 X-Forwarded-For 标头。 请与部署环境的管理员联系，以确保 X-Forwarded-For 标头被传递到网关。 例如，在使用 NINGX ingress 的 Kubernetes 环境中，配置网关使用的 NGINX ingress，使其使用 X-Forwarded-For 标头： NGINX 配置 "use-forwarded-headers"。

    geoIP 功能仅对互联网可路由 IP 地址有用。 例如， 192.168.x.x 和 10.x.x.x IP 地址是内部专用 IP 地址，无法解析到地理位置。

  • 并非所有事件都会出现所有字段。 有些字段是特定类型的 API 所特有的，而另一些字段则仅由特定类型或版本的网关发送。

设置了有效内容日志记录的示例 API 事件记录

{
  "@timestamp": "2025-05-26T10:34:12.510174294Z",
  "@version": "1",
  "api_id": "46e6b0fc-58f2-4a58-a47f-0e866c11b1dc",
  "api_name": "findbranch-api",
  "api_ref": "findbranch-api:2.0.0",
  "api_resource_id": "findbranch-api:2.0.0:GET:/details",
  "api_type": "REST",
  "api_version": "2.0.0",
  "app_id": "1faa2b75-20d4-41d4-a2aa-ce363a9c76cf",
  "app_lifecycle_state": "PRODUCTION",
  "app_name": "sandbox-test-app",
  "bytes_received": 0,
  "bytes_sent": 1351,
  "catalog_id": "d22da219-8bd7-407d-923d-af5368b130c4",
  "catalog_name": "sandbox",
  "client_geoip": {},
  "client_id": "136775e010e78dd27afe3d68b63a9789",
  "client_ip": "10.21.34.114",
  "datetime": "2025-05-26T10:34:11.598Z",
  "developer_org_id": "e38a3601-5ceb-4a18-8b8a-3989f4a7fce3",
  "developer_org_name": "sandbox-test-org",
  "developer_org_title": "Sandbox Test Organization",
  "domain_name": "apiconnect",
  "endpoint_url": "N/A",
  "event_id": "3ab419327b3a62e21ed0ac110f9d29259738d5a6",
  "gateway_geoip": {},
  "gateway_ip": "192.168.143.45",
  "gateway_service_name": "v6gw",
  "gateway_type": "apigw/10.6.4.0",
  "global_transaction_id": "65587a59683443a300002432",
  "http_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
  "immediate_client_ip": "10.21.34.114",
  "latency_info": [
    { "started": 0, "task": "Start" },
    { "started": 0, "name": "default-api-route", "task": "api-routing" },
    { "started": 2, "name": "default-api-cors", "title": "default-cors", "task": "api-cors" },
    { "started": 3, "name": "default-wsdl", "title": "default-wsdl", "task": "assembly-wsdl" },
    { "started": 3, "name": "default-html-page", "title": "default-html-page", "task": "assembly-html-page" },
    { "started": 4, "name": "default-api-client-identification", "title": "default-client-identification", "task": "api-client-identification" },
    { "started": 6, "name": "default-api-ratelimit", "title": "default-ratelimit", "task": "assembly-ratelimit" },
    { "started": 11, "name": "default-api-security", "title": "default-security", "task": "api-security" },
    { "started": 13, "name": "default-func-call-preflow", "task": "assembly-function-call" },
    { "started": 13, "name": "default-api-execute", "task": "api-execute" },
    { "started": 13, "name": "sophie-org_sandbox_findbranch-api_2.0.0_invoke_0", "title": "invoke", "task": "assembly-invoke" },
    { "started": 508, "name": "sophie-org_sandbox_findbranch-api_2.0.0_log_0", "title": "log", "task": "assembly-log" },
    { "started": 509, "name": "sophie-org_sandbox_findbranch-api_2.0.0_set-variable_0", "title": "set-variable", "task": "assembly-set-variable" },
    { "started": 510, "name": "sophie-org_sandbox_findbranch-api_2.0.0_set-variable_1", "title": "set-variable", "task": "assembly-set-variable" },
    { "started": 511, "name": "default-func-call-main", "task": "assembly-function-call" },
    { "started": 511, "name": "default-api-result", "task": "api-result" },
    { "started": 512, "name": "default-func-call-global", "task": "assembly-function-call" }
  ],
  "log_policy": "activity",
  "opentracing_info": [],
  "org_id": "127047d3-cdbe-4deb-bad9-69a9de9f7410",
  "org_name": "sophie-org",
  "path_id": "default:2.0.0:GET:/details",
  "plan_id": "findbranch-api-auto-product:2.0.0:default",
  "plan_name": "default",
  "plan_version": "2.0.0",
  "product_id": "8ba4e04b-ae14-41ce-a96c-a175957c698d",
  "product_name": "findbranch-api-auto-product",
  "product_ref": "findbranch-api-auto-product:2.0.0",
  "product_title": "findbranch-api auto product",
  "product_version": "2.0.0",
  "query_string": "",
  "request_body": "",
  "request_http_headers": [],
  "request_method": "GET",
  "request_protocol": "https",
  "resource_id": "default:2.0.0:GET:/findbranch",
  "resource_path": "GET",
  "response_body": "",
  "response_http_headers": [],
  "status_code": "200 OK",
  "tags": ["apicapievent", "send_to_storage_only", "_geoip_lookup_failure"],
  "time_to_serve_request": 513,
  "transaction_id": "9266",
  "uri_path": "/sophie-org/sandbox/findbranch/details",
  "user_agent": {
    "device": "Mac",
    "major": "136",
    "minor": "0",
    "name": "Chrome",
    "os": "Mac OS X",
    "os_full": "Mac OS X 10.15.7",
    "os_major": "10",
    "os_minor": "15",
    "os_name": "Mac OS X",
    "os_patch": "7",
    "os_version": "10.15.7",
    "patch": "0",
    "version": "136.0.0.0"
  }
}