API de REST de Defender for Cloud Apps

Artículo
01/23/2024

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:

En el portal de Microsoft Defender, selecciona Configuración. A continuación, elige Aplicaciones en la nube. En Sistema, selecciona Acerca de.
En la pantalla Acerca de Defender for Cloud Apps, puedes ver la dirección URL de la API.

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.

Compartir vía