본문으로 건너뛰기

SHIELDEX File 6.0 - 시간대별 detailCode 통계 API 명세서 (GET /statistics/detail-code)

# SHIELDEX File 6.0 - 시간대별 detailCode 통계 API 명세서 (GET /statistics/detail-code)

조회 기간(from ~ to) 동안 발생한 무해화 결과를 1시간 단위로 그룹핑하여, 각 시간대의 detailCode 별 건수(count0 ~ count3, count-1)를 JSON Array 로 반환하는 고객 연동용 통계 API 명세입니다.

항목값
문서 버전6.2026.0813.01
관련 문서역할
무해화 결과 응답 명세서 (detailCode)detailCode 정의·산출 규칙의 SSOT
무해화 로그리즌 표logReason / 결과 code 정의의 SSOT

안내 본 API 의 detailCode 산출 규칙은 위 결과 응답 명세서(§6)와 완전히 동일합니다. 본 문서는 그 detailCode 를 시간대별로 집계하여 제공하는 통계 엔드포인트만 정의합니다.

1. 요청 사양 (Request)​

항목값
MethodGET
Path/statistics/detail-code
실제 호출 URLhttp://{서버IP}:8060/statistics/detail-code (포트 8060)
인증무토큰 (서버 간 연동)
Content-Type없음 (GET, 쿼리스트링)

고객 시스템은 포트 8060 으로 호출합니다. Context-Path 는 없습니다.

1.1 요청 파라미터​

이름타입필수형식설명
fromString필수yyyyMMddHHmmss (14자리)조회 시작일시 (해당 시각 포함)
toString필수yyyyMMddHHmmss (14자리)조회 종료일시 (해당 시각 포함)
항목규칙
형식from / to 는 14자리 숫자
오류유효한 일시가 아니거나 from > to 이면 400
조회 기준무해화 요청 시각

1.2 요청 예시​

GET /statistics/detail-code?from=20260727090000&to=20260727105959
항목값
의미2026-07-27 09:00:00 ~ 10:59:59 기간의 통계

2. 응답 사양 (Response)​

조회 기간 내의 데이터를 1시간 단위(yyyyMMddHH0000) 로 묶고, 각 시간대별로 detailCode 의 발생 건수를 반환합니다.

항목값
응답 포맷JSON Array
HTTP Status200 OK

2.1 필드 설명​

KEYTYPE설명
dateString해당 시간대의 기준 시각 (yyyyMMddHH0000)
count0NumberdetailCode = 0 (위험요소 없음/안전) 건수
count1NumberdetailCode = 1 (위험요소 있음) 건수
count2NumberdetailCode = 2 (백신 검출) 건수
count3NumberdetailCode = 3 (미지원/예외·차단) 건수
count-1NumberdetailCode = -1 (오류) 건수
항목규칙
필드명count + detailCode 값 (0→count0 … 3→count3, -1→count-1)
오류 집계detailCode = -1 → count-1. count4 는 사용하지 않음
JSON 접근count-1 은 obj["count-1"] (점 접근 obj.count-1 불가)
없는 코드해당 시간대에 없으면 0
빈 시간대요청이 없어도 응답에 포함, 모든 count 는 0
정렬date 오름차순

2.2 응답 예시​

[
  {
    "date": "20260727090000",
    "count0": 100,
    "count1": 1,
    "count2": 2,
    "count3": 0,
    "count-1": 0
  },
  {
    "date": "20260727100000",
    "count0": 100,
    "count1": 2,
    "count2": 5,
    "count3": 0,
    "count-1": 1
  }
]
시간대의미
20260727090000 (09시)안전 100건, 위험요소 있음 1건, 백신 검출 2건
20260727100000 (10시)안전 100건, 위험요소 있음 2건, 백신 검출 5건, 오류 1건 (count-1)

3. detailCode → count 매핑​

detailCode 의 의미와 산출 규칙은 무해화 결과 응답 명세서 §6 와 동일하며, 본 API 는 그 값을 아래와 같이 count 버킷으로 집계합니다.

detailCode의미집계 버킷
0위험요소 없음 (안전)count0
1위험요소 있음 (의심·경고·위험·위변조)count1
2백신(바이러스) 검출count2
3미지원 파일 (예외·차단)count3
-1오류count-1
항목규칙
키 명명count + detailCode (-1 → count-1)
사용하지 않음count4 (코드 값이 다름). 응답에 포함하지 않음

3.1 산출 규칙 요약 (결과 명세서와 동일)​

먼저 매칭되는 규칙을 적용합니다.

우선순위조건결과
1명시적 로그리즌아래 로그리즌 표
2재구성 완료 (200000, 200001)아래 위험도 표
3오류detailCode = -1 → count-1
4그 외detailCode = 0 → count0

로그리즌 → detailCode

로그리즌detailCode집계
2000040count0
200005, 200006, 200007, 220355, 230133, 2403551count1
9900032count2
210211, 230213, 2402153count3

