Compartir a través de

API de REST de Defender for Cloud Apps

  • Artículo

En este artículo se describe cómo interactuar con Defender for Cloud Apps a través de HTTPS.

La API de Microsoft Defender for Cloud Apps proporciona acceso mediante programación a Defender for Cloud Apps mediante puntos de conexión de API REST. Las aplicaciones pueden usar la API para realizar operaciones de lectura y actualización en objetos y datos de Defender for Cloud Apps. Por ejemplo, la API de Defender for Cloud Apps admite las siguientes operaciones comunes para un objeto de usuario:

  • Cargar archivos de registro para Cloud Discovery
  • Generar scripts de bloqueo
  • Enumeración de actividades y alertas
  • Descartar o resolver alertas

Estructura de la URL de la API

Para utilizar la API de Defender for Cloud Apps, primero debes obtener la URL de la API de tu inquilino. La URL de la API utiliza el siguiente formato: https://<portal_url>/api/<endpoint>.

Para obtener la dirección URL de la API de Defender for Cloud Apps para el inquilino, sigue estos pasos:

  1. En el portal de Microsoft Defender, selecciona Configuración. A continuación, elige Aplicaciones en la nube. En Sistema, selecciona Acerca de.

  2. En la pantalla Acerca de Defender for Cloud Apps, puedes ver la dirección URL de la API.

    Consulta del centro de datos.

Una vez que tengas la dirección URL de API, agrégale el sufijo /api para obtener la dirección URL de la API. Por ejemplo, si la dirección URL del portal es https://mytenant.us2.contoso.com, la dirección URL de la API es https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokens de API

Defender for Cloud Apps requiere un token de API en el encabezado de todas las solicitudes de API al servidor, como las siguientes:

Authorization: Token <your_token_key>

Donde <your_token_key> es el token de API personal.

Para obtener más información sobre los tokens de API, consulta Administración de tokens de API.

Tokens de API: ejemplo

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"

¿Qué acciones se admiten?

La siguiente tabla describe las acciones admitidas:

Resource Verbos HTTP Rutas de URI
Actividades GET o POST /api/v1/activities/
Alertas GET o POST /api/v1/alerts/
Enriquecimiento de datos GET, POST o DELETE /api/subnet/
Entidades GET o POST /api/v1/entities/
Archivos GET o POST /api/v1/files/

Donde Recurso representa un grupo de entidades relacionadas.

¿Qué tipos de campo se admiten?

En la tabla siguiente se describen los tipos de campo admitidos:

Campo Descripción
string Una cadena de texto
boolean Un valor booleano que representa true/false
integer Entero de 32 bits con signo
timestamp Milisegundos desde la época

Marcas de tiempo

Las menciones de marcas de tiempo en la API de Defender for Cloud Apps hacen referencia a la marca de tiempo de Unix en milisegundos. Esta marca de tiempo viene determinada por el número de milisegundos desde 1970-01-01 0:00:00. Puedes usar el cmdlet de PowerShell get-date para convertir fechas a marcas de tiempo.

Límites

Puedes optar por limitar las solicitudes proporcionando un parámetro de límite en la solicitud.

Se admiten los siguientes métodos para proporcionar el parámetro límite:

  • Codificado con dirección URL (con encabezado Content-Type: application/x-www-form-urlencoded)
  • Datos de formulario
  • Cuerpo JSON (con Content-Type: multipart/form-data y un encabezado de límite adecuado)

Nota:

  • Si no se proporciona ningún límite, se establecerá un valor predeterminado de 100.
  • Las respuestas de todas las solicitudes realizadas con el token de API se limitan a un máximo de 100 elementos.
  • El límite de todas las solicitudes de API es de 30 solicitudes por minuto por inquilino.

Filters

Cuando tengas un gran número de resultados, te resultará útil ajustar las solicitudes mediante filtros. En esta sección se describe la estructura de los filtros y los operadores que pueden utilizarse con ellos.

Estructura

Algunos de nuestros puntos de conexión de API admiten filtros al realizar consultas. En sus secciones pertinentes, encontrarás una referencia en la que se enumeran todos los campos filtrables disponibles y los operadores admitidos para ese recurso.

La mayoría de los filtros admiten varios valores para proporcionar consultas eficaces. Al combinar filtros y operadores, usamos AND como operador lógico entre los filtros.

Ejemplos de filtro

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

Operadores

Nota:

No todos los operadores son compatibles con todos los filtros.

La siguiente tabla describe los operadores admitidos:

Operador Tipo de respuesta Descripción
contains lista de cadenas Devuelve todos los registros pertinentes que contienen una de las cadenas proporcionadas
deq Lista de valores Devuelve todos los registros que contienen un valor que no es igual a uno de los valores proporcionados
descendantof Lista de valores Devuelve todos los valores o descendientes correspondientes de los registros correspondientes
doesnotstartwith lista de cadenas Devuelve todos los registros pertinentes que no empiezan por cada una de las cadenas proporcionadas
endswith lista de cadenas Devuelve todos los registros pertinentes que terminan con una de las cadenas proporcionadas
eq Lista de valores Devuelve todos los registros relevantes que contienen uno de los valores proporcionados
gt Un solo valor Devuelve todos los registros cuyo valor es mayor que el valor proporcionado
gte Un solo valor Devuelve todos los registros cuyo valor es mayor o igual que el valor proporcionado
gte_ndays number Devuelve todos los registros con fecha posterior a N días atrás
isnotset boolean Cuando se establece en "true", devuelve todos los registros pertinentes que no tienen un valor en el campo especificado
isset boolean Cuando se establece en "true", devuelve todos los registros pertinentes que tienen un valor en el campo especificado
lt Un solo valor Devuelve todos los registros cuyo valor es menor que el valor proporcionado
lte Un solo valor Devuelve todos los registros cuyo valor es menor o igual que el valor proporcionado
lte_ndays number Devuelve todos los registros con fecha anterior a N días atrás
ncontains lista de cadenas Devuelve todos los registros pertinentes que no contienen una de las cadenas proporcionadas
ndescendantof Lista de valores Devuelve todos los registros pertinentes que no coinciden con valores o descendientes de ellos
neq Lista de valores Devuelve todos los registros relevantes que no contienen todos los valores proporcionados
range Lista de objetos que contienen campos "start" y "end" Devuelve todos los registros dentro de uno de los intervalos proporcionados
startswith lista de cadenas Devuelve todos los registros pertinentes a partir de una de las cadenas proporcionadas
startswithsingle string Devuelve todos los registros relevantes que empiezan por la cadena proporcionada
text string Realiza una búsqueda de texto completo de todos los registros

Pasos siguientes

Autenticación de API

Si tienes algún problema, estamos aquí para ayudar. Para obtener ayuda o soporte técnico para el problema del producto, abre una incidencia de soporte técnico.