엔티티 목록 API

개요

엔티티 목록 API는 해당 GET /api/entity_list 엔드포인트를 통해 엔티티 데이터를 조회하고 관리할 수 있게 해주는 RESTful 엔드포인트입니다. 이 API는 페이지 분할, 필터링 및 정렬 기능을 기본적으로 지원하여 엔티티 정보에 대한 포괄적인 접근을 제공합니다.

주요 기능

엔티티 목록 API는 다음과 같은 기능을 제공합니다:

• 효율적인 데이터 처리를 위해 엔티티를 페이지 단위로 불러오기
• 위험 점수 기준치, 최근 위험도 및 사용자 이름을 기준으로 엔티티를 필터링합니다
• 결과를 위험 점수 또는 이상 점수 순으로 정렬

조회 매개변수

이 API는 데이터 검색 및 필터링을 제어하기 위해 여러 가지 쿼리 매개변수를 지원합니다:

필터링 규칙

필터 매개변수를 사용할 때는 다음 규칙이 적용됩니다:

• risk_score_min 과 risk_score_max는 상호 배타적이며, 동일한 요청에서 함께 사용할 수 없습니다.
• 여러 필터 매개변수를 조합하여 검색 결과를 더욱 세밀하게 조정할 수 있습니다.

정렬 옵션

이 API는 두 가지 정렬 방법을 지원합니다:

페이지 매김

대규모 결과 집합을 탐색하려면 다음 매개변수를 사용하십시오:

• limit – 요청당 반환되는 레코드 수
• 오프셋 – 결과 집합의 시작 위치

응답 구조

이 API는 다음과 같은 정보를 반환합니다:

• 엔티티 세부사항
• 위험 관련 지표
• 일치하는 개체의 총 개수
• 페이지 나누기 정보 ( 한도 및 오프셋 )

이상 점수 기준으로 정렬할 경우, 응답에 추가적인 집계 위험 지표가 포함됩니다.

응답 예시

다음 예시는 일반적인 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
}

응답 항목은 다음과 같습니다:

• risk_threshold는 쿼리에 적용되는 유효한 위험 임계값을 나타냅니다.
• 'entities'에는 일치하는 엔티티 목록이 포함되어 있습니다.
• sortBy=anomalyScoretotal_sum_risk는 다음 조건이 충족 될 때만 포함됩니다.
• total_count는 지정된 필터 조건에 부합하는 엔티티의 총 개수를 나타냅니다.
• limit 과 offset은 현재 결과 집합에 대한 페이지 분할 정보를 제공합니다.

오류 처리

이 API는 표준 HTTP 상태 코드를 반환합니다:

• 200 OK– 요청 성공
• 400 Bad Request– 잘못된 요청 매개변수
• 500 Internal Server Error– 예기치 않은 서버 오류