실시간 복합 이벤트 수신
WebSocket으로 복합 이벤트를 실시간으로 수신하는 방법을 설명합니다.
마지막 업데이트: 1980년 1월 1일
WebSocket
/api/v1/ws/composite-events설명
이 WebSocket 엔드포인트는 새로 생성되는 복합 이벤트를 실시간으로 스트리밍합니다.
연결이 성립되면 서버는 먼저 hello 텍스트 메시지를 한 번 보냅니다.
그 이후 도착하는 비어 있지 않은 JSON 메시지는 단일 복합 이벤트 조회 응답과 동일한 복합 이벤트 payload를 따릅니다.
인증
WebSocket 연결을 생성할 때 Authorization 헤더에 Access Token을 포함해야 합니다.
헤더 형식은 Authorization: Bearer YOUR_ACCESS_TOKEN입니다.
쿼리 파라미터
이 WebSocket 엔드포인트는 별도의 쿼리 파라미터를 정의하지 않습니다.
연결 동작
- WebSocket 연결이 수락되면 서버가 즉시
hello를 보냅니다. - 연결 유지를 위해 서버가 주기적으로 빈 문자열을 보낼 수 있습니다.
- 빈 keep-alive 메시지는 무시하고, 비어 있지 않은 JSON 메시지만 복합 이벤트 payload로 처리하면 됩니다.
이벤트 메시지 형식
초기 hello 이후 수신되는 메시지는 아래 구조를 따릅니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
{
"id": "composite_evt_123",
"group_key": "edge-01:normal_speech_female",
"rule": {
"id": "rule_001",
"name": "Repeated Speech Cluster",
"description": "Groups repeated speech events within the same window",
"window_seconds": 30,
"min_events": 3,
"enabled": true,
"group_by": "label_id",
"include_label_ids": [
"normal_speech_female"
],
"include_mic_ids": [
"mic_001",
"mic_002"
]
},
"events": [
{
"id": "evt_001",
"confidence": 0.93,
"confidence_threshold": 0.5,
"sound_level": 71.2,
"sound_level_threshold": 65,
"description": "Repeated speech detected near entrance",
"audio_file": {
"file_path": "/audio/events/evt_001.wav"
},
"is_read": false,
"read_at": null,
"created_at": "2026-03-26T09:00:00Z",
"updated_at": "2026-03-26T09:00:05Z",
"label_id": "normal_speech_female",
"mic_id": "mic_001",
"label": {
"id": "normal_speech_female",
"name": {
"ko": "female speech",
"en": "normal speech female"
},
"active": true
},
"microphone": {
"id": "mic_001",
"name": "Entrance Mic",
"host": "172.16.10.21",
"subnet_mask": "255.255.255.0",
"mac_address": "00:11:22:33:44:55",
"microphone_type": "PDM_715IP",
"channel": {
"scheme": "rtsp",
"port": 554,
"path": "/stream",
"username": null,
"password": null
},
"console": {
"scheme": "http",
"port": 80,
"path": "/",
"username": "admin",
"password": "password"
},
"streaming": true,
"recording": true,
"edge_id": "edge_001",
"location": {
"latitude": 37.546344,
"longitude": 126.944322
},
"status": "active",
"thresholds": {},
"created_at": "2026-03-01T00:00:00Z",
"updated_at": "2026-03-26T09:00:05Z",
"deleted_at": null,
"reported_at": "2026-03-26T09:00:05Z",
"connected": true
}
}
],
"mics": [
{
"id": "mic_001",
"name": "Entrance Mic",
"host": "172.16.10.21",
"subnet_mask": "255.255.255.0",
"mac_address": "00:11:22:33:44:55",
"microphone_type": "PDM_715IP",
"channel": {
"scheme": "rtsp",
"port": 554,
"path": "/stream",
"username": null,
"password": null
},
"console": {
"scheme": "http",
"port": 80,
"path": "/",
"username": "admin",
"password": "password"
},
"location": {
"latitude": 37.546344,
"longitude": 126.944322
},
"streaming": true,
"recording": true,
"status": "active",
"created_at": "2026-03-01T00:00:00Z",
"updated_at": "2026-03-26T09:00:05Z",
"deleted_at": null,
"reported_at": "2026-03-26T09:00:05Z",
"connected": true,
"edge_id": "edge_001",
"edge_status": "active"
}
],
"labels": [
{
"id": "normal_speech_female",
"name": {
"ko": "female speech",
"en": "normal speech female"
},
"active": true
}
],
"started_at": "2026-03-26T08:59:45Z"
}연결 예시
npx wscat -c "ws://{{EDGE_IP}}:8100/api/v1/ws/composite-events" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"