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

適用於:

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

注意事項

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

提示

為了獲得更好的效能,您可以使用更接近您地理位置的伺服器:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.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: machineIdcomputerDnsName 、、 osKindosPlatformosVersionavModeavSignatureVersionavPlatformVersionavEngineVersionquickScanResult 、、 fullScanResultquickScanErrorfullScanErroravIsSignatureUpToDate 、、 avIsEngineUpToDateavIsPlatformUpToDaterbacGroupId
  • $top 最大值為 10,000。
  • $skip

重要事項

請注意, 不支援 rbacgroupnameId 篩選運算子。

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 要求本文

空白

1.3.3 回應

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

1.4 參數

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 防毒軟體的效能分析器

另請參閱

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

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