Iniciar la API de investigación

Artículo
05/03/2024

Se aplica a:

¿Quiere experimentar Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación geográfica:

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

Descripción de la API

Inicie una investigación automatizada en un dispositivo.

Consulte Introducción a las investigaciones automatizadas para obtener más información.

Limitaciones

Las limitaciones de velocidad de esta API son de 50 llamadas por hora.

Requisitos de AIR

Su organización debe tener Defender para punto de conexión (consulte Requisitos mínimos para Microsoft Defender para punto de conexión.

Actualmente, AIR solo admite las siguientes versiones del sistema operativo:

Windows Server 2019
Windows Server 2022
Windows 10, versión 1709 (compilación del sistema operativo 16299.1085 con KB4493441) o posterior
Windows 10, versión 1803 (compilación del sistema operativo 17134.704 con KB4493464) o posterior
Windows 10, versión 1803 o posterior
Windows 11

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para más información, incluido cómo elegir permisos, consulte Uso de api de Microsoft Defender para punto de conexión

Tipo de permiso	Permiso	Nombre para mostrar del permiso
Aplicación	Alert.ReadWrite.All	"Leer y escribir todas las alertas"
Delegado (cuenta profesional o educativa)	Alert.ReadWrite	"Alertas de lectura y escritura"

Nota:

Al obtener un token con credenciales de usuario:

El usuario debe tener al menos el siguiente permiso de rol: "Acciones de corrección activas" (vea Create y administrar roles para obtener más información).
El usuario debe tener acceso al dispositivo en función de la configuración del grupo de dispositivos (consulte Create y administrar grupos de dispositivos para obtener más información).

La creación de grupos de dispositivos se admite en El plan 1 y el plan 2 de Defender para punto de conexión.

Solicitud HTTP

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

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 201: código de respuesta creado e Investigación en el cuerpo de la respuesta.

Ejemplo

Solicitud

Aquí tiene un ejemplo de la solicitud.

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

{
  "Comment": "Test investigation"
}