재구성 완료 시 위험도 → detailCode (200000, 200001)

위험도 (threatLevelCode)의미detailCode집계
1안전0count0
2, 3, 4, 6의심·경고·위험·위변조1count1
5심각2count2

4. 집계 로직​

항목규칙
시간대 그룹핑무해화 요청 시각을 yyyyMMddHH0000 으로 절삭. 예) 09:00:00 ~ 09:59:59 → 20260727090000
집계 대상완료된 결과만 (code ∈ {0, 1, 2}). 진행 중(code = 3)은 제외
빈 시간대고객이 준 from / to 를 그대로 사용. 해당 구간의 모든 시간대를 응답에 포함. 요청이 없으면 count 는 전부 0. 과거·현재·미래를 잘라내지 않음
정렬date(시간대) 오름차순
집계 스코프조회 기간 내 전체 무해화 결과

5. 오류 응답​

HTTP조건Body 예시
400 Bad Requestfrom/to 누락·형식 오류(14자리 아님·잘못된 일시)·from > to{ "code": 400, "message": "'from' is required (yyyyMMddHHmmss)" }
502 Bad Gateway서버 내부 처리 실패{ "code": 502, "message": "statistics call failed: ..." }
{
  "code": 400,
  "message": "'from' must be 14 digits (yyyyMMddHHmmss): 202607270900"
}

6. 호출 사용 예제 및 기대 결과​

실제 배포 서버(예: 10.10.12.226, 포트 8060·http)에서 2026-07-27 09:00:00 ~ 10:59:59 구간을 조회하는 전체 예제입니다.

6.1 주소(URL) 호출 예제​

http://10.10.12.226:8060/statistics/detail-code?from=20260727090000&to=20260727105959
항목값
호스트10.10.12.226 을 실제 서버로 대체
포트8060
방화벽고객 시스템 → 서버 8060/tcp

6.2 curl 호출 예제​

curl -G "http://10.10.12.226:8060/statistics/detail-code" \
     --data-urlencode "from=20260727090000" \
     --data-urlencode "to=20260727105959"

6.3 기대 결과 예제 (200 OK)​

위 요청에 대한 응답 예시입니다. 09시 대와 10시 대 두 시간대의 detailCode 별 건수가 반환됩니다.

[
  {
    "date": "20260727090000",
    "count0": 100,
    "count1": 1,
    "count2": 2,
    "count3": 0,
    "count-1": 0
  },
  {
    "date": "20260727100000",
    "count0": 100,
    "count1": 2,
    "count2": 5,
    "count3": 0,
    "count-1": 1
  }
]
시간대count0count1count2count3count-1의미
20260727090000 (09:00:00~09:59:59)1001200안전 100, 위험요소 있음 1, 백신 검출 2
20260727100000 (10:00:00~10:59:59)1002501안전 100, 위험요소 있음 2, 백신 검출 5, 오류 1

6.4 파라미터 오류 예제 (400 Bad Request)​

from 을 14자리 미만으로 보낸 경우:

http://10.10.12.226:8060/statistics/detail-code?from=202607270900&to=20260727105959
{
  "code": 400,
  "message": "'from' must be 14 digits (yyyyMMddHHmmss): 202607270900"
}

7. 빈 시간대 · 데이터 없음 예제​

조회 기간 내에 완료된 무해화 결과가 하나도 없어도 빈 배열을 반환하지 않습니다. from / to 가 속한 모든 시간대를 0 건으로 채웁니다.

예) from=20260727090000, to=20260727115959 이고 09시·11시에 요청이 없고 10시에만 데이터가 있는 경우:

시간대데이터응답
09시없음모든 count 0
10시있음실제 건수
11시없음모든 count 0
[
  {
    "date": "20260727090000",
    "count0": 0,
    "count1": 0,
    "count2": 0,
    "count3": 0,
    "count-1": 0
  },
  {
    "date": "20260727100000",
    "count0": 100,
    "count1": 2,
    "count2": 5,
    "count3": 0,
    "count-1": 1
  },
  {
    "date": "20260727110000",
    "count0": 0,
    "count1": 0,
    "count2": 0,
    "count3": 0,
    "count-1": 0
  }
]

기간 전체에 데이터가 없어도 동일하게 시간대 수만큼 count0~`count3·count-1` 이 0 인 객체가 반환됩니다.

8. 호출 경로​

http://{서버IP}:8060/statistics/detail-code?from=yyyyMMddHHmmss&to=yyyyMMddHHmmss
항목값
포트8060
Context-Path없음

변경 이력​

날짜문서 버전내용
2026-08-136.2026.0813.01빈 시간대 0건 포함. 오류(detailCode = -1)는 count-1 로 집계 (count4 미사용). 응답 구간은 요청 from / to 그대로. 호출 URL은 :8060/statistics/detail-code.
2026-08-066.2026.0806.05최초 배포 — GET /statistics/detail-code 시간대별 detailCode 통계 API