You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: defender-endpoint/api/device-health-api-methods-properties.md
+35-35Lines changed: 35 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ ms.service: defender-endpoint
5
5
ms.author: deniseb
6
6
author: denisebmsft
7
7
ms.localizationpriority: medium
8
-
ms.date: 06/25/2024
8
+
ms.date: 02/19/2025
9
9
manager: deniseb
10
10
ms.reviewr: mkaminska
11
11
audience: ITPro
@@ -23,7 +23,6 @@ search.appverid: met150
23
23
24
24
**Applies to:**
25
25
26
-
-[Microsoft Defender for Endpoint](../microsoft-defender-endpoint.md)
27
26
-[Microsoft Defender for Endpoint Plan 2](../microsoft-defender-endpoint.md)
28
27
-[Microsoft Defender XDR](/defender-xdr)
29
28
@@ -41,11 +40,13 @@ Retrieves a list of Microsoft Defender Antivirus device health details. This API
41
40
42
41
-**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.
43
42
44
-
-**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:
45
-
- Call the API to get a list of download URLs with all your organization data.
46
-
- Download all the files using the download URLs and process the data as you like.
43
+
-**via files** This API solution enables pulling larger amounts of data faster and more reliably, and is recommended for large organizations who have more than 100,000 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:
47
44
48
-
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.
45
+
1. Call the API to get a list of download URLs with all your organization data.
46
+
47
+
2. Download all the files using the download URLs and process the data as you like.
48
+
49
+
Data that is collected using either `JSON response` or by using files is a snapshot of the current state. This data doesn't contain historical data. To collect historical data, you must save the data in your own data storage.
49
50
50
51
> [!IMPORTANT]
51
52
> 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](../configure-server-endpoints.md#functionality-in-the-modern-unified-solution).
@@ -66,60 +67,59 @@ Data that is collected using either '_JSON response_ or _via files_' is the curr
66
67
67
68
### 1.3 Export device antivirus health details API properties (JSON response)
68
69
69
-
- The properties defined in the following table are listed alphabetically, by property ID. When running this API, the resulting output won't necessarily be returned in the same order listed in this table.
70
+
- The properties defined in the following table are listed alphabetically, by property ID. When you use this API, the resulting output won't necessarily be returned in the same order listed in this table.
70
71
- Note that **rbacgroupname** and **Id** aren't supported filter operators.
71
72
- Some more columns might be returned in the response. These columns can be temporary and might be removed; use only the documented columns.
72
73
73
74
| Property (ID) | Data type | Description | Example of a returned value |
74
75
|---|---|---|---|
75
76
|`avEngineUpdateTime`| DateTimeOffset | Datetime when the antivirus engine was last updated on device | "2022-08-04T12:44:02Z" |
76
-
|`avEngineVersion`| String | Antivirus engine version |"1.1.19400.3"|
77
-
|`avIsEngineUpToDate`| String | Up-to-date status of antivirus engine |"True", "False", "Unknown"|
78
-
|`avIsPlatformUpToDate`| String | Up-to-date status of antivirus platform |"True", "False", "Unknown"|
79
-
|`avIsSignatureUpToDate`| String | Up-to-date status of antivirus signature |"True", "False", "Unknown"|
80
-
|`avMode`| String | Antivirus mode. | Each mode is a string typed integer value ranging from 0 to 5. Refer to the following mapping to see its value's meaning: <br/>'' = Other<br/>'0' = Active<br/>'1' = Passive<br/>'2' = Disabled<br/>'3' = Other<br/>'4' = EDRBlocked<br/>'5' = PassiveAudit |
77
+
|`avEngineVersion`| String | Antivirus engine version |`1.1.19400.3`|
78
+
|`avIsEngineUpToDate`| String | Up-to-date status of antivirus engine |`True`, `False`, or `Unknown`|
79
+
|`avIsPlatformUpToDate`| String | Up-to-date status of antivirus platform |`True`, `False`, or `Unknown`|
80
+
|`avIsSignatureUpToDate`| String | Up-to-date status of antivirus signature |`True`, `False`, or `Unknown`|
81
+
|`avMode`| String | Antivirus mode. | Each mode is a string typed integer value ranging from 0 to 5. <br/>`''` = `Other`<br/>`0` = `Active`<br/>`1` = `Passive`<br/>`2` = `Disabled`<br/>`3` = `Other`<br/>`4` = `EDRBlocked`<br/>`5` = `PassiveAudit`|
81
82
|`avPlatformUpdateTime`| DateTimeOffset | Datetime when antivirus platform was last updated on device | "2022-08-04T12:44:02Z" |
82
-
|`avPlatformVersion`| String | Antivirus platform version |"4.18.2203.5"|
83
+
|`avPlatformVersion`| String | Antivirus platform version |`4.18.2203.5`|
83
84
|`avSignaturePublishTime`| DateTimeOffset | Datetime when antivirus security intelligence build was released | "2022-08-04T12:44:02Z" |
84
85
|`avSignatureUpdateTime`| DateTimeOffset | Datetime when antivirus security intelligence was last updated on device | "2022-08-04T12:44:02Z" |
85
-
|`avSignatureVersion`| String | Antivirus security intelligence version |"1.371.1323.0"|
86
-
|`computerDnsName`| String | DNS name |"SampleDns"|
87
-
|`dataRefreshTimestamp`| DateTimeOffset | Datetime when data is refreshed for this report |"2022-08-04T12:44:02Z"|
88
-
|`fullScanError`| String | Error codes from full scan | "0x80508023" |
89
-
|`fullScanResult`| String | Full scan result of this device |"Completed" <br> "Canceled" <br>"Failed"|
90
-
|`fullScanTime`| DateTimeOffset | Datetime when full scan has completed |"2022-08-04T12:44:02Z"|
|`osKind`| String | Operating system kind |`windows`, `mac`, or `linux`|
96
+
|`osPlatform`| String | Operating system major version name |`Windows 10` or `macOS`|
97
+
|`osVersion`| String | Operating system version |`10.0.18363.1440, 12.4.0.0`|
98
+
|`quickScanError`| String | Error codes from quick scan |`0x80508023`|
99
+
|`quickScanResult`| String | Quick scan result of this device |`Completed`, `Canceled`, or `Failed`|
100
+
|`quickScanTime`| DateTimeOffset | Datetime when quick scan completed |`2022-08-04T12:44:02Z`|
101
+
|`rbacGroupId`| Long | Device group ID that this machine belongs to |`712`|
102
+
|`rbacGroupName`| String | Name of device group that this machine belongs to |`SampleGroup`|
102
103
103
104
### 1.4 Export device antivirus health details API properties (via files)
104
105
105
106
> [!IMPORTANT]
106
107
> Information in this section relates to prereleased product which can be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
107
108
108
109
> [!NOTE]
109
-
>
110
-
> - The files are gzip compressed & in multiline Json format.
110
+
> - The files are gzip-compressed and in multiline `.json` format.
111
111
> - The download URLs are only valid for 3 hours; otherwise you can use the parameter.
112
112
> - For maximum download speed of your data, you can make sure you're downloading from the same Azure region that your data resides.
113
-
> - Each record is approximately 1KB of data. You should take this into account when choosing the correct pageSize parameter for you.
114
-
> -Some more columns might be returned in the response. These columns are temporary and might be removed, so use only the documented columns.
113
+
> - Each record uses approximately 1KB of data. You should take this into account when choosing the correct `pageSize` parameter.
114
+
> -More columns might be returned in the response. These columns are temporary and might be removed, so use only the documented columns.
115
115
116
116
| Property (ID) | Data type | Description | Example of a returned value |
117
117
|---|---|---|---|
118
118
| 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"]|
119
119
| GeneratedTime | String | The time that the export was generated. | 2022-05-20T08:00:00Z |
120
120
121
121
> [!NOTE]
122
-
> In each of the Export filesa 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.
122
+
> In each of the export files, there's a property called `DeviceGatheredInfo`, which contains antivirus data. Each of its attributes can provide you with information on the device's health and its status.
0 commit comments