你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

本地管理控制台的警报管理 API 参考

本文列出了 Microsoft Defender for IoT 本地管理控制台支持的警报管理 REST API。

警报（检索警报信息）

使用此 API 可从本地管理控制台检索所有/经过筛选的警报。

URI：/external/v1/alerts 或 /external/v2/alerts

GET

请求

查询参数：

名称	说明	示例	必需/可选
State	仅获取已处理或未处理的警报。 支持的值： - handled - unhandled 所有其他值都被忽略。	/api/v1/alerts?state=handled	可选
fromTime	获取从给定时间开始创建的警报，以毫秒为单位，从 Epoch 时间开始，采用 UTC 时区。	/api/v1/alerts?fromTime=<epoch>	可选
toTime	获取仅在给定时间之前创建的警报，以毫秒为单位，采用 Epoch 时间和 UTC 时区。	/api/v1/alerts?toTime=<epoch>	可选
siteId	在其中发现警报的站点。	/api/v1/alerts?siteId=1	可选
zoneId	在其中发现警报的区域。	/api/v1/alerts?zoneId=1	可选
sensorId	在其中发现警报的传感器。	/api/v1/alerts?sensorId=1	可选

注意

你可能没有站点和区域 ID。 如果是这种情况，请首先查询所有设备以检索站点和区域 ID。 有关详细信息，请参阅本地管理控制台的集成 API 参考（公共预览版）。

响应

类型：JSON

包含以下字段的警报列表：

名称	类型	可为空/不可为 null	值列表
Id	Numeric	不可为 null	-
sensorId	Numeric	不可为 null	-
zoneId	Numeric	不可为 null	-
time	Numeric	不可为 null	采用 Epoch 时间和 UTC 时区的毫秒数
title	字符串	不可为 null	-
message	String	不可为 null	-
severity	字符串	不可为 null	Warning、Minor、Major 或 Critical
engine	字符串	不可为 null	Protocol Violation、Policy Violation、Malware、Anomaly 或 Operational
sourceDevice	Numeric	Nullable	设备 ID
destinationDevice	Numeric	Nullable	设备 ID
remediationSteps	字符串	Nullable	警报中显示的修正步骤
additionalInformation	其他信息对象	Nullable	-
handled	布尔，警报的状态	不可为 null	true 或 false

其他信息字段：

名称	类型	可为空/不可为 null	值列表
description	字符串	不可为 null	-
information	JSON 数组	不可为 null	String

已为 V2 添加：

名称	类型	可为空/不可为 null	值列表
sourceDeviceAddress	String	Nullable	IP 或 MAC 地址
destinationDeviceAddress	String	Nullable	IP 或 MAC 地址
remediationSteps	JSON 数组	不可为 null	字符串，警报中所述的修正步骤
sensorName	字符串	不可为 null	用户定义的传感器的名称
zoneName	字符串	不可为 null	与传感器关联的区域的名称
siteName	字符串	不可为 null	与传感器关联的站点的名称

有关详细信息，请参阅传感器 API 版本参考。

响应示例

[
    {
        "engine": "Operational",
        "handled": false,
        "title": "Traffic Detected on sensor Interface",
        "additionalInformation": null,
        "sourceDevice": 0,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808245000,
        "sensorId": 1,
        "message": "The sensor resumed detecting network traffic on ens224.",
        "destinationDevice": 0,
        "id": 1,
        "severity": "Warning"
    },
    {
        "engine": "Anomaly",
        "handled": false,
        "title": "Address Scan Detected",
        "additionalInformation": null,
        "sourceDevice": 4,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808260000,
        "sensorId": 1,
        "message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
        "destinationDevice": 0,
        "id": 2,
        "severity": "Critical"
    },
    {
        "engine": "Operational",
        "handled": false,
        "title": "Suspicion of Unresponsive MODBUS Device",
        "additionalInformation": null,
        "sourceDevice": 194,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808285000,
        "sensorId": 1,
        "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
        "destinationDevice": 0,
        "id": 3,
        "severity": "Minor"
    }
]

cURL 命令

类型：GET

API：

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

UUID（基于 UUID 管理警报）

使用此 API 对 Defender for IoT 检测到的特定警报执行指定操作。

例如，可以使用此 API 创建一个转发规则，将数据转发到 QRadar。 有关详细信息，请参阅将 Qradar 与 Microsoft Defender for IoT 集成。

URI：/external/v1/alerts/<UUID>

PUT

请求

类型：JSON

查询参数：

名称	说明	示例	必需/可选
UUID	为要处理或要处理并了解的警报定义通用唯一标识符 (UUID)。	/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0	必需

正文参数

名称	说明	示例	必需/可选
action	字符串	handle 或 handleAndLearn	必需

