通过

更新事件 API

  • 项目

适用于：

注意

使用 MS Graph 安全 API 试用我们的新 API。 有关详细信息，请查看： 使用 Microsoft Graph 安全 API - Microsoft Graph |Microsoft Learn。 有关使用 MS Graph 安全 API 的新 更新事件 API 的信息，请参阅 更新事件。

重要

某些信息与预发布的产品有关，在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。

API 说明

更新现有事件的属性。 可更新的属性包括：status、、determination、assignedToclassification、tags、 和 comments。

配额、资源分配和其他约束

  1. 在达到限制阈值之前，每分钟最多可以进行 50 个调用或每小时 1,500 个调用。
  2. 仅当 设置为 TruePositive 时classification，才能设置 determination 属性。

如果请求受到限制，它将返回 429 响应代码。 响应正文指示可以开始进行新调用的时间。

权限

要调用此 API，需要以下权限之一。 若要了解详细信息（包括如何选择权限），请参阅 访问 Microsoft Defender XDR API。

权限类型 权限 权限显示名称
应用程序 Incident.ReadWrite.All 读取和写入所有事件
委派（工作或学校帐户） Incident.ReadWrite 读取和写入事件

注意

使用用户凭据获取令牌时，用户需要有权在门户中更新事件。

HTTP 请求

PATCH /api/incidents/{id}

请求标头

名称 类型 说明
Authorization String 持有者 {token}。 必需。
Content-Type String application/json. 必需。

请求正文

在请求正文中，提供应更新的字段的值。 请求正文中未包含的现有属性会保留其值，除非由于相关值的更改而必须重新计算这些属性。 为了获得最佳性能，应省略未更改的现有值。

属性 类型 说明
status 枚举 指定事件的当前状态。 可能的值为： Active、 Resolved、 InProgress和 Redirected。
assignedTo string 事件的所有者。
classification 枚举 事件的规范。 可能的值为： TruePositive (真正) 、 InformationalExpectedActivity (信息、预期活动) 和 FalsePositive (误报) 。
测定 枚举 指定事件的确定。

每个分类的可能确定值为：

  • 真报： MultiStagedAttack (多阶段攻击) 、 MaliciousUserActivity (恶意用户活动) 、 CompromisedAccount (泄露的帐户) – 考虑相应地更改公共 api 中的枚举名称、 Malware (恶意软件) 、 Phishing (钓鱼) 、 UnwantedSoftware (不需要的软件) (和其他 Other) 。
  • 信息性预期活动：SecurityTesting (安全性测试) 、 LineOfBusinessApplication (业务线应用程序) 、 ConfirmedActivity (已确认的活动) - 考虑相应地更改公共 api 中的枚举名称，并 Other (其他) 。
  • 误报：Clean (不是恶意) - 请考虑相应地更改公共 API 中的枚举名称， NoEnoughDataToValidate (没有足够的数据来验证) ，并 Other (其他) 。
    		•
    tags 字符串列表 事件标记列表。
    comment string 要添加到事件的注释。

    注意

    在 2022 年 8 月 29 日左右，以前支持的警报确定值 (“Apt”和“SecurityPersonnel”) 将弃用，不再通过 API 提供。

    响应

    如果成功，此方法返回 200 OK。 响应正文包含具有更新属性的事件实体。 如果未找到具有指定 ID 的事件，该方法将 404 Not Found返回 。

    示例

    请求示例

    下面是请求的示例。

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    请求数据示例

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comment": "pen testing"
}

    提示

    想要了解更多信息？ 在我们的技术社区：Microsoft Defender XDR 技术社区中与 Microsoft 安全社区互动。