API de la liste des entités

L'API « Entity List » permet d'accéder à une liste paginée d'entités et prend en charge le filtrage et le tri en fonction de critères liés au risque.

Présentation

L'API « Entity List » est un point de terminaison RESTful qui vous permet de récupérer et de gérer les données d'entité via ce GET /api/entity_list point de terminaison. L'API offre un accès complet aux informations relatives aux entités et intègre des fonctionnalités de pagination, de filtrage et de tri.

Fonctions principales

L'API « Entity List » offre les fonctionnalités suivantes :

  • Récupérer les entités sous forme paginée pour un traitement efficace des données
  • Filtrer les entités en fonction des seuils de score de risque, du risque récent et du nom d'utilisateur
  • Trier les résultats par score de risque ou par score d'anomalie

Paramètres de requête

L'API accepte plusieurs paramètres de requête permettant de contrôler la récupération et le filtrage des données :

Tableau 1. Paramètres de requête
Paramètre Type Par défaut Descriptif
limite entier 50 Nombre maximal d'entités renvoyées lors d'une seule requête. Plage valide : 1 à 1 000. Le nombre maximal d'entités autorisé par requête est de 1 000.
position entier 0 Nombre d'entités à ignorer avant d'afficher les résultats. Utilisé pour la pagination. Les valeurs inférieures à 0 sont considérées comme égales à 0.
score_de_risque_min séparer N/A Renvoie les entités dont le score de risque est supérieur ou égal à la valeur indiquée. Utilisé pour identifier les entités présentant un risque plus élevé. Ne peut pas être utilisé conjointement avec risk_score_max.
score_de_risque_max séparer N/A Renvoie les entités dont le score de risque est inférieur ou égal à la valeur indiquée. Utilisé pour identifier les entités présentant un risque moindre. Ne peut pas être utilisé conjointement avec risk_score_min.
risk_score séparer N/A Identique à risk_score_min. Renvoie les entités dont le score de risque est supérieur ou égal à la valeur indiquée.
risque_récent séparer N/A Renvoie les entités dont le score de risque le plus récent ( latest_risk ) est supérieur ou égal à la valeur indiquée.
Nom d'utilisateur chaîne N/A Renvoie les entités associées au nom d'utilisateur spécifié.
sortBy chaîne N/A Trie les entités renvoyées. Valeurs prises en charge : risk (tri par score de risque) et anomalyScore (tri par score d'anomalie agrégé). Lorsque anomalyScore est spécifié, la réponse inclut le champ « total_sum_risk » pour chaque entité.

Règles de filtrage

Lors de l'utilisation des paramètres de filtrage, les règles suivantes s'appliquent :

  • risk_score_min et risk_score_max s'excluent mutuellement et ne peuvent pas être utilisés dans la même requête.
  • Il est possible de combiner plusieurs paramètres de filtrage pour affiner davantage les résultats.

Options de tri

L'API prend en charge deux méthodes de tri :

Tableau 2. Options de tri
Valeur Descriptif
risk Trier les entités en fonction de leur score de risque.
anomalyScore Trier les entités en fonction du score d'anomalie agrégé et inclure la valeur « total_sum_risk » dans la réponse.

Pagination

Utilisez les paramètres suivants pour parcourir des ensembles de résultats volumineux :

  • limite – Nombre d'enregistrements renvoyés par requête
  • offset – Position de départ de l'ensemble de résultats

Structure de la réponse

L'API renvoie les informations suivantes :

  • Détails d'entité
  • Indicateurs liés aux risques
  • Nombre total d'entités correspondantes
  • Informations sur la pagination ( limite et décalage )

Lors du tri par score d'anomalie, un indicateur de risque agrégé supplémentaire est inclus dans la réponse.

Exemple de réponse

L'exemple suivant illustre une réponse API typique :

{
  "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
}

Les champs de réponse sont les suivants :

  • risk_threshold indique le seuil de risque effectif appliqué à la requête.
  • « entités » contient la liste des entités correspondantes.
  • La variable « total_sum_risk » n'est prise en compte que lorsque sortBy=anomalyScore.
  • total_count correspond au nombre total d'entités répondant aux critères de filtrage spécifiés.
  • Les paramètres « limit » et « offset » fournissent des informations de pagination pour l'ensemble de résultats actuel.

Traitement des erreurs

L'API renvoie des codes d'état standard de l' HTTP :

  • 200 OK– Demande acceptée
  • 400 Bad Request– Paramètres de requête non valides
  • 500 Internal Server Error– Erreur inattendue du serveur