更新事件 API

  • 發行項

適用於：

注意事項

使用 MS Graph 安全性 API 試用新的 API。 深入瞭解： 使用 Microsoft Graph 安全性 API - Microsoft Graph |Microsoft Learn。 如需使用 MS Graph 安全性 API 的新 更新事件 API 相關信息，請參閱 更新事件。

重要事項

部分資訊與發行前版本產品有關，在正式發行之前可能會實質上進行修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

API 描述

匯報 現有事件的屬性。 可更新的屬性為： status、 determination、 classification、 assignedTo、 tags和 comments。

配額、資源配置和其他條件約束

  1. 在達到節流閾值之前，您每分鐘最多可以撥打 50 次，或每小時撥打 1,500 次。
  2. 只有當 classification 設定為 TruePositive 時，才可以設定 determination 屬性。

如果您的要求已節流，則會傳 429 回回應碼。 回應本文會指出您可以開始進行新呼叫的時間。

權限

呼叫此 API 需要下列其中一個許可權。 若要深入瞭解，包括如何選擇許可權，請參閱存取 Microsoft Defender 全面偵測回應 API。

許可權類型 權限 許可權顯示名稱
應用程式 Incident.ReadWrite.All 讀取和寫入所有事件
委派 (公司或學校帳戶) Incident.ReadWrite 讀取和寫入事件

注意事項

使用使用者認證取得令牌時，用戶必須具有在入口網站中更新事件的許可權。

HTTP 要求

PATCH /api/incidents/{id}

要求標頭

名稱 類型 描述
授權 字串 持有人 {token}。 必要。
Content-Type 字串 application/json。 必要。

要求內文

在要求本文中，提供應更新之欄位的值。 要求本文中未包含的現有屬性會維護其值，除非因為相關值的變更而必須重新計算這些屬性。 為了達到最佳效能，您應該省略未變更的現有值。

屬性 類型 描述
狀態 Enum 指定事件的目前狀態。 可能的值為： Active、 Resolved、 InProgress和 Redirected。
assignedTo 字串 事件的擁有者。
分類 Enum 事件的規格。 可能的值為： TruePositive (為真) 、 InformationalExpectedActivity (信息、預期的活動) ，以及 FalsePositive (誤判) 。
測定 Enum 指定事件的判斷。

每個分類的可能判斷值如下：

  • 確判： MultiStagedAttack (多階段攻擊) 、 MaliciousUserActivity (惡意使用者活動) 、 CompromisedAccount (遭入侵的帳戶) – 請考慮據以變更公用 API 中的列舉名稱、 Malware (惡意代碼) 、 Phishing (網路釣魚) 、 UnwantedSoftware (垃圾軟體) ，以及 Other (其他) 。
  • 信息、預期的活動：SecurityTesting (安全性測試) 、 LineOfBusinessApplication (企業營運應用程式) 、 ConfirmedActivity (已確認的活動) - 請考慮據以變更公用 API 中的列舉名稱， (Other 其他) 。
  • 誤判：Clean (非惡意) - 請考慮據以變更公用 API 中的列舉名稱、 NoEnoughDataToValidate (沒有足夠的數據來驗證) ，以及 Other (其他) 。
    		•
    標記 字串清單 事件標籤清單。
    註解 字串 要新增至事件的批注。

    注意事項

    在 2022 年 8 月 29 日左右，先前支援的警示判斷值 ('Apt' 和 'SecurityPersonnel') 將會被取代，且不再可透過 API 使用。

    回應

    如果成功，這個方法會傳回 200 OK。 回應本文包含具有更新屬性的事件實體。 如果找不到有指定識別碼的事件，則方法會傳回 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"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    提示

    想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：Microsoft Defender 全面偵測回應 技術社群。