Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Descripción de la API
Dispositivo fuera del panel de Defender para punto de conexión.
Requisitos previos
Sistemas operativos admitidos
| Sistema operativo | Versiones compatibles |
|---|---|
| Cliente de Windows | Windows 11 y Windows 10, versión 1703 y posteriores |
| Servidor de Windows | Windows Server 2019 y posteriores; Windows Server 2012 R2 y Windows Server 2016 al usar el nuevo agente unificado para Defender for Endpoint |
| macOS | macOS 14 y posteriores |
| Linux | Distribuciones de Linux admitidas |
Limitaciones
- Las limitaciones de velocidad de esta API son 100 llamadas por minuto y 1500 llamadas por hora.
- En dispositivos Windows, ejecutar la API de desconexión solo detiene el servicio de sensores. No elimina la información de incorporación del registro como hace un script de offboarding.
Permissions
Microsoft recomienda utilizar roles con la menor cantidad de permisos. Esto ayuda a mejorar la seguridad de la organización. Administrador global es un rol con muchos privilegios que debe limitarse a escenarios de emergencia cuando no se puede usar un rol existente.
Al obtener un token con credenciales de usuario:
El usuario debe tener asignado un rol adecuado. Para obtener más información, vea: Opciones de permisos.
El usuario debe tener acceso al dispositivo, en función de la configuración del grupo de dispositivos. Para obtener más información, vea: Crear y administrar grupos de dispositivos.
Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, consulte Uso de Defender para API de punto de conexión.
| Tipo de permiso | Permiso | Nombre para mostrar del permiso |
|---|---|---|
| Aplicación | Machine.Offboard |
Offboard machine |
| Delegado (cuenta profesional o educativa) | Machine.Offboard |
Offboard machine |
Solicitud HTTP
POST https://api.security.microsoft.com/api/machines/{id}/offboard
El identificador de equipo se puede encontrar en la dirección URL al seleccionar el dispositivo. Por lo general, es un número alfanumérico de 40 dígitos que se puede encontrar en la dirección URL.
Encabezados de solicitud
| Nombre | Tipo | Descripción |
|---|---|---|
| Authorization | Cadena | {token} de portador. Necesario. |
| Content-Type | string | application/json. Necesario. |
Cuerpo de la solicitud
En el cuerpo de la solicitud, proporcione un objeto JSON con los parámetros siguientes:
| Parámetro | Tipo | Descripción |
|---|---|---|
| Comentario | Cadena | Comentario que se va a asociar a la acción. Necesario. |
Respuesta
Si se ejecuta correctamente, este método devuelve 200 - Created response código y Acción de máquina en el cuerpo de la respuesta.
Ejemplo
Solicitud
Este es un ejemplo de la solicitud. Si no se agrega ningún comentario JSON, se produce un error con el código 400.
POST https://api.security.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard
{
"Comment": "Offboard machine by automation"
}