安全报告 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

除了在 Apigee 界面中使用安全报告之外，您还可以通过安全报告 API 访问所有安全报告功能。本部分介绍了如何使用安全报告 API。

注意：数据进入 Apigee Analytics 流水线的平均延迟时间为 15 到 20 分钟。因此，结束时间在过去 20 分钟以内的安全报告可能会返回错误的结果。

API 调用示例中的参数

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

ORG 是您的组织。
ENV 是您希望在其中计算报告的环境。
ENVGROUP 是包含环境的环境组。
REPORT_ID 是调用返回的报告 ID，用于创建安全报告。
$TOKEN 是 OAuth 访问令牌的环境变量。
timeRange 是报告的时间范围。

创建安全报告

如需创建安全报告，请输入如下所示的命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

其中，Query.json 是定义查询的查询模板。查询模板的示例如下所示。

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

查询具有以下参数：

指标：
- bot。这用于计算已确定为机器人来源的不同 IP 地址的数量。
  
  聚合函数：count_distinct
- bot_traffic。作为机器人来源的 IP 地址发出的请求总数。
  
  聚合函数：sum
请参阅指标和聚合函数。
维度：ax_resolved_client_ip。此组会按来源的 IP 地址计算报告中的机器人的数量。
请参阅维度。
过滤条件：environment。
groupByTimeUnit：minute
timeRange：last7days。请参阅时间范围。

请注意，此 API 调用会返回与使用 Apigee 界面创建的机器人 IP 地址报告示例相同的报告。

时间范围

报告的时间范围。您可以通过以下任一方式设置 timeRange 字段：

指定报告应扩展到过去多长时间。选项如下：
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
按以下格式指定报告的开始时间和结束时间：
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
start 和 end 都必须是过去的时间，并且最长可比当前创建报告的时间早一年。

示例响应

以上查询会返回如下所示的响应：

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

响应包含以下内容：

报告 ID，您可以在报告完成后使用该报告 ID 获取报告。在上面的示例中，报告 ID 为 3964675e-9934-4398-bff5-39dd93a67201。
"state"：报告作业的状态，可以是以下项之一：
- enqueued：报告作业刚刚创建，但尚未运行。
- running：报告作业正在运行。
- completed：报告作业已完成。在此阶段，您可以查看报告。
- expired：报告作业已过期，您无法再查看报告。

获取报告状态

如需获取报告的状态，请发送如下请求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

其中，REPORT_ID 是报告 ID。请参阅示例 API 调用中的参数。

该响应包含报告参数的摘要以及报告的当前状态。在此示例中，状态为 "completed"，因此您可以查看报告的结果。

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

获取报告

如需下载安全报告，请发送如下请求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

其中，REPORT_ID 是报告 ID。请参阅示例 API 调用中的参数。

这将返回一个包含报告的文件，其名称的格式为 OfflineQueryResult-{ID}.zip。如需查看报告，请执行以下操作：

解压缩 OfflineQueryResult-{ID}.zip。
输入 gzip -d QueryResults-{ID}*.json.gz。
输入 cat QueryResults-{ID}*.json

机器人流量示例

以下示例创建一个 bot_traffic 报告：

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

查询具有以下参数：

指标：bot_traffic。这是每隔一分钟已确定为机器人来源的 IP 地址发出的请求总数。

请参阅指标和聚合函数。
维度：bot_reason。bot_reason 可以是机器人的检测规则的任意组合。检测到机器人时，bot_reason 包含机器人流量模式匹配的检测规则的子集。

请参阅维度。
过滤条件：environment。
groupByTimeUnit：minute
timeRange：last7days

请注意，此 API 调用会返回与使用 Apigee 界面创建的机器人 IP 地址报告示例相同的报告。

聊天机器人检测数据延迟

聊天机器人检测的处理延迟时间平均约为 15 到 20 分钟。

为环境组创建安全报告

使用安全报告 API，您可以为环境组（而不仅仅是环境）中的数据创建报告。为此，请输入如下命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

并确保查询模板 Query.json 包含以下行：

"envgroup_hostname": "ENVGROUP"

其中，ENVGROUP 是包含环境的环境组的名称。您可以通过在 Apigee 界面中转到管理 > 环境 > 组找到环境组的名称。

备注：

环境组级报告 API 仅支持具有聚合函数 sum 的指标 message_count。
环境组级报告 API 不支持维度 bot_reason 或 incident_id，但支持安全报告的所有其他维度。

获取报告状态

如需获取报告的状态，请输入如下所示的命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

该方法返回报告请求的摘要和报告的当前状态。以下是示例响应：

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

由于状态为 "completed"，因此您现在可以查看报告，如下所述。

查看安全报告

如需查看安全报告，请输入如下所示的命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

这将返回一个包含报告的文件，其名称的格式为 OfflineQueryResult-{ID}.zip。如需查看报告，请执行以下操作：

解压缩 OfflineQueryResult-{ID}.zip。
输入 gzip -d QueryResults-{ID}*.json.gz。
输入 cat QueryResults-{ID}*.json

指标和聚合函数

您可以将以下指标和聚合函数用于报告来计算指标的统计信息。

指标	说明	`Aggregation function`
`bot`	每隔一分钟检测到的机器人的不同 IP 地址数量。	`count_distinct`
`bot_traffic`	每隔一分钟检测到的机器人 IP 地址发出的消息数量。	`sum`
`message_count`	Apigee 每隔一分钟处理的 API 调用总数。注意：`message_count` 不能与同一报告中的其他指标结合使用。	`sum`
`response_size`	返回的响应载荷大小（以字节为单位）。	`sum`、`avg`、`min`、`max`
`bot_first_detected`	首次检测到机器人的日期和时间。只能通过 API 获得。	`min`
`bot_last_detected`	上次检测到机器人的日期和时间。只能通过 API 获得。	`max`

维度

利用维度，您可以根据相关的数据子集将指标值归为一组。下表介绍了 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
ax_dn_region
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_family
ax_ua_agent_type
ax_ua_agent_version
ax_ua_agent_category
ax_ua_os_family
bot_reason
client_id
developer
developer_app
developer_email
envgroup_hostname
environment
incident_id（预览）
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

安全报告的限制

请参阅安全报告的限制。