请求示例

{
    "action": "handle"
}

响应

类型：JSON

表示设备的 JSON 对象数组。

响应字段：

名称	类型	必需/可选	说明
content / error	String	必须	如果请求成功，则显示内容属性。 否则，显示错误属性。

可能的内容值：

状态代码	消息	说明
200	警报更新请求已成功完成。	更新请求已成功完成。 无注释。
200	已处理警报 (handle)。	在收到警报处理请求时已处理了警报。 警报将保持 handled 状态。
200	已处理并了解了警报 (handleAndLearn)。	在收到 handleAndLearn 请求时已处理并了解了警报。 警报将保持 handledAndLearn 状态。
200	已处理警报 (handled)。 已处理并了解了警报 (handleAndLearn)。	在收到 handleAndLearn 请求时已处理了警报。 警报变为 handleAndLearn 状态。
200	已处理并了解了警报 (handleAndLearn)。 已忽略处理请求。	在收到警报处理请求时，此警报已处于 handleAndLearn 状态。 警报保持 handleAndLearn 状态。
500	无效操作。	发送的操作不是要对警报执行的有效操作。
500	出现了意外错误。	发生了意外错误。 若要解决此问题，请与技术支持联系。
500	无法执行请求，因为找不到此 UUID 的警报。	在系统中找不到指定的警报 UUID。

响应示例：成功

{
    "content": "Alert update request finished successfully"
}

响应示例：失败

{
    "error": "Invalid action"
}

cURL 命令

类型：PUT

API：

curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

示例：

curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

maintenanceWindow（创建警报排除项）

管理维护时段，在该时段下不会发送警报。 使用此 API 定义和更新停止和开始时间、触发警报时应排除的设备或子网，或者定义或更新应排除的 Defender for IoT 引擎。

例如，在维护时段最好停止发送所有警报，但关键设备上的恶意软件警报除外。

使用 maintenanceWindow API 定义的维护时段将作为只读排除规则显示在本地管理控制台的“警报排除项”窗口中，其命名使用以下语法：Maintenance-{token name}-{ticket ID}。

重要

此 API 仅用于维护目的和有限的时间段，并非用来取代警报排除规则。 仅在一次性的临时维护操作中使用此 API。

URI：/external/v1/maintenanceWindow

POST

创建新的维护时段。

请求

正文参数：

名称	说明	示例	必需/可选
ticketId	字符串。 定义用户系统中的维护工单 ID。 确保票证 ID 未链接到打开的现有时段。	2987345p98234	必需
ttl	正整数。 定义 TTL（生存时间），这是维护时段的持续时间（以分钟为单位）。 定义的时间段结束后，维护时段结束，系统恢复正常运行。	180	必需
engines	字符串的 JSON 数组。 定义要在维护时段从哪个引擎抑制警报。 可能的值： - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	可选
sensorIds	字符串的 JSON 数组。 定义要在维护时段从哪个传感器抑制警报。 可以从设备（管理 OT 传感器设备） API 获取这些传感器 ID。	1,35,63	可选
subnets	字符串的 JSON 数组。 定义要在维护时段抑制警报的子网。 以 CIDR 表示法定义每个子网。	192.168.0.0/16,138.136.80.0/14,112.138.10.0/8	可选

响应

状态代码	消息	说明
201（已创建）	-	操作已成功完成。
400（错误请求）	无 ticketId	API 请求缺少 ticketId 值。
400（错误请求）	非法 TTL	API 请求包括非正的或非数字的 TTL 值。
400（错误请求）	无法分析请求。	分析正文时出现问题，例如不正确的参数或无效值。
400（错误请求）	已存在具有相同参数的维护时段。	当现有维护时段已存在且具有相同详细信息时显示。
404（未找到）	未知传感器 ID	请求中列出的其中一个传感器不存在。
409（冲突）	工单 ID 已有一个打开的窗口。	工单 ID 已链接到另一个打开的维护时段。
500（内部服务器错误）	-	任何其他意外错误。

cURL 命令

类型：POST

API：

curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

示例：

curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

DELETE

关闭现有的维护时段。

请求

查询参数：

名称	说明	示例	必需/可选
ticketId	定义用户系统中的维护工单 ID。 请确保票证 ID 链接到打开的现有时段。	2987345p98234	必需

响应

错误代码：

代码	Message	说明
200（正常）	-	操作已成功完成。
400（错误请求）	无 ticketId	请求中缺少 ticketId 参数。
404（未找到）：	未找到维护时段。	工单 ID 未链接到打开的维护时段。
500（内部服务器错误）	-	任何其他意外错误。

cURL 命令

类型：DELETE

