メインコンテンツまでスキップ

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

ログリゼン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)​

from14桁未満で送信した場合:

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時なしすべての count0
10時あります実際の件数
11時なしすべての count0
[
  {
    "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