依定義取得掃描歷程記錄

發行項
05/03/2024

適用於：

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

想要體驗 Microsoft Defender 弱點管理嗎？瞭解如何註冊免費試用版。

重要事項

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

注意事項

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

API 描述

依定義擷取掃描記錄的清單。

支援 OData 作業。
OData 支援的運算子：
- $top最大值為 4096。傳回要求中指定的會話數目。
- $skip預設值為 0。略過要求中指定的會話數目。

如需 OData 作業使用方式的範例，請參閱範例$top要求。

限制

此 API 的速率限制為每分鐘 100 次呼叫，每小時 1500 次呼叫。

權限

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

許可權類型	權限	許可權顯示名稱
應用程式	Machine.Read.All	讀取所有掃描資訊。
委派 (公司或學校帳戶)	Machine.Read.All	讀取所有掃描資訊。

注意事項

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

若要檢視使用者至少必須具有下列角色許可權的數據：'ViewData' 或 'TvmViewData' (如需詳細資訊，請參閱 Create 和管理角色)

HTTP 要求

POST api/DeviceAuthenticatedScanDefinitions/GetScanHistoryByScanDefinitionId

要求標頭

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

要求內文

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

參數	Type	描述
ScanDefinitionIds	字串	掃描標識碼。必要。

回應

如果成功，這個方法會傳回 200 - 確定回應碼，並依定義包含掃描歷程記錄的清單。

範例要求

以下是要求的範例。

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/GetScanHistoryByScanDefinitionId

{
    "ScanDefinitionIds": ["4ad8d463-6b3a-4894-b42a-a2de9ea0a8ae", "60c4aa57-c573-4488-8d18-230914792a92", "c6220f67-2cad-4ba3-a2fa-7ded6384da56"]
}

回應範例

{
"@odata.context": "https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/GetScanHistoryByScanDefinitionId",
    "value": [
    {
    "ScanDefinitionIds": "4ad8d463-6b3a-4894-b42a-a2de9ea0a8ae",
    "LastScanned": "2022-12-20T11:14:24.5561791Z",
    "ScanStatus": "Partial Success",
    "ScannerId": "625431694b7d2ca9d07e77ca1b029ef216bebb6d"
    },
    {
    "ScanDefinitionIds": "60c4aa57-c573-4488-8d18-230914792a92",
    "LastScanned": "2022-11-17T15:13:24.5561791Z",
    "ScanStatus": "Partial Success",
    "ScannerId": "625431694b7d2ca9d07e77ca1b029ef216bebb6d"
    },
    {
    "ScanDefinitionIds": "c6220f67-2cad-4ba3-a2fa-7ded6384da56",
    "LastScanned": "2022-11-10T18:15:24.5561791Z",
    "ScanStatus": "Partial Success",
    "ScannerId": "625431694b7d2ca9d07e77ca1b029ef216bebb6d"
    },
   ]
}

範例$top要求

以下是只傳回 1 個工作階段的要求範例。

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/GetScanHistoryByScanDefinitionId?$top=1

$top回應範例

{
"@odata.context": "https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/GetScanHistoryByScanDefinitionId",
    "value": [
    {
    "ScanDefinitionIds": "4ad8d463-6b3a-4894-b42a-a2de9ea0a8ae",
    "LastScanned": "2022-12-20T11:14:24.5561791Z",
    "ScanStatus": "Partial Success",
    "ScannerId": "625431694b7d2ca9d07e77ca1b029ef216bebb6d"
    },
 ]
}

共用方式為