API：

curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

示例：

curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

GET

检索使用此 API 处理维护时段时所执行的所有打开 (POST)、关闭 (DELETE) 和更新 (PUT) 操作的日志。 T

请求

查询参数：

名称	说明	示例	必需/可选
fromDate	筛选预定义日期及以后的日志。 格式为 YYYY-MM-DD。	2022-08-10	可选
toDate	筛选截至预定义日期的日志。 格式为 YYYY-MM-DD。	2022-08-10	可选
ticketId	筛选与特定票证 ID 相关的日志。	9a5fe99c-d914-4bda-9332-307384fe40bf	可选
tokenName	筛选与特定令牌名称相关的日志。	quarterly-sanity-window	可选

错误代码：

代码	Message	说明
200	OK	操作已成功完成。
204：	无内容	没有要显示的数据。
400	错误的请求	日期格式错误。
500	内部服务器错误	任何其他意外错误。

响应

类型：JSON

表示维护时段操作的 JSON 对象数组。

响应结构：

名称	类型	可为空/不可为 null	值列表
id	Long integer	不可为 null	当前日志的内部 ID
dateTime	字符串	不可为 null	活动发生的时间，例如：2022-04-23T18:25:43.511Z
ticketId	字符串	不可为 null	维护时段 ID 例如： 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	String	不可为 null	维护时段令牌名称。 例如： quarterly-sanity-window
engines	字符串数组	Nullable	维护时段适用的引擎，如维护时段创建期间提供的：Protocol Violation、Policy Violation、Malware、Anomaly 或 Operational
sensorIds	字符串数组	Nullable	维护时段适用的传感器，如维护时段创建期间提供的。
subnets	字符串数组	Nullable	维护时段适用的子网，如维护时段创建期间提供的。
ttl	Numeric	Nullable	维护时段的生存时间 (TTL)，如维护时段创建或更新期间提供的。
operationType	字符串	不可为 null	以下值之一：OPEN、UPDATE 和 CLOSE

cURL 命令

类型：GET

API：

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

PUT

允许通过更改 ttl 参数，在启动维护过程后更新维护时段持续时间。 新的持续时间定义将替代之前的定义。

如果要设置比当前配置的持续时间更长的持续时间，此方法就非常有用。 例如，如果最初定义了 180 分钟，而 90 分钟已经过去了，你想要再添加 30 分钟，请将 ttl 更新到 120 分钟以重置持续时间计数。

请求

查询参数：

名称	说明	示例	必需/可选
ticketId	字符串。 定义用户系统中的维护工单 ID。	2987345p98234	必需
ttl	正整数。 定义时段的持续时间（以分钟为单位）。	210	必需

响应

错误代码：

代码	Message	说明
200（正常）	-	操作已成功完成。
400（错误请求）	无 ticketId	请求缺少 ticketId 值。
400（错误请求）	非法 TTL	定义的 TTL 不是数值，也不是正整数。
400（错误请求）	无法分析请求	请求缺少 ttl 参数值。
404（未找到）	未找到维护时段	工单 ID 未链接到打开的维护时段。
500（内部服务器错误）	-	任何其他意外错误。

cURL 命令

类型：PUT

API：

curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

示例：

curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

pcap（请求警报 PCAP）

使用此 API 请求与警报相关的 PCAP 文件。

URI：/external/v2/alerts/

GET

请求

查询参数：

名称	说明	示例	必需/可选
id	来自本地管理控制台的警报 ID	/external/v2/alerts/pcap/<id>	必需

响应

类型：JSON

包含操作状态详细信息的消息字符串：

状态代码	消息	说明
200（正常）	-	JSON 对象，其中包含有关请求的 PCAP 文件的数据。 有关详细信息，请参阅数据字段。
500（内部服务器错误）	找不到警报	在本地管理控制台上找不到提供的警报 ID。
500（内部服务器错误）	获取 xsense ID <number> 的令牌时出错	获取指定传感器 ID 的传感器令牌时出错
500（内部服务器错误）	-	任何其他意外错误。

数据字段

名称	类型	可为空/不可为 null	值列表
id	Numeric	不可为 null	本地管理控制台警报 ID
xsenseId	Numeric	不可为 null	传感器 ID
xsenseAlertId	Numeric	不可为 null	传感器控制台警报 ID
downloadUrl	String	不可为 null	用于下载 PCAP 文件的 URL
token	String	不可为 null	在下载 PCAP 文件时要使用的传感器令牌

响应示例：成功

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

响应示例：错误

{
  "error": "alert not found"
}

cURL 命令

类型：GET

API

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

*示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

后续步骤

有关详细信息，请参阅 Defender for IoT API 参考概述。