安全统计信息 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

您可以使用安全统计信息 API 来查看过去 14 天内与滥用行为和机器人相关的统计信息。安全统计信息有两种类型：

  • 没有时间维度的表格统计信息。表格统计信息通常使用聚合函数计算，例如 sum for message_count 或 bot_traffic。
  • 具有时间维度的时序统计信息。
注意：聊天机器人检测的处理延迟时间平均约为 15 到 20 分钟。

API 调用示例中的参数

以下各部分提供了使用安全统计数据 API 的 API 调用的示例。API 调用包含以下参数：

  • ORG：您的组织。
  • ENV：您的环境。
  • METRIC_i：此统计信息的指标。请参阅指标和聚合函数。
  • AGGREGATION_i：指标的聚合函数。请参见下表。
  • DIMENSION_i：用于对统计信息的值进行分组的维度。
  • PAGE_SIZE：单个页面中返回的子组件数上限。
  • time_range：统计信息的时间范围，格式为 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    其中：

    • START_TIME 是时间范围的开始时间。
    • END_TIME 是时间范围的结束时间。

    START_TIME 和 END_TIME 的格式为 "YYYY-MM-DDT00:00:00Z"。

    时间范围的长度最多为 14 天，开始日期和结束日期都必须在过去 365 天内。

示例：查询环境的表格安全统计信息

查询表格统计信息的请求具有以下格式：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

请参阅 API 调用示例中的参数。

如需了解可以在请求中包含的指标数量上限、聚合函数和维度，请参阅安全统计信息限制。

以下是查询表格统计信息的示例请求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

如需查看请求和响应的说明，请参阅 queryTabularStats 参考页面。

示例：查询环境的时序安全统计信息

时序 API 会返回所选指标的时序统计信息，按所选维度分组。

以下调用会调用按 API 代理分组的机器人流量的时序统计信息。由于有四个代理，因此会生成四个时序点序列。每行的点的顺序与列字段中的对应索引匹配。

以下是请求示例：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

请参阅 API 调用示例中的参数。

如需查看请求和响应的说明，请参阅 queryTabularStats 参考页面。

示例：查询滥用行为检测的事件详情

以下示例查询 Advanced API Security 的滥用行为检测的事件详情。该调用会返回给定事件中 developer_app 的机器人数量的详细信息。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

请参阅 API 调用示例中的参数。

这会返回如下所示的响应：

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

如需查看请求和响应的说明，请参阅 queryTabularStats 参考页面。

指标和聚合函数

下表介绍了安全统计信息 API 中可用的指标和聚合函数：

Metric 说明 Aggregation function
bot 每隔一分钟检测到的机器人的不同 IP 地址数量。 count_distinct
bot_first_detected 首次检测到机器人的日期和时间。只能通过 API 获得。 min
bot_last_detected 上次检测到机器人的日期和时间。只能通过 API 获得。max
bot_traffic 每隔一分钟检测到的机器人 IP 地址发出的消息数量。 sum
message_count

Apigee 每隔一分钟处理的 API 调用总数。

注意：message_count 不能与同一报告中的其他指标结合使用。

 sum
response_size 响应的大小。 average、max、min、sum

维度

利用维度，您可以根据相关的数据子集将指标值归为一组。下表介绍了 Advanced API Security 报告特有的维度：

维度 说明
bot_reason 可以是安全检测规则的任意组合。bot_reason 包含机器人流量模式匹配的检测规则的子集。
incident_id（预览） 安全事件的 UUID，由对 Incidents API 的调用返回。请参阅“示例：获取详细信息或特定突发事件”。
security_action 安全操作。可能的值为 ALLOW、DENY 或 FLAG。
security_action_name 安全操作的名称。
security_action_headers 您可以使用这些标头来查询标记安全操作。

注意：bot_reason 和 incident_id 仅适用于以下指标：

  • bot
  • bot_traffic
  • response_size

除了上述维度之外，Advanced API Security 还支持以下维度：

  • access_token
  • api_product
  • apiproxy
  • app_group_app
  • app_group_name
  • ax_edge_execution_fault_code
  • ax_geo_city
  • ax_geo_continent
  • ax_geo_country
  • ax_geo_region
  • ax_isp
  • ax_resolved_client_ip
  • ax_ua_agent_version
  • client_id
  • developer
  • developer_app
  • developer_email
  • environment
  • is_filtered_out
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

安全统计信息的限制

安全统计信息 API（包括表格和时序）具有以下限制：

  • 页面大小上限：14400
  • 最多 10 个时序维度
  • 最多 15 个表格统计信息维度
  • 最多 5 个指标聚合。
  • 最多 5 个时序指标聚合
  • 时间范围：长度最多为 14 天，且开始日期和结束日期都必须在过去 365 天内。
  • 维度 incident_id 和 bot_reason 不能与指标 message_count 或 response_size 一起使用。
  • 维度 is_filtered_out 仅受表格统计信息支持，并且也适用于旧数据。

比较安全统计信息 API 和安全报告 API

安全统计信息 API 和安全报告 API 均返回与滥用行为和机器人相关的安全统计信息，但它们存在以下差异：

  • 安全统计信息 API 旨在查看近期 API 流量的统计信息。安全统计信息 API 的数据只能追溯到 14 天前，但是您可以在发送请求后立即查看统计信息。

    安全统计信息也会显示在 Apigee 界面的滥用行为指标视图中。

  • 安全报告 API 旨在查看长时间运行的操作的统计信息。如需使用安全得分 API，您可以提交作业并仅在作业完成时查看结果。安全得分 API 的数据可追溯到一年前。