Редактиране

Споделяне чрез

Export device antivirus health details API methods and properties

  • Статия

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:

  • 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

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.

Export device antivirus health details API description

Retrieves a list of Microsoft Defender Antivirus device health details. This API has different API calls (methods) to get different types of data. Because the amount of data can be large, there are two ways it can be retrieved:

  • JSON response The API 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.

  • via files This API solution 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.

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.

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

1.1 Export device antivirus health details API methods

Method Data type Description
(JSON response) Microsoft Defender Antivirus health per device collection. See: 1.2 Export device antivirus health details API properties (JSON response) Returns a table with an entry for every unique combination of DeviceId, ConfigurationId.

The API 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.
(via files) Microsoft Defender Antivirus health per device collection. See: 1.3 Export device antivirus health details API properties (via files) Returns a table with an entry for every unique combination of DeviceId, ConfigurationId.

This API solution 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:
  1. Call the API to get a list of download URLs with all your organization data.
  2. Download all the files using the download URLs and process the data as you like.

1.2 Limitations

  • Maximum page size: 200,000
  • Rate limitations for this API: 30 calls per minute and 1,000 calls per hour

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

Note

  • The properties defined in the following table are listed alphabetically, by property ID. When running this API, the resulting output will not necessarily be returned in the same order listed in this table.
  • Note that rbacgroupname and Id are not supported filter operators.
  • Some additional columns might be returned in the response. These columns can be temporary and might be removed; use only the documented columns.
Property (ID) Data type Description Example of a returned value
avEngineUpdateTime DateTimeOffset Datetime when AV engine was last updated on device "2022-08-04T12:44:02Z"
avEngineVersion String Antivirus engine version "1.1.19400.3"
avIsEngineUpToDate String Up-to-date status of AV engine "True", "False", "Unknown"
avIsPlatformUpToDate String Up-to-date status of AV platform "True", "False", "Unknown"
avIsSignatureUpToDate String Up-to-date status of AV signature "True", "False", "Unknown"
avMode String Antivirus mode. Each mode will be a string typed integer value ranging from 0 to 5. Refer to the mapping below to see its value's meaning:
  • '' = Other
  • '0' = Active
  • '1' = Passive
  • '2' = Disabled
  • '3' = Other
  • '4' = EDRBlocked
  • '5' = PassiveAudit
avPlatformUpdateTime DateTimeOffset Datetime when AV platform was last updated on device "2022-08-04T12:44:02Z"
avPlatformVersion String Antivirus platform version "4.18.2203.5"
avSignaturePublishTime DateTimeOffset Datetime when AV security intelligence build was released "2022-08-04T12:44:02Z"
avSignatureUpdateTime DateTimeOffset Datetime when AV security intelligence was last updated on device "2022-08-04T12:44:02Z"
avSignatureVersion String Antivirus security intelligence version "1.371.1323.0"
computerDnsName String DNS name "SampleDns"
dataRefreshTimestamp DateTimeOffset Datetime when data is refreshed for this report "2022-08-04T12:44:02Z"
fullScanError String Error codes from full scan "0x80508023"
fullScanResult String Full scan result of this device "Completed"
"Canceled"
"Failed"
fullScanTime DateTimeOffset Datetime when full scan has completed "2022-08-04T12:44:02Z"
id String Machine GUID "30a8fa2826abf24d24379b23f8a44d471f00feab"
lastSeenTime DateTimeOffset Last seen datetime of this machine "2022-08-04T12:44:02Z"
machineId String Machine GUID "30a8fa2826abf24d24379b23f8a44d471f00feab"
osKind String Operating system kind "windows", "mac", "linux"
osPlatform String Operating system major version name Windows 10, macOs
osVersion String Operating system version 10.0.18363.1440, 12.4.0.0
quickScanError String Error codes from quick scan "0x80508023"
quickScanResult String Quick scan result of this device "Completed"
"Canceled"
"Failed"
quickScanTime DateTimeOffset Datetime when quick scan has completed "2022-08-04T12:44:02Z"
rbacGroupId Long Device group ID that this machine belongs to 712
rbacGroupName String Name of device group that this machine belongs to "SampleGroup"

1.4 Export device antivirus health details API properties (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.

Note

  • The files are gzip compressed & in multiline Json format.
  • The download URLs are only valid for 3 hours; otherwise you can use the parameter.
  • For maximum download speed of your data, you can make sure you are downloading from the same Azure region that your data resides.
  • Each record is approximately 1KB of data. You should take this into account when choosing the correct pageSize parameter for you.
  • Some additional columns might be returned in the response. These columns are temporary and might be removed, please use only the documented columns.
Property (ID) Data type Description Example of a returned value
Export files array[string] A list of download URLs for files holding the current snapshot of the organization. ["https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime String The time that the export was generated. 2022-05-20T08:00:00Z

Note

In each of the Export files a property "DeviceGatheredInfo" containing the data about Antivirus information can be found. Each of its attributes can provide you with information on the device's health and its status.

See also

Export device antivirus health report

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.