Offboard machine APIOffboard machine API

Область применения:Applies to:

Хотите испытать Defender для конечной точки?Want to experience Defender for Endpoint? Зарегистрився для бесплатной пробной.Sign up for a free trial.

Примечание

Если вы клиент правительства США, используйте URL-адреса, указанные в Microsoft Defender для конечных точек для государственных клиентов США.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

Описание APIAPI description

Offboard device from 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 для конечной точки см. в этой записи.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. Дополнительные новости, в том числе выбор разрешений, см. в этой ссылке: Use Defender for Endpoint APITo 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''Offboard machine'
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) Machine.OffboardMachine.Offboard 'Offboard machine''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
CommentComment StringString Комментарий для связи с действием.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"
}