API бортового компьютера

Статья
11/19/2024

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

Хотите попробовать Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.

Примечание.

Если вы являетесь клиентом для государственных организаций США, используйте URI, перечисленные в Microsoft Defender для конечной точки для клиентов государственных организаций США.

Совет

Для повышения производительности можно использовать сервер ближе к географическому расположению:

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 для конечной точки.

Ограничения

Ограничения скорости для этого API — 100 вызовов в минуту и 1500 вызовов в час.

Примечание.

Эта страница посвящена выполнению действия компьютера с помощью API. Дополнительные сведения о функциях действий ответа с помощью Microsoft Defender для конечной точки см. в статье Выполнение действий реагирования на компьютере.

Примечание.

Этот API поддерживается в Windows 11, Windows 10 версии 1703 и более поздних версий; в Windows Server 2019 и более поздних версиях; а также в Windows Server 2012 R2 и Windows Server 2016 при использовании нового унифицированного агента для Defender для конечной точки.
Этот API не поддерживается на устройствах macOS или Linux.
Запуск API отключения только останавливает работу службы датчика, но не удаляет сведения о подключении из реестра, как это делает сценарий отключения.

Разрешения

Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Defender для конечных точек.

Тип разрешения	Разрешение	Отображаемое имя разрешения
Приложение	`Machine.Offboard`	`Offboard machine`
Делегированные (рабочая или учебная учетная запись)	`Machine.Offboard`	`Offboard machine`

Важно!

Microsoft рекомендует использовать роли с наименьшим количеством разрешений. Это помогает повысить безопасность вашей организации. Глобальный администратор — это роль с высокими привилегиями, которую следует ограничивать экстренными сценариями, когда вы не можете использовать существующую роль.

При получении маркера с использованием учетных данных пользователя:

Пользователю должна быть назначена соответствующая роль (см. раздел Параметры разрешений).
Пользователь должен иметь доступ к устройству на основе параметров группы устройств. Дополнительные сведения см. в статье Создание групп устройств и управление ими.

Создание группы устройств поддерживается в Defender для конечной точки плана 1 и плана 2.

HTTP-запрос

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

Идентификатор компьютера можно найти в URL-адресе при выборе устройства. Как правило, это 40-значный буквенно-цифровой номер, который можно найти в URL-адресе.

Заголовки запросов

Имя	Тип	Описание
Авторизация	String	Bearer {token}. Обязательное поле.
Content-Type	string	application/json. Обязательное поле.

Текст запроса

В тексте запроса укажите объект JSON со следующими параметрами:

Параметр	Тип	Описание
Comment	String	Комментарий для связывания с действием. Обязательное поле.

Отклик

В случае успешного выполнения этот метод возвращает 200 - Created response код и действие компьютера в тексте ответа.

Пример

Запрос

Ниже приведен пример запроса. Если комментарий JSON не добавлен, ошибка с кодом 400.

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

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