安全统计信息 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
access_token
api_product
apiproxy
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
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 一起使用。

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

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

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

安全统计信息也会显示在 Apigee 界面的滥用行为指标视图中。
安全报告 API 旨在查看长时间运行的操作的统计信息。如需使用安全得分 API，您可以提交作业并仅在作业完成时查看结果。安全得分 API 的数据可追溯到一年前。