导出设备防病毒运行状况详细信息 API 方法和属性

  • 项目

适用于：

希望体验 Microsoft Defender for Endpoint？ 注册免费试用版。

注意

如果你是美国政府客户，请使用美国政府客户Microsoft Defender for Endpoint中列出的 URI。

提示

为了提高性能，可以使用离地理位置更近的服务器：

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.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 365 安全仪表板中使用设备运行状况和防病毒合规性报告工具的信息，请参阅：Microsoft Defender for Endpoint 中的设备运行状况和防病毒报告。

1.1 导出设备防病毒运行状况详细信息 API 方法

方法 数据类型 说明
每个设备集合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. 调用 API 以获取包含所有组织数据的下载 URL 列表。
  2. 使用下载 URL 下载所有文件，并根据需要处理数据。

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。 请参阅下面的映射，了解其值的含义：
  • “” = 其他
  • “0” = 活动
  • “1” = 被动
  • “2” = 已禁用
  • “3” = 其他
  • “4” = EDRBlocked
  • “5” = PassiveAudit
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”，其中包含有关防病毒信息的数据。 其每个属性都可以为你提供有关设备运行状况及其状态的信息。

另请参阅

导出设备防病毒软件运行状况报告

设备运行状况和合规性报告

提示

想要了解更多信息？ Engage技术社区中的 Microsoft 安全社区：Microsoft Defender for Endpoint技术社区。