API de la Lista de Entidades

La API de la Lista de entidades permite acceder a una lista paginada de entidades y admite el filtrado y la ordenación en función de criterios relacionados con el riesgo.

Visión general

La API de la Lista de entidades es un punto final RESTful que permite recuperar y gestionar datos de entidades a través de dicho GET /api/entity_list punto final. La API ofrece un acceso completo a la información de las entidades y cuenta con funciones integradas de paginación, filtrado y ordenación.

Características clave

La API de la Lista de entidades ofrece las siguientes funciones:

  • Recuperar entidades en formato paginado para un manejo eficiente de los datos
  • Filtrar entidades según los umbrales de puntuación de riesgo, el riesgo reciente y el nombre de usuario
  • Ordenar los resultados por puntuación de riesgo o por puntuación de anomalía

Parámetros de consulta

La API admite varios parámetros de consulta para controlar la recuperación y el filtrado de datos:

Tabla 1. Parámetros de consulta
Parámetro Tipo Valor predeterminado Descripción
límite entero 50 Número máximo de entidades devueltas en una sola solicitud. Rango válido: 1–1000. Se permite un máximo de 1000 entidades por solicitud.
desplazamiento entero 0 Número de entidades que se deben omitir antes de mostrar los resultados. Se utiliza para la paginación. Los valores inferiores a 0 se consideran 0.
puntuación_de_riesgo_mínima flotante N/D Devuelve las entidades cuya puntuación de riesgo sea mayor o igual que el valor especificado. Se utiliza para identificar a las entidades de mayor riesgo. No se puede utilizar junto con risk_score_max.
puntuación_de_riesgo_máxima flotante N/D Devuelve las entidades cuya puntuación de riesgo sea inferior o igual al valor especificado. Se utiliza para identificar entidades de menor riesgo. No se puede utilizar junto con risk_score_min.
risk_score flotante N/D Igual que risk_score_min. Devuelve las entidades cuya puntuación de riesgo sea mayor o igual que el valor especificado.
riesgo_reciente flotante N/D Devuelve las entidades cuya puntuación de riesgo más reciente ( latest_risk ) sea mayor o igual que el valor especificado.
username serie N/D Devuelve las entidades asociadas al nombre de usuario especificado.
sortBy serie N/D Ordena las entidades devueltas. Valores admitidos: risk (ordenar por puntuación de riesgo) y anomalyScore (ordenar por puntuación agregada de anomalías). Cuando anomalyScore se especifica, la respuesta incluye el campo «total_sum_risk» para cada entidad.

Reglas de filtrado

Al utilizar los parámetros de filtro, se aplican las siguientes reglas:

  • risk_score_min y risk_score_max son mutuamente excluyentes y no pueden utilizarse en la misma solicitud.
  • Se pueden combinar varios parámetros de filtro para refinar aún más los resultados.

Opciones de ordenación

La API admite dos métodos de ordenación:

Tabla 2. Opciones de ordenación
Valor Descripción
risk Ordena las entidades según su puntuación de riesgo.
anomalyScore Ordena las entidades según la puntuación de anomalía agregada e incluye «total_sum_risk» en la respuesta.

Paginación

Utiliza los siguientes parámetros para navegar por conjuntos de resultados extensos:

  • límite : número de registros devueltos por solicitud
  • offset – Posición inicial del conjunto de resultados

Estructura de la respuesta

La API devuelve la siguiente información:

  • Detalles de entidad
  • Indicadores relacionados con el riesgo
  • Número total de entidades coincidentes
  • Información sobre la paginación ( límite y desplazamiento )

Al ordenar los resultados por puntuación de anomalía, se incluye en la respuesta una métrica de riesgo agregada adicional.

Ejemplo de respuesta

El siguiente ejemplo muestra una respuesta típica de la API:

{
  "risk_threshold": 50.0,
  "entities": [
    {
      "entity_id": 12345,
      "username": "john.doe",
      "risk_score": 78.5,
      "latest_risk": 82.0,
      "total_sum_risk": 156.3
    },
    {
      "entity_id": 12346,
      "username": "jane.smith",
      "risk_score": 65.2,
      "latest_risk": 68.7,
      "total_sum_risk": 121.8
    }
  ],
  "total_count": 250,
  "limit": 50,
  "offset": 0
}

Los campos de respuesta incluyen:

  • risk_threshold indica el umbral de riesgo efectivo que se aplica a la consulta.
  • «entidades» contiene la lista de entidades coincidentes.
  • «total_sum_risk» solo se incluye cuando sortBy=anomalyScore.
  • total_count representa el número total de entidades que cumplen los filtros especificados.
  • «limit» y «offset» proporcionan información sobre la paginación del conjunto de resultados actual.

Manejo de errores

La API devuelve códigos de estado estándar de HTTP :

  • 200 OK– Solicitud aceptada
  • 400 Bad Request– Parámetros de solicitud no válidos
  • 500 Internal Server Error– Error inesperado del servidor