共用方式為

進階搜捕 API

  • 適用於: Microsoft Defender for Endpoint

警告

此進階搜捕 API 是功能有限的舊版本。 Microsoft Graph 安全性 API 中已經提供可以查詢更多資料表的更全面版本的進階搜捕 API。 請參閱使用 Microsoft Graph 安全性 API 進行進階搜捕

注意事項

如果您是美國政府客戶，請使用適用於美國政府的適用於端點的 Microsoft Defender 客戶中列出的 URI。

提示

為了獲得更好的效能，請使用更靠近您的地理位置的伺服器：

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com
  • aea.api.security.microsoft.com

限制

  1. 您只能對過去 30 天的資料執行查詢。

  2. 結果最多包括 100,000 列。

  3. 每個租用戶的執行次數受到限制：

    • API 呼叫：每分鐘最多 45 次呼叫，每小時最多 1,500 次呼叫。
    • 執行時間：每小時運行時間10分鐘，每天運行時間3小時。

  4. 單一請求的最大執行時間為 200 秒。

  5. 429 response 代表依要求數目或 CPU 達到配額限制。 閱讀回應內文以瞭解已達到的限制。

  6. 單一要求的查詢結果大小上限不能超過 124 MB。 如果超過，則會顯示 HTTP 400 錯誤要求，並顯示訊息「查詢執行已超出允許的結果大小。 透過限制結果數量來優化您的查詢，然後重試」。

權限

需要下列其中一個權限才能呼叫此 API。 若要深入瞭解，包括如何選擇許可權，請參閱 使用適用於端點的 Microsoft Defender API

權限類型 權限 權限顯示名稱
應用程式 AdvancedQuery.讀取.全部 Run advanced queries
委派 (公司或學校帳戶) 進階查詢.Read Run advanced queries

注意事項

使用使用者認證取得權杖時：

  • 使用者必須在 View Data Microsoft Entra ID 中指派角色
  • 使用者必須根據裝置群組設定存取裝置 (如需詳細資訊，請參閱 建立和管理裝置群組)

適用於端點的 Defender 方案 1 和方案 2 支援裝置群組建立。

HTTP 要求

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

要求標頭

頁首 值
授權 持有者 {token}。 必要。
Content-Type 應用程式/json

要求內文

在要求內文中，提供具有下列參數的 JSON 物件：

參數 Type 描述
查詢 Text 要執行的查詢。 必要。

回應

如果成功，這個方法會傳回 200 OK，並在回應本文中傳回 QueryResponse 物件。

範例

請求範例

以下是請求的範例。

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run


{
    "Query":"DeviceProcessEvents |where InitiatingProcessFileName =~ 'powershell.exe' |where ProcessCommandLine contains 'appdata'|project Timestamp, FileName, InitiatingProcessFileName, DeviceId|limit 2"
}

回應範例

以下是回應的範例。

注意事項

為了簡潔起見，此處顯示的回應物件可能會被截斷。 所有屬性都會從實際呼叫傳回。

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

提示

想要深入了解? 在我們的技術社區中與Microsoft安全社區Engage：適用於端點的 Microsoft Defender技術社區。

  • Last updated on