导出设备防病毒运行状况详细信息 API 方法和属性
适用于:
希望体验 Microsoft Defender for Endpoint? 注册免费试用版。
注意
如果你是美国政府客户,请使用 适用于美国政府客户的 Microsoft Defender for Endpoint 中列出的 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
- ina.api.security.microsoft.com
重要
本文中的某些信息与预发行的产品有关,该产品在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
导出设备防病毒运行状况详细信息 API 说明
检索Microsoft Defender 防病毒设备运行状况详细信息的列表。 此 API 具有不同的 API 调用 (方法,) 获取不同类型的数据。 由于数据量可能很大,因此可通过两种方式检索数据:
JSON 响应 API 会将组织中的所有数据作为 JSON 响应进行拉取。 此方法最适合 设备少于 100-K 的小型组织。 响应是分页的,因此可以使用响应中的 @odata.nextLink 字段来提取下一个结果。
通过 文件 借助此 API 解决方案,可以更快、更可靠地拉取大量数据。 因此,建议将它用于具有 100 K 个以上的设备的大型组织。 此 API 将组织中的所有数据作为下载文件拉取。 响应包含用于从 Azure 存储下载所有数据的 URL。 通过此 API,可以从 Azure 存储下载所有数据,如下所示:
- 调用 API 以获取包含所有组织数据的下载 URL 列表。
- 使用下载 URL 下载所有文件,并根据需要处理数据。
使用“JSON 响应 或通过 文件”收集的数据是当前状态的当前快照。 它不包含历史数据。 若要收集历史数据,客户必须将数据保存在自己的数据存储中。
重要
若要在设备运行状况报告中显示 Windows Server 2012 R2 和 Windows Server 2016,必须使用新式统一解决方案包载入这些设备。 有关详细信息,请参阅 适用于 Windows Server 2012 R2 和 2016 的新式统一解决方案中的新功能。
有关在 Microsoft Defender 门户中使用 设备运行状况和防病毒合规性 报告工具的信息,请参阅: Microsoft Defender for Endpoint 中的设备运行状况和防病毒报告。
1.1 导出设备防病毒运行状况详细信息 API 方法
方法 | 数据类型 | 说明 |
---|---|---|
(JSON 响应) | 每个设备集合Microsoft Defender 防病毒运行状况。 请参阅: 1.2 导出设备防病毒运行状况详细信息 API 属性 (JSON 响应) | 返回一个表,其中包含 DeviceId、ConfigurationId 的每个唯一组合的条目。 API 会将组织中的所有数据作为 JSON 响应进行拉取。 此方法最适合设备少于 100-K 的小型组织。 响应是分页的,因此可以使用 @odata.nextLink 响应中的 字段来提取下一个结果。 |
通过文件) ( | 每个设备集合Microsoft Defender 防病毒运行状况。 请参阅: 1.3 通过文件 (导出设备防病毒运行状况详细信息 API 属性) | 返回一个表,其中包含 DeviceId、ConfigurationId 的每个唯一组合的条目。 借助此 API 解决方案,可以更快、更可靠地拉取大量数据。 因此,建议将它用于具有 100 K 个以上的设备的大型组织。 此 API 将组织中的所有数据作为下载文件拉取。 响应包含用于从 Azure 存储下载所有数据的 URL。 通过此 API,可以从 Azure 存储下载所有数据,如下所示:
|
1.2 限制
- 最大页面大小:200,000
- 此 API 的速率限制:每分钟 30 个调用和每小时 1,000 个调用
1.3 导出设备防病毒运行状况详细信息 API 属性 (JSON 响应)
注意
- 下表中定义的属性按属性 ID 按字母顺序列出。 运行此 API 时,生成的输出不一定按此表中列出的相同顺序返回。
- 请注意 ,rbacgroupname 和 ID 不支持筛选器运算符。
- 响应中可能会返回一些其他列。 这些列可以是临时的,可能会被删除;仅使用记录的列。
属性 (ID) | 数据类型 | 说明 | 返回值的示例 |
---|---|---|---|
avEngineUpdateTime | DateTimeOffset | 上次在设备上更新 AV 引擎的日期/时间 | “2022-08-04T12:44:02Z” |
avEngineVersion | String | 防病毒引擎版本 | "1.1.19400.3" |
avIsEngineUpToDate | String | AV 引擎的最新状态 | “True”、“False”、“Unknown” |
avIsPlatformUpToDate | String | AV 平台的最新状态 | “True”、“False”、“Unknown” |
avIsSignatureUpToDate | String | AV 签名的最新状态 | “True”、“False”、“Unknown” |
avMode | String | 防病毒模式。 | 每个模式都是一个字符串类型的整数值,范围为 0 到 5。 请参阅下面的映射,了解其值的含义:
|
avPlatformUpdateTime | DateTimeOffset | 上次在设备上更新 AV 平台的日期时间 | “2022-08-04T12:44:02Z” |
avPlatformVersion | String | 防病毒平台版本 | "4.18.2203.5" |
avSignaturePublishTime | DateTimeOffset | 发布 AV 安全智能生成的日期/时间 | “2022-08-04T12:44:02Z” |
avSignatureUpdateTime | DateTimeOffset | 上次在设备上更新 AV 安全智能的日期/时间 | “2022-08-04T12:44:02Z” |
avSignatureVersion | String | 防病毒安全智能版本 | "1.371.1323.0" |
computerDnsName | String | DNS 名称 | “SampleDns” |
dataRefreshTimestamp | DateTimeOffset | 刷新此报表数据时的日期/时间 | “2022-08-04T12:44:02Z” |
fullScanError | String | 完全扫描中的错误代码 | “0x80508023” |
fullScanResult | String | 此设备的完整扫描结果 | “Completed” “已取消” “失败” |
fullScanTime | DateTimeOffset | 完成完全扫描的日期/时间 | “2022-08-04T12:44:02Z” |
id | String | 计算机 GUID | “30a8fa2826abf24d24379b23f8a44d471f00feab” |
lastSeenTime | DateTimeOffset | 此计算机的上次查看日期/时间 | “2022-08-04T12:44:02Z” |
machineId | String | 计算机 GUID | “30a8fa2826abf24d24379b23f8a44d471f00feab” |
osKind | String | 操作系统类型 | “windows”、“mac”、“linux” |
osPlatform | String | 操作系统主版本名称 | Windows 10、macOs |
osVersion | String | 操作系统版本 | 10.0.18363.1440, 12.4.0.0 |
quickScanError | String | 快速扫描中的错误代码 | “0x80508023” |
quickScanResult | String | 此设备的快速扫描结果 | “Completed” “已取消” “失败” |
quickScanTime | DateTimeOffset | 完成快速扫描的日期/时间 | “2022-08-04T12:44:02Z” |
rbacGroupId | 长型 | 此计算机所属的设备组 ID | 712 |
rbacGroupName | String | 此计算机所属的设备组的名称 | “SampleGroup” |
1.4 通过文件 (导出设备防病毒运行状况详细信息 API 属性)
重要
本节中的信息与预发布产品有关,在商业发布之前,这些产品可能会进行重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
注意
- 这些文件是多行 Json 格式的 gzip 压缩 &。
- 下载 URL 仅在 3 小时内有效;否则可以使用 参数。
- 为了获得数据的最大下载速度,可以确保从数据所在的同一 Azure 区域进行下载。
- 每个记录大约为 1KB 的数据。 在为你选择正确的 pageSize 参数时,应考虑到这一点。
- 响应中可能会返回一些其他列。 这些列是临时的,可能会删除,请仅使用记录的列。
属性 (ID) | 数据类型 | 说明 | 返回值的示例 |
---|---|---|---|
导出文件 | array[string] | 保存组织当前快照的文件的下载 URL 列表。 | ["https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"] |
GeneratedTime | String | 生成导出的时间。 | 2022-05-20T08:00:00Z |
注意
在每个导出文件中,可以找到一个属性“DeviceGatheredInfo”,其中包含有关防病毒信息的数据。 其每个属性都可以为你提供有关设备运行状况及其状态的信息。
另请参阅
提示
想要了解更多信息? 在技术社区中与 Microsoft 安全社区互动: Microsoft Defender for Endpoint 技术社区。