更新事件 API

  • 適用於: Microsoft Defender XDR

注意事項

試試我們使用 MS Graph 安全 API 的新 API。 欲了解更多，請見： 使用 Microsoft Graph 安全 API - Microsoft Graph |Microsoft Learn。 關於使用 MS Graph 安全 API 的新 更新事件 API 資訊，請參見 更新事件。

重要事項

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

API 描述

匯報現有事件的屬性。 可更新的屬性有：status、assignedTotagsdeterminationclassification和。comments

配額、資源分配及其他限制

  1. 你每分鐘最多可以撥打50通電話，或每小時1,500通，才會達到限速門檻。
  2. 只有當 classification 設定為 TruePositive 時，才能設定該determination屬性。

如果你的請求被限速，它會回傳一個 429 回應代碼。 回應主體會顯示你可以開始撥打新電話的時間。

權限

呼叫此 API 需要以下其中一項權限。 欲了解更多，包括如何選擇權限，請參閱「存取 Microsoft Defender 全面偵測回應API」。

權限類型 權限 權限顯示名稱
應用程式 事件。閱讀、寫入、全部 閱讀並寫入所有事件
委託 (工作或學校帳戶) 事件。讀寫 讀寫事件

注意事項

使用使用者憑證取得令牌時，使用者需要有權限在入口網站更新事件。

HTTP 要求

PATCH /api/incidents/{id}

要求標頭

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

要求內文

在請求主體中，提供應更新欄位的值。 未包含在請求實體中的現有屬性會維持其值，除非因相關值變更而必須重新計算。 為了達到最佳效能，你應該省略那些沒有改變的現有數值。

屬性 類型 描述
狀態 Enum 說明事件的當前狀態。 可能的值有：Active、 ResolvedInProgressRedirected和 。
分配給 字串 事件的主謀。
分類 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。 回應實體包含已更新屬性的事件實體。 如果找不到符合指定 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 安全性社群互動: Microsoft Defender 全面偵測回應技術社群。

    • Last updated on