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