API de REST de Defender for Cloud Apps

  • Artículo
  • Tiempo de lectura: 6 minutos

Nota

  • Hemos cambiado el nombre de Microsoft Cloud App Security. Ahora se llama Microsoft Defender for Cloud Apps. En las próximas semanas, actualizaremos las capturas de pantalla y las instrucciones aquí y en las páginas relacionadas. Para obtener más información sobre el cambio, consulte este anuncio. Para obtener más información sobre el cambio de nombre reciente de los servicios de seguridad de Microsoft, consulte el blog seguridad de Microsoft Ignite.

  • Microsoft Defender for Cloud Apps ahora forma parte de Microsoft 365 Defender. El portal de Microsoft 365 Defender permite a los administradores de seguridad realizar sus tareas de seguridad en una ubicación. Esto simplificará los flujos de trabajo y agregará la funcionalidad de los demás servicios Microsoft 365 Defender. Microsoft 365 Defender será el hogar de la supervisión y administración de la seguridad en las identidades, los datos, los dispositivos, las aplicaciones y la infraestructura de Microsoft. Para obtener más información sobre estos cambios, consulte Microsoft Defender for Cloud Apps en Microsoft 365 Defender.

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

La API de Microsoft Defender for Cloud Apps proporciona acceso mediante programación a Defender for Cloud Aplicaciones a través de puntos de conexión de la API REST. Las aplicaciones pueden usar la API para realizar operaciones de lectura y actualización en datos y objetos 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 dirección URL de la API

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

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

  1. En el portal Defender for Cloud Aplicaciones, seleccione el icono de signo de interrogación en la barra de menús. Después, seleccione Acerca de.

    Select About.

  2. En la pantalla Defender for Cloud Aplicaciones sobre , puede ver la dirección URL del portal.

    View your data center.

Una vez que tenga la dirección URL del portal, agregue el sufijo a ella 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.contoso.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 más información sobre los tokens de API, consulte Administración de tokens de API.

Ejemplo

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

¿Qué acciones se admiten?

En la tabla siguiente se describen las acciones admitidas:

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

Donde Resource 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 textual
boolean 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 de PowerShell get-date 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:

  • Codificado con dirección URL (con Content-Type: application/x-www-form-urlencoded encabezado)
  • Datos del 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.

Filtros

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

Estructura

Algunos de nuestros puntos de conexión de API admiten filtros al realizar consultas. En sus secciones pertinentes, encontrará 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 proporcionarle consultas eficaces. Al combinar filtros y operadores, usamos AND como operador lógico entre los filtros.

Ejemplo

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.contoso.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 de los valores proporcionados.
descendantof lista de valores Devuelve todos los registros pertinentes que coinciden con los valores o descendientes de ellos.
doesnotstartwith lista de cadenas Devuelve todos los registros pertinentes que no comienzan 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 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 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 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 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 los 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 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 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 surgen problemas, estamos aquí para ayudarle. Para obtener ayuda o soporte técnico para el problema del producto, abra una incidencia de soporte técnico.