API de máquina fuera de la máquinaOffboard machine API

Se aplica a:Applies to:

¿Desea experimentar Defender for Endpoint?Want to experience Defender for Endpoint? Regístrate para obtener una versión de prueba gratuita.Sign up for a free trial.

Nota

Si es un cliente del Gobierno de Estados Unidos, use los URI que aparecen en Microsoft Defender para endpoints para clientes de US Government.If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Sugerencia

Para un mejor rendimiento, puede usar el servidor más cerca de la ubicación geográfica: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

Descripción de la APIAPI description

Dispositivo offboard de Defender para endpoint.Offboard device from Defender for Endpoint.

LimitacionesLimitations

  • Las limitaciones de velocidad para esta API son 100 llamadas por minuto y 1500 llamadas por hora.Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

Nota

Esta página se centra en realizar una acción de máquina a través de la API.This page focuses on performing a machine action via API. Consulta Realizar acciones de respuesta en un equipo para obtener más información acerca de la funcionalidad de acciones de respuesta a través de Microsoft Defender para endpoint.See take response actions on a machine for more information about response actions functionality via Microsoft Defender for Endpoint.

Nota

Esta API se admite en Windows 10, versión 1703 y versiones posteriores, o Windows Server 2019 y versiones posteriores.This API is supported on Windows 10, version 1703 and later, or Windows Server 2019 and later. Esta API no se admite en dispositivos MacOS o Linux.This API is not supported on MacOS or Linux devices.

PermisosPermissions

Se requiere uno de los siguientes permisos para llamar a esta API.One of the following permissions is required to call this API. Para obtener más información, incluido cómo elegir permisos, consulte Use Defender for Endpoint APITo learn more, including how to choose permissions, see Use Defender for Endpoint APIs

Tipo de permisoPermission type PermisoPermission Nombre para mostrar de permisosPermission display name
AplicaciónApplication Machine.OffboardMachine.Offboard 'Offboard machine''Offboard machine'
Delegado (cuenta profesional o educativa)Delegated (work or school account) Machine.OffboardMachine.Offboard 'Offboard machine''Offboard machine'

Nota

Al obtener un token con credenciales de usuario:When obtaining a token using user credentials:

  • El usuario necesita el rol ad "Administrador global"The user needs to 'Global Admin' AD role
  • El usuario debe tener acceso al dispositivo en función de la configuración del grupo de dispositivos (consulta Crear y administrar grupos de dispositivos para obtener más información)The user needs to have access to the device, based on device group settings (See Create and manage device groups for more information)

Solicitud HTTPHTTP request

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

Encabezados de solicitudRequest headers

NombreName TipoType DescripciónDescription
AuthorizationAuthorization CadenaString Portador {token}.Bearer {token}. Necesario.Required.
Content-TypeContent-Type cadenastring application/json.application/json. Necesario.Required.

Cuerpo de la solicitudRequest body

En el cuerpo de la solicitud, proporcione un objeto JSON con los siguientes parámetros:In the request body, supply a JSON object with the following parameters:

ParámetroParameter TipoType DescripciónDescription
ComentarioComment CadenaString Comentario para asociarlo a la acción.Comment to associate with the action. Necesario.Required.

RespuestaResponse

Si se realiza correctamente, este método devuelve 201: código de respuesta creado y Acción de máquina en el cuerpo de la respuesta.If successful, this method returns 201 - Created response code and Machine Action in the response body.

EjemploExample

SolicitudRequest

Aquí tiene un ejemplo de la solicitud.Here is an example of the request.

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