Entity-List-API

Die Entity-List-API bietet Zugriff auf eine paginierte Liste von Entitäten und unterstützt die Filterung und Sortierung nach risikobezogenen Kriterien.

Übersicht

Die Entity List-API ist ein RESTful-Endpunkt, über den GET /api/entity_list Sie Entitätsdaten abrufen und verwalten können. Die API bietet umfassenden Zugriff auf Entitätsinformationen und verfügt über integrierte Funktionen für Paginierung, Filterung und Sortierung.

Schlüsselfunktionen

Die Entity-List-API bietet folgende Funktionen:

  • Entitäten in paginierter Form abrufen, um eine effiziente Datenverarbeitung zu gewährleisten
  • Entitäten nach Schwellenwerten für die Risikobewertung, aktuellem Risiko und Benutzernamen filtern
  • Ergebnisse nach Risikowert oder Anomaliewert sortieren

Abfrageparameter

Die API akzeptiert mehrere Abfrageparameter zur Steuerung des Datenabrufs und der Filterung:

Tabelle 1 Abfrageparameter
Parameter Typ Standard Beschreibung
Begrenzung ganze Zahl 50 Maximale Anzahl der in einer einzelnen Anfrage zurückgegebenen Entitäten. Gültiger Bereich: 1–1000. Pro Anfrage sind maximal 1000 Entitäten zulässig.
Versatz ganze Zahl 0 Anzahl der Einträge, die übersprungen werden sollen, bevor Ergebnisse zurückgegeben werden. Wird für die Paginierung verwendet. Werte kleiner als 0 werden als 0 behandelt.
risk_score_min Gleitkomma nicht zutreffend Gibt Entitäten zurück, deren Risikowert größer oder gleich dem angegebenen Wert ist. Dient zur Identifizierung von Unternehmen mit höherem Risiko. Kann nicht zusammen mit „risk_score_max“ verwendet werden.
risk_score_max Gleitkomma nicht zutreffend Gibt Entitäten zurück, deren Risikowert kleiner oder gleich dem angegebenen Wert ist. Wird zur Identifizierung von Unternehmen mit geringerem Risiko verwendet. Kann nicht zusammen mit „risk_score_min“ verwendet werden.
risk_score Gleitkomma nicht zutreffend Entspricht „risk_score_min “. Gibt Entitäten zurück, deren Risikowert größer oder gleich dem angegebenen Wert ist.
aktuelles_Risiko Gleitkomma nicht zutreffend Gibt Entitäten zurück, deren aktuellster Risikowert ( latest_risk ) größer oder gleich dem angegebenen Wert ist.
username Zeichenfolge nicht zutreffend Gibt die Entitäten zurück, die mit dem angegebenen Benutzernamen verknüpft sind.
sortBy Zeichenfolge nicht zutreffend Sortiert die zurückgegebenen Entitäten. Unterstützte Werte: risk (Sortierung nach Risikowert) und anomalyScore (Sortierung nach aggregiertem Anomaliewert). Wenn anomalyScore angegeben wird, enthält die Antwort für jede Entität das Feld „total_sum_risk “.

Regeln filtern

Bei der Verwendung von Filterparametern gelten folgende Regeln:

  • „risk_score_min“ und „risk_score_max“ schließen sich gegenseitig aus und können nicht in derselben Anfrage verwendet werden.
  • Es können mehrere Filterparameter kombiniert werden, um die Ergebnisse weiter zu verfeinern.

Sortieroptionen

Die API unterstützt zwei Sortiermethoden:

Tabelle 2. Sortieroptionen
Wert Beschreibung
risk Entitäten nach Risikobewertung sortieren.
anomalyScore Sortiere Entitäten nach dem aggregierten Anomaliewert und füge „total_sum_risk“ in die Antwort ein.

Seitenaufteilung

Verwenden Sie die folgenden Parameter, um durch umfangreiche Ergebnismengen zu navigieren:

  • limit – Anzahl der pro Anfrage zurückgegebenen Datensätze
  • offset – Startposition der Ergebnismenge

Antwortstruktur

Die API gibt die folgenden Informationen zurück:

  • Entitätsdetails
  • Risikobezogene Kennzahlen
  • Gesamtzahl der übereinstimmenden Entitäten
  • Informationen zur Paginierung ( Limit und Offset )

Bei der Sortierung nach Anomaliewert wird eine zusätzliche aggregierte Risikokennzahl in die Antwort aufgenommen.

Beispielantwort

Das folgende Beispiel zeigt eine typische API-Antwort:

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

Zu den Antwortfeldern gehören:

  • risk_threshold gibt den effektiven Risikoschwellenwert an, der auf die Abfrage angewendet wird.
  • „entities“ enthält die Liste der übereinstimmenden Entitäten.
  • „total_sum_risk“ wird nur dann berücksichtigt, wenn sortBy=anomalyScore.
  • „total_count“ gibt die Gesamtzahl der Entitäten an, die den angegebenen Filtern entsprechen.
  • „limit“ und „offset“ liefern Informationen zur Paginierung der aktuellen Ergebnismenge.

Fehlerbehandlung

Die API gibt Standard- HTTP -Statuscodes zurück:

  • 200 OK– Anfrage erfolgreich
  • 400 Bad Request– Ungültige Anfrageparameter
  • 500 Internal Server Error– Unerwarteter Serverfehler