복합 이벤트 API 개요

Composite Event in Deeply AI System

복합 이벤트 객체#

Composite Event 객체는 여러 기본 이벤트에 복합 이벤트 규칙을 적용해 생성된 집계 레코드입니다. 여러 관련 감지를 하나의 상위 결과로 묶어 반환해야 할 때 사용합니다.

동작 방식#

복합 이벤트는 다음 조건에서 생성됩니다:

• 규칙이 정의한 시간 창 안에서 기본 이벤트를 수집하고
• 규칙이 자체 그룹화 전략으로 이벤트를 묶고
• API가 관련 마이크와 라벨을 포함한 그룹 결과를 반환할 때

Events 섹션의 공개 이벤트 객체와 달리, 복합 이벤트 내부의 events 필드는 더 많은 정보를 담은 이벤트 payload를 사용합니다. 이 중첩 이벤트에는 임계값, 오디오 파일 정보, 읽음 상태, 전체 마이크 객체가 포함됩니다.

속성#

id#

• Type: string
• Description: 복합 이벤트의 고유 식별자입니다.

---

group_key#

• Type: string
• Description: rule 설정에 따라 composite event에 부여된 grouping key입니다.

---

rule#

• Type: object
• Description: 이 composite event를 생성한 rule 정의입니다.

rule.id#

• Type: string
• Description: rule의 고유 식별자입니다.

rule.name#

• Type: string
• Description: rule의 표시 이름입니다.

rule.description#

• Type: string | null
• Description: rule에 대한 선택적 설명입니다.

rule.window_seconds#

• Type: number
• Description: rule이 base event를 그룹화할 때 사용하는 time window입니다.

rule.min_events#

• Type: integer
• Description: composite event를 형성하는 데 필요한 최소 base event 수입니다.

rule.enabled#

• Type: boolean
• Description: rule이 현재 활성화되어 있는지 여부입니다.

rule.group_by#

• Type: string
• Description: composite event의 group_key를 계산하는 grouping strategy입니다.

rule.include_label_ids#

• Type: string[] | null
• Description: rule에 설정된 label ID 목록입니다.

rule.include_mic_ids#

• Type: string[] | null
• Description: rule에 설정된 microphone ID 목록입니다.

---

events#

• Type: array
• Description: 이 composite event에 포함된 상세 base event 목록입니다.
• Reference: 이벤트 API 개요와 관련되지만, 여기의 nested object는 공개 OpenAPI event object보다 더 자세한 정보를 포함합니다.

---

mics#

• Type: array
• Description: 그룹화된 이벤트와 연결된 microphone device 목록입니다.
• Reference: 관련 device model은 마이크 장치 API 개요를 참고해 주세요.
• Shape: 각 항목은 단일 마이크 조회(GET /api/v1/mics/{mic_id}) 응답과 같은 형태입니다.

---

labels#

• Type: array
• Description: 그룹화된 이벤트와 연결된 label 목록입니다.

labels[].id#

• Type: string
• Description: label의 고유 식별자입니다.

labels[].name#

• Type: object
• Description: 다국어 label 이름입니다.
  • ko (string): 한국어 label 이름.
  • en (string): 영어 label 이름.

labels[].active#

• Type: boolean
• Description: label이 활성 상태인지 여부입니다.

---

started_at#

• Type: string, ISO 8601 format
• Description: 그룹화된 composite event window가 시작된 시점을 나타내는 timestamp입니다.
• Note: 소수 초(최대 6자리)가 붙을 수 있습니다. (예: "2026-03-26T09:00:05.123456Z") 소수 초 유무와 관계없이 ISO 8601 파서로 읽어 주세요.

---

페이지네이션 조회는 복합 이벤트 목록 조회, 단건 응답은 단일 복합 이벤트 조회, 실시간 스트림은 실시간 복합 이벤트 수신 문서를 참고해 주세요.