تحرير

Export device antivirus health report

  • مقالة

Applies to:

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

Note

If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Tip

For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.microsoft.com

Important

Some information in this article relates to a prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, expressed or implied, with respect to the information provided here.

This API has two methods to retrieve Microsoft Defender Antivirus device antivirus health details:

  • Method one: 1 Export health reporting (JSON response) The method pulls all data in your organization as JSON responses. This method is best for small organizations with less than 100-K devices. The response is paginated, so you can use the @odata.nextLink field from the response to fetch the next results.

  • Method two: 2 Export health reporting (via files) This method enables pulling larger amounts of data faster and more reliably. So, it's recommended for large organizations, with more than 100-K devices. This API pulls all data in your organization as download files. The response contains URLs to download all the data from Azure Storage. This API enables you to download all your data from Azure Storage as follows:

    • Call the API to get a list of download URLs with all your organization data.
    • Download all the files using the download URLs and process the data as you like.

Data that is collected using either 'JSON response or via files' is the current snapshot of the current state. It doesn't contain historic data. To collect historic data, customers must save the data in their own data storages. See Export device health details API methods and properties.

Important

Currently, only the Antivirus Health JSON Response is generally available. Antivirus Health API via files is currently only available in public preview.

Advanced Hunting custom query is currently only available in public preview, even if the queries are still visible.

Important

For Windows Server 2012 R2 and Windows Server 2016 to appear in device health reports, these devices must be onboarded using the modern unified solution package. For more information, see New functionality in the modern unified solution for Windows Server 2012 R2 and 2016.

Note

For information about using the Device health and antivirus compliance reporting tool in the Microsoft 365 Security dashboard, see: Device health and antivirus compliance report in Microsoft Defender for Endpoint.

1 Export health reporting (JSON response)

1.1 API method description

This API retrieves a list of Microsoft Defender Antivirus device antivirus health details. Returns a table with an entry for every unique combination of:

  • DeviceId
  • Device name
  • AV mode
  • Up-to-date status
  • Scan results

1.1.1 Limitations

  • maximum page size is 200,000
  • Rate limitations for this API are 30 calls per minute and 1000 calls per hour.

OData supported operators

  • $filter on: machineId, computerDnsName, osKind, osPlatform, osVersion, avMode, avSignatureVersion, avEngineVersion, avPlatformVersion, quickScanResult, quickScanError, fullScanResult, fullScanError, avIsSignatureUpToDate, avIsEngineUpToDate, avIsPlatformUpToDate, rbacGroupId
  • $top with max value of 10,000.
  • $skip

Important

Note that rbacgroupname and Id are not supported filter operators.

1.2 Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs for details.

Permission type Permission Permission display name
Application Machine.Read.All 'Read all machine profiles'
Delegated (work or school account) Machine.Read 'Read machine information'

1.3 URL (HTTP request)

URL: GET: /api/deviceavinfo

1.3.1 Request headers

Name Type Description
Authorization String Bearer {token}. Required.

1.3.2 Request body

Empty

1.3.3 Response

If successful, this method returns 200 OK with a list of device health details.

1.4 Parameters

1.5 Properties

See: 1.3 Export device antivirus health details API properties (JSON response)

Supports OData V4 queries.

1.6 Example

Request example

Here's an example request:

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

Response example

Here's an example response:

{

    @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 Export health reporting (via files)

Important

Information in this section relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

2.1 API method description

This API response contains all the data of Antivirus health and status per device. Returns a table with an entry for every unique combination of:

  • DeviceId
  • device name
  • AV mode
  • Up-to-date status
  • Scan results

2.1.2 Limitations

  • Maximum page size is 200,000.
  • Rate limitations for this API are 30 calls per minute and 1000 calls per hour.

2.2 Permissions

One of the following permissions is required to call this API.

Permission type Permission Permission display name
Application Vulnerability.Read.All 'Read "threat and vulnerability management" vulnerability information'
Delegated (work or school account) Vulnerability.Read 'Read "threat and vulnerability management" vulnerability information'

To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs for details.

2.3 URL

GET /api/machines/InfoGatheringExport

2.4 Parameters

  • sasValidHours: The number of hours that the download URLs will be valid for (Maximum 24 hours).

2.5 Properties

See: 1.4 Export device antivirus health details API properties (via files).

2.6 Examples

2.6.1 Request example

Here's an example request:

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

2.6.2 Response example

Here's an example response:

{

   "@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"


}

Tip

Performance tip Due to a variety of factors (examples listed below) Microsoft Defender Antivirus, like other antivirus software, can cause performance issues on endpoint devices. In some cases, you might need to tune the performance of Microsoft Defender Antivirus to alleviate those performance issues. Microsoft's Performance analyzer is a PowerShell command-line tool that helps determine which files, file paths, processes, and file extensions might be causing performance issues; some examples are:

  • Top paths that impact scan time
  • Top files that impact scan time
  • Top processes that impact scan time
  • Top file extensions that impact scan time
  • Combinations – for example:
    • top files per extension
    • top paths per extension
    • top processes per path
    • top scans per file
    • top scans per file per process

You can use the information gathered using Performance analyzer to better assess performance issues and apply remediation actions. See: Performance analyzer for Microsoft Defender Antivirus.

See also

Export device health methods and properties

Device health and compliance reporting

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.