匯出裝置防毒程式健康狀況報告

發行項
05/03/2024

適用於：

想要體驗適用於端點的 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

重要事項

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

此 API 有兩種方法可擷取 Microsoft Defender 防病毒軟體裝置防病毒軟體健康情況詳細數據：

方法1：1 匯出健康情況報告 (JSON 回應) 方法會將組織中的所有數據提取為 JSON 回應。此方法最適合 裝置少於 100 K 的小型組織。回應會進行分頁，因此您可以使用回應中的 @odata.nextLink 欄位來擷取下一個結果。
方法 2：2 透過檔案匯出健康情況報告 () 此方法可讓您更快速且更可靠地提取大量數據。因此，建議大型組織使用超過100 K的裝置。此 API 會將組織中的所有資料提取為下載檔。回應包含可從 Azure 記憶體下載所有數據的 URL。此 API 可讓您從 Azure 記憶體下載所有資料，如下所示：
- 呼叫 API 以取得包含您所有組織資料的下載 URL 清單。
- 使用下載 URL 下載所有檔案，並視需要處理數據。

使用「JSON 回應 或 透過檔案」收集的數據是目前狀態的目前快照集。它不包含歷史數據。若要收集歷史數據，客戶必須將數據儲存在自己的數據記憶體中。請參閱導出裝置健康情況詳細數據 API 方法和屬性。

重要事項

目前，只有 防病毒軟體健康情況 JSON 回應 已正式推出。 透過檔案的防病毒軟體健康情況 API 目前僅適用於公開預覽。

進階搜捕自定義查詢目前僅在公開預覽版中提供，即使仍然顯示查詢也一樣。

重要事項

若要 Windows Server 2012 R2 和 Windows Server 2016 出現在裝置健康情況報告中，這些裝置必須使用新式整合解決方案套件上線。如需詳細資訊，請參閱適用於 Windows Server 2012 R2 和 2016 的新式整合解決方案中的新功能。

注意事項

如需在 Microsoft 365 安全性儀錶板中使用裝置健康情況和防病毒軟體合規性報告工具的相關信息，請參閱：適用於端點的 Microsoft Defender 中的裝置健康情況和防病毒軟體合規性報告。

1 導出健康情況報告 (JSON 回應)

1.1 API 方法描述

此 API 會擷取 Microsoft Defender 防病毒軟體裝置防病毒軟體健康情況詳細數據的清單。傳回數據表，其中包含下列每個唯一組合的專案：

DeviceId
裝置名稱
AV 模式
最新狀態
掃描結果

1.1.1 限制

頁面大小上限為 200,000
此 API 的速率限制為每分鐘 30 次呼叫，每小時 1000 次呼叫。

OData 支援的運算符

$filteron：machineId、computerDnsName、、osKind、osPlatform、osVersion、avMode、avSignatureVersion、avPlatformVersionavEngineVersion、quickScanResult、、fullScanResultquickScanError、fullScanError、avIsSignatureUpToDate、、avIsEngineUpToDate、 avIsPlatformUpToDaterbacGroupId
$top 最大值為 10,000。
$skip

重要事項

請注意， 不支援 rbacgroupname 和 Id 篩選運算子。

1.2 許可權

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

許可權類型	權限	許可權顯示名稱
應用程式	Machine.Read.All	「讀取所有計算機設定檔」
委派 (公司或學校帳戶)	Machine.Read	「讀取機器資訊」

1.3 URL (HTTP 要求)

URL: GET: /api/deviceavinfo

1.3.1 要求標頭

名稱	類型	描述
授權	字串	持有人 {token}。此為必要動作。

1.3.2 要求本文

Empty

1.3.3 回應

如果成功，此方法會傳回 200 OK，其中包含裝置健康情況詳細數據清單。

1.4 參數

默認頁面大小為 20
請參閱 OData 查詢與適用於端點的 Microsoft Defender 的範例。

1.5 屬性

請參閱： 1.3 匯出裝置防病毒軟體健康情況詳細資料 API 屬性 (JSON 回應)

支援 OData V4 查詢。

1.6 範例

要求範例

以下是範例要求：

GET https://api.securitycenter.microsoft.com/api/deviceavinfo

回應範例

以下是範例回應：

{

    @odata.context: "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAvInfo",

"value": [{

            "id": "Sample Guid",

            "machineId": "Sample Machine Guid",

            "computerDnsName": "appblockstg1",

            "osKind": "windows",

            "osPlatform": "Windows10",

            "osVersion": "10.0.19044.1865",

            "avMode": "0",

            "avSignatureVersion": "1.371.1279.0",

            "avEngineVersion": "1.1.19428.0",

            "avPlatformVersion": "4.18.2206.108",

            "lastSeenTime": "2022-08-02T19:40:45Z",

            "quickScanResult": "Completed",

            "quickScanError": "",

            "quickScanTime": "2022-08-02T18:40:15.882Z",

            "fullScanResult": "",

            "fullScanError": "",

            "fullScanTime": null,

            "dataRefreshTimestamp": "2022-08-02T21:16:23Z",

            "avEngineUpdateTime": "2022-08-02T00:03:39Z",

            "avSignatureUpdateTime": "2022-08-02T00:03:39Z",

            "avPlatformUpdateTime": "2022-06-20T16:59:35Z",

            "avIsSignatureUpToDate": "True",

            "avIsEngineUpToDate": "True",

            "avIsPlatformUpToDate": "True",

            "avSignaturePublishTime": "2022-08-02T00:03:39Z",

            "rbacGroupName": "TVM1",

            "rbacGroupId": 4415

        },

        ...

     ]

}

