API de REST de Defender for Cloud Apps

Artículo
11/28/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 a través de puntos de conexión de API REST. Las aplicaciones pueden usar la API para realizar operaciones de lectura y actualización en Defender for Cloud Apps datos y objetos. Por ejemplo, la API de Defender for Cloud Apps admite las siguientes operaciones comunes para un objeto de usuario:

Carga de archivos de registro para la detección de nube
Generación de scripts de bloque
Enumerar actividades y alertas
Descartar o resolver alertas

Estructura de dirección URL de API

Para usar la API de Defender for Cloud Apps, primero debe obtener la dirección URL de la API del inquilino. La dirección URL de API usa el formato siguiente: https://<portal_url>/api/<endpoint>.

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

En el portal de Microsoft Defender, seleccione Configuración. A continuación, elija Aplicaciones en la nube. En Sistema, seleccione Acerca de.
En la pantalla Defender for Cloud Apps acerca de , puede ver la dirección URL de la API.

Una vez que tenga la dirección URL de la API, agréguele el sufijo para obtener la /api 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>

Dónde <your_token_key> está el token de API personal.

Para obtener más información sobre los tokens de API, consulte 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?

En la tabla siguiente se describen las acciones admitidas:

Recurso	Verbos HTTP	Rutas 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
booleano	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. Puede usar el cmdlet get-date de PowerShell para convertir fechas en marcas de tiempo.

Límites

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

Se admiten los métodos siguientes para proporcionar el parámetro limit:

Con codificación URL (con Content-Type: application/x-www-form-urlencoded encabezado)
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 para todas las solicitudes realizadas con el token de API están limitadas a un máximo de 100 elementos.
El límite para todas las solicitudes de API es de 30 solicitudes por minuto por inquilino.

Filtros

Si tiene un gran número de resultados, le resultará útil ajustar las solicitudes mediante filtros. En esta sección se describe la estructura de los filtros y los operadores que se pueden usar con .

Estructura

Algunos de nuestros puntos de conexión de API admiten filtros al realizar consultas. En sus secciones pertinentes, encontrará una referencia que enumera 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.

Filtros: ejemplo

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.

En la tabla siguiente se describen 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 los valores proporcionados.
descendantof	lista de valores	Devuelve todos los registros pertinentes que coinciden con valores o descendientes de ellos.
doesnotstartwith	lista de cadenas	Devuelve todos los registros pertinentes que no comienzan con 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 pertinentes que contienen uno de los valores proporcionados.
gt	valor único	Devuelve todos los registros cuyo valor es mayor que el valor proporcionado.
Gte	valor único	Devuelve todos los registros cuyo valor es mayor o igual que el valor proporcionado.
gte_ndays	número	Devuelve todos los registros con fecha posterior a la de hace N días
isnotset	booleano	Cuando se establece en "true", devuelve todos los registros pertinentes que no tienen un valor en el campo especificado.
isset	booleano	Cuando se establece en "true", devuelve todos los registros pertinentes que tienen un valor en el campo especificado.
lt	valor único	Devuelve todos los registros cuyo valor es menor que el valor proporcionado.
lte	valor único	Devuelve todos los registros cuyo valor es menor o igual que el valor proporcionado.
lte_ndays	número	Devuelve todos los registros con fecha anterior a la de hace N días
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 pertinentes que no contienen todos los valores proporcionados.
range	lista de objetos que contienen campos "start" y "end"	Devuelve todos los registros 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 pertinentes a partir de la cadena proporcionada.
text	string	Realiza una búsqueda de texto completo de todos los registros.

Pasos siguientes

Autenticación de API

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

Compartir a través de