载出计算机 APIOffboard machine API

适用于:Applies to:

想要体验适用于终结点的 Defender?Want to experience Defender for Endpoint? 注册免费试用版。Sign up for a free trial.

备注

如果你是美国政府客户,请使用 Microsoft Defender for Endpoint 中针对美国政府客户的 URI。If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

提示

为了提高性能,可以使用距离地理位置更近的服务器:For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.comapi-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.comapi-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.comapi-uk.securitycenter.microsoft.com

API 说明API description

从 Defender for Endpoint 载出设备。Offboard device from Defender for Endpoint.

限制Limitations

  • 此 API 的速率限制是每分钟 100 个调用和每小时 1500 个调用。Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

备注

此页面重点介绍通过 API 执行计算机操作。This page focuses on performing a machine action via API. 有关 通过 Microsoft Defender for Endpoint 的响应操作功能详细信息,请参阅对计算机执行响应操作。See take response actions on a machine for more information about response actions functionality via Microsoft Defender for Endpoint.

备注

此 API 在 Windows 10 版本 1703 和更高版本或 Windows Server 2019 及更高版本上受支持。This API is supported on Windows 10, version 1703 and later, or Windows Server 2019 and later. 此 API 在 MacOS 或 Linux 设备上不受支持。This API is not supported on MacOS or Linux devices.

权限Permissions

若要调用此 API,需要以下权限之一。One of the following permissions is required to call this API. 若要了解更多信息(包括如何选择权限),请参阅对 终结点 API 使用 DefenderTo learn more, including how to choose permissions, see Use Defender for Endpoint APIs

权限类型Permission type 权限Permission 权限显示名称Permission display name
应用程序Application Machine.OffboardMachine.Offboard "载出计算机"'Offboard machine'
委派(工作或学校帐户)Delegated (work or school account) Machine.OffboardMachine.Offboard "载出计算机"'Offboard machine'

备注

使用用户凭据获取令牌时:When obtaining a token using user credentials:

  • 用户需要"全局管理员"AD 角色The user needs to 'Global Admin' AD role
  • 用户需要具有对设备的访问权限,根据设备组设置 (请参阅创建和管理 设备 组,了解) The user needs to have access to the device, based on device group settings (See Create and manage device groups for more information)

HTTP 请求HTTP request

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

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization StringString Bearer {token}。Bearer {token}. 必需Required.
Content-TypeContent-Type stringstring application/json.application/json. 必需Required.

请求正文Request body

在请求正文中,提供具有以下参数的 JSON 对象:In the request body, supply a JSON object with the following parameters:

参数Parameter 类型Type 说明Description
评论Comment 字符串String 要与操作关联的注释。Comment to associate with the action. 必需Required.

响应Response

如果成功,此方法在响应正文中返回 201 - 已创建响应 代码和计算机 操作。If successful, this method returns 201 - Created response code and Machine Action in the response body.

示例Example

请求Request

下面是一个请求示例。Here is an example of the request.

POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard
{
  "Comment": "Offboard machine by automation"
}