2 透過檔案導出健康情況報告 ()

重要事項

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

2.1 API 方法描述

此 API 回應包含每個裝置防病毒軟體健康情況和狀態的所有數據。傳回數據表，其中包含下列每個唯一組合的專案：

DeviceId
裝置名稱
AV 模式
最新狀態
掃描結果

2.1.2 限制

頁面大小上限為 200,000。
此 API 的速率限制為每分鐘 30 次呼叫，每小時 1000 次呼叫。

2.2 許可權

呼叫此 API 需要下列其中一個許可權。

許可權類型	權限	許可權顯示名稱
應用程式	Vulnerability.Read.All	「讀取「威脅與弱點管理」弱點資訊」
委派 (公司或學校帳戶)	Vulnerability.Read	「讀取「威脅與弱點管理」弱點資訊」

若要深入瞭解，包括如何選擇許可權，請參閱使用適用於端點的 Microsoft Defender API 以取得詳細數據。

2.3 URL

GET /api/machines/InfoGatheringExport

2.4 參數

sasValidHours：下載 URL 的有效時數 () 最多 24 小時。

2.5 屬性

請參閱： 1.4 匯出裝置防病毒軟體健康情況詳細數據 API 屬性 (檔案) 。

2.6 範例

2.6.1 要求範例

以下是範例要求：

GET https://api-us.securitycenter.contoso.com/api/machines/InfoGatheringExport

2.6.2 回應範例

以下是範例回應：

{

   "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",

   "exportFiles": [

       "https://tvmexportexternalprdeus.blob.core.windows.net/temp-../2022-08-02/2201/InfoGatheringExport/json/OrgId=../_RbacGroupId=../part-00055-12fc2fcd-8f56-4e09-934f-e8efe7ce74a0.c000.json.gz?sv=2020-08-04&st=2022-08-02T22%3A47%3A11Z&se=2022-08-03T01%3A47%3A11Z&sr=b&sp=r&sig=..",

       "https://tvmexportexternalprdeus.blob.core.windows.net/temp-../2022-08-02/2201/InfoGatheringExport/json/OrgId=../_RbacGroupId=../part-00055-12fc2fcd-8f56-4e09-934f-e8efe7ce74a0.c000.json.gz?sv=2020-08-04&st=2022-08-02T22%3A47%3A11Z&se=2022-08-03T01%3A47%3A11Z&sr=b&sp=r&sig=.."

   ],


   "generatedTime": "2022-08-02T22:01:00Z"


}

提示

效能提示由於各種因素 (下列範例) Microsoft Defender 防病毒軟體和其他防病毒軟體一樣，可能會在端點裝置上造成效能問題。在某些情況下，您可能需要調整 Microsoft Defender 防病毒軟體的效能，以減輕這些效能問題。 Microsoft 的 效能分析器 是一種 PowerShell 命令行工具，可協助判斷哪些檔案、檔案路徑、程式和擴展名可能會造成效能問題;一些範例包括：

影響掃描時間的最上層路徑
影響掃描時間的熱門檔案
影響掃描時間的熱門程式
影響掃描時間的最上層擴展名
組合 - 例如：
- 每個擴充功能的頂端檔案
- 每個擴充功能的最上層路徑
- 每個路徑的前置進程
- 每個檔案的最上層掃描
- 每個進程每個檔案的掃描數目最高

您可以使用效能分析器所收集的信息，進一步評估效能問題並套用補救動作。請參閱：Microsoft Defender 防病毒軟體的效能分析器。

另請參閱

匯出裝置健康狀況方法和屬性

裝置健康情況與合規性報告

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：適用於端點的 Microsoft Defender 技術社群。

匯出裝置防毒程式健康狀況報告

1 導出健康情況報告 (JSON 回應)

1.1 API 方法描述

1.1.1 限制

OData 支援的運算符

1.2 許可權

1.3 URL (HTTP 要求)

1.3.1 要求標頭

1.3.2 要求本文

1.3.3 回應

1.4 參數

1.5 屬性

1.6 範例

要求範例

回應範例

2 透過檔案導出健康情況報告 ()

2.1 API 方法描述

2.1.2 限制

2.2 許可權

2.3 URL

2.4 參數

2.5 屬性

2.6 範例

2.6.1 要求範例

2.6.2 回應範例

另請參閱

意見反應

意見反應

其他資源