進階搜捕 API

適用於：

• 適用於端點的 Microsoft Defender

警告

此進階搜捕 API 是功能有限的舊版。 可查詢更多數據表的更完整進階搜捕 API 版本已可在 Microsoft Graph 安全性 API 中使用。 請參閱 使用 Microsoft Graph 安全性 API 進行進階搜捕

想要體驗適用於端點的 Microsoft Defender 嗎？ 注册免費試用版。

注意事項

如果您是美國政府客戶，請使用 適用於美國政府客戶的 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

限制

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

2. 結果最多包含 100,000 個數據列。

3. 每個租使用者的執行數目有限：

   • API 呼叫：每分鐘最多 45 個呼叫，每小時最多 1,500 個呼叫。
   • 運行時間：每小時 10 分鐘的運行時間，以及一天 3 小時的運行時間。

4. 單一要求的最大運行時間為200秒。

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

6. 單一要求的查詢結果大小上限不能超過 124 MB。 如果超過，HTTP 400 不正確的要求會出現訊息「查詢執行已超過允許的結果大小。 藉由限制結果數目來優化查詢，然後再試一次」。

權限

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

許可權類型	權限	許可權顯示名稱
應用程式	AdvancedQuery.Read.All	Run advanced queries
委派 (公司或學校帳戶)	AdvancedQuery.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	application/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 Graph 安全性 API - Microsoft Graph |Microsoft Learn

• Microsoft適用於端點的 Defender API 簡介

• 從入口網站進階搜捕

• 使用 PowerShell 進階搜尋

提示

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