帮你快速理解、总结文档立即下载
文档中心>云防火墙>API 文档>AI安全场景相关接口>查询防火墙告警事件

查询防火墙告警事件

最近更新时间：2026-07-21 01:27:28

我的收藏

本页目录：

1. 接口描述

接口请求域名： cfw.tencentcloudapi.com 。

查询当前租户防火墙聚合告警事件。Response.Data 内 total 表示聚合告警事件数；alerts[].occurrence_count 表示单个聚合告警事件的告警发生次数/命中次数。

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：DescribeCfwAlerts。
Version 是 String 公共参数，本接口取值：2019-09-04。
Region 否 String 公共参数，本接口不需要传递此参数。
StartTime 否 String

告警开始时间。可选，格式 YYYY-MM-DD HH:MM:SS；默认查询最近 1 小时。


示例值：2026-07-09 00:00:00
EndTime 否 String

告警结束时间。可选，格式 YYYY-MM-DD HH:MM:SS；默认当前时间。


示例值：2026-07-09 23:59:59
Level 否 String

告警严重级别过滤。可选；枚举 low、middle、high。


示例值：high
Direction 否 String

流量方向过滤。可选；枚举 outbound 出站、inbound 入站、lateral 横向。


示例值：inbound
ActionStatus 否 String

处置状态过滤。可选；枚举 unhandled、handled、blocked、passed、isolated、ignored。


示例值：blocked
KillChain 否 String

攻击链阶段过滤。可选；枚举 recon、brute_force、delivery、exploit、c2、lateral_movement、exfiltration。


示例值：exploit
AttackResult 否 String

攻击结果过滤。可选；枚举 attempt、success、fail、unknown。


示例值：success
Strategy 否 String

IPS 策略动作过滤。可选；枚举 observe、block。


示例值：block
EventName 否 String

攻击事件名称关键字过滤。可选，例如 SQL注入、暴力破解、恶意域名访问。


示例值：SQL注入
EventId 否 String

精确告警事件 ID 过滤。用于指定事件的写操作前检查和写操作后核验；事件重新聚合时返回原请求 ID 和当前事件 ID。无匹配返回空结果，多匹配或定位过程异常时失败，不退化为宽查询。


示例值：2c1b2a1887a81672b1779791cb4e2c74
SrcIp 否 String

源 IP 过滤。可选。


示例值：1.1.1.1
DstIp 否 String

目的 IP 过滤。可选。


示例值：2.2.2.2
InstanceId 否 String

云资源实例 ID 过滤。可选，例如 ins-xxxxxxxx。


示例值：cdb-i6zh3mwf
Limit 否 Integer

单页返回告警数。可选，默认 10，最大 50。


示例值：10
Offset 否 Integer

分页偏移。可选，默认 0。


示例值：0
OrderBy 否 String

排序字段。可选，默认 EndTime；枚举 EndTime、StartTime、Count。排序字段。可选，默认 EndTime；枚举 EndTime、StartTime、Count；Count 表示按单个聚合告警事件的告警发生次数/命中次数排序，对应返回中的 occurrence_count


示例值：EndTime
Order 否 String

排序方向。可选，默认 desc；枚举 desc、asc。


示例值：desc

3. 输出参数

参数名称 类型 描述
Data String

查询结果。UTF-8 JSON object 字符串；调用方需解析 Response.Data。


示例值：{"alerts":[],"total":0,"returned":0,"offset":0,"order":"desc","order_by":"EndTime","start_time":"2026-07-09 00:00:00","end_time":"2026-07-09 23:59:59","filters":"high,inbound,blocked,SQL注入,1.1.1.1->2.2.2.2"}
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 按时间和命中次数查询告警

StartTime 和 EndTime 限定查询窗口；Count 按 occurrence_count 排序；下一页把 Offset 增加本页 returned。

输入示例

POST / HTTP/1.1
Host: cfw.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeCfwAlerts
<公共请求参数>

{
    "StartTime": "2026-06-01 00:00:00",
    "EndTime": "2026-06-02 00:00:00",
    "OrderBy": "Count",
    "Order": "desc",
    "Limit": 10,
    "Offset": 0
}

输出示例

{
    "Response": {
        "Data": "{\"total\":376,\"returned\":10,\"offset\":0,\"order_by\":\"Count\",\"order\":\"desc\",\"alerts\":[{\"event_id\":\"evt-1\",\"occurrence_count\":138}]}",
        "RequestId": "4266525E-10C4-41E1-8A28-5CCE1FBF6A58"
    }
}

示例2 查询高危阻断告警

按告警级别和处置状态过滤；Response.Data 中 total 是聚合告警事件数，occurrence_count 是单个聚合告警事件的告警发生次数/命中次数。

输入示例

POST / HTTP/1.1
Host: cfw.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeCfwAlerts
<公共请求参数>

{
    "Level": "high",
    "ActionStatus": "blocked",
    "Limit": 10
}

输出示例

{
    "Response": {
        "Data": "{\"total\":376,\"alerts\":[{\"event_id\":\"evt-1\",\"occurrence_count\":138}]}",
        "RequestId": "4266525E-10C4-41E1-8A28-5CCE1FBF6A58"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

错误码 描述
FailedOperation.ResponseTooLarge FailedOperation.ResponseTooLarge
InternalError 内部错误。
InvalidParameter 参数错误。
中国站