通过

机外计算机 API

  • 项目

适用于：

希望体验 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

API 说明

从 Defender for Endpoint 卸载设备。

限制

  • 此 API 的速率限制是每分钟 100 个调用和每小时 1,500 个调用。

    注意

    本页重点介绍如何通过 API 执行计算机操作。 有关通过 Microsoft Defender for Endpoint 的响应操作功能的详细信息，请参阅 在计算机上执行 响应操作。

注意

  • Windows 11、Windows 10 版本 1703 及更高版本支持此 API;在 Windows Server 2019 及更高版本上;和 在 Windows Server 2012 R2 和 Windows Server 2016 上使用 适用于 Defender for Endpoint 的新统一代理时。
  • macOS 或 Linux 设备不支持此 API。
  • 运行卸载 API 只会阻止传感器服务运行，但不会像卸载脚本那样从注册表中删除载入信息。

权限

要调用此 API，需要以下权限之一。 若要了解详细信息（包括如何选择权限），请参阅 使用 Defender for Endpoint API

权限类型 权限 权限显示名称
应用程序 Machine.Offboard Offboard machine
委派（工作或学校帐户） Machine.Offboard Offboard machine

重要

Microsoft 建议使用权限最少的角色。 这有助于提高组织的安全性。 全局管理员是一个权限很高的角色，应仅限于在无法使用现有角色的紧急情况下使用。

注意

使用用户凭据获取令牌时：

  • 用户必须具有全局管理员角色。
  • 用户必须有权访问设备，具体取决于设备组设置。 有关详细信息，请参阅 创建和管理设备组。

Defender for Endpoint 计划 1 和计划 2 支持创建设备组。

HTTP 请求

POST https://api.security.microsoft.com/api/machines/{id}/offboard

选择设备时，可以在 URL 中找到计算机 ID。 通常，它是可在 URL 中找到的 40 位字母数字。

请求标头

名称 类型 说明
Authorization String 持有者 {token}。 必需。
Content-Type string application/json. 必需。

请求正文

在请求正文中，提供具有以下参数的 JSON 对象：

参数 类型 说明
评论 字符串 要与操作关联的注释。 必需。

响应

如果成功，此方法在 200 - Created response 响应正文中返回代码和 计算机操作 。

示例

请求

下面是请求的示例。 如果未添加 JSON 注释，则代码 400出错。

POST https://api.security.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard

{
  "Comment": "Offboard machine by automation"
}

提示

想要了解更多信息？ 在技术社区中与 Microsoft 安全社区互动： Microsoft Defender for Endpoint 技术社区。