EdgeFlow AI 연동 API

개요

연동 방식은 목적에 따라 두 가지입니다.

EdgeFlow AI 서버는 Connect RPC 규격으로 API를 제공합니다. 모든 호출은 POST /edgeflowai.v4.<서비스>/<메서드> 형태이며, 본문은 JSON입니다. 같은 경로로 gRPC·gRPC-Web 클라이언트도 사용할 수 있습니다.

빠른 시작

1. 로그인

# YOUR_SERVER·계정은 관리자가 안내한 값으로 바꿉니다.
curl -X POST "https://YOUR_SERVER/edgeflowai.v4.AuthService/Login" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  --data '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

HTTP 200이어도 로그인 실패일 수 있습니다. 응답의 ok가 true이고 token이 있을 때만 다음 단계로 진행하세요. 10회 연속 실패하면 5분간 잠기며 lockedUntil로 해제 시각을 알려 줍니다.

2. 채널 목록

curl -X POST "https://YOUR_SERVER/edgeflowai.v4.ChannelService/ListChannels" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data '{}'

버전별 공개 API

설치된 제품 버전을 선택하면 해당 버전에서 사용할 수 있는 API를 보여 줍니다.

경로는 모두 POST /edgeflowai.v4.<서비스>/<메서드>입니다. API 이름을 누르면 상세 설명과 코드 예제로 이동합니다. 이 밖의 관리 API(사용자·장비 제어·설정·업데이트 등)는 보안상 공개하지 않습니다.

공통 규칙

• 필드명은 JSON lowerCamelCase입니다(예: channelUids).
• int64·uint64 값은 JSON에서 문자열로 옵니다(예: "expiresAt":"1792432800"). 요청에는 숫자도 받습니다.
• 시각(Timestamp)은 RFC3339 UTC 문자열입니다(예: "2026-10-19T01:00:00Z").
• enum은 이름 문자열로 옵니다(예: "CHANNEL_STATE_NORMAL").
• 기본값(0, 빈 문자열, false, 빈 배열)인 필드는 응답에서 생략됩니다. 필드가 없으면 기본값으로 처리하세요.
• 일부 노드만 실패한 경우 오류 대신 성공한 결과와 warnings를 함께 반환합니다.

오류 응답

HTTP 4xx·5xx와 함께 {"code":"unauthenticated","message":"..."} 형태로 반환합니다.

API 상세

v1.4.16 기준입니다(공개 API 정의는 v1.4.15와 동일). 예시의 값은 모두 가상의 값입니다.

실시간 이벤트

EventStreamService/StreamEvents는 서버 스트리밍 API입니다. 연결을 유지한 채 이벤트가 발생할 때마다 메시지를 받습니다.

• 요청: kinds(예: va_event, alarm, node_status), channelUids로 필터
• 연결 유지: kind가 ping인 메시지가 구독 직후와 15초마다 옵니다. 무시하고, 45초 이상 아무 메시지도 없으면 재연결하세요.
• 메시지: kind, channelUid, time, json(이벤트 본문 JSON 문자열)
• 인증된 사용자는 역할과 무관하게 구독할 수 있습니다.

이벤트 데이터

이벤트는 실시간 이벤트(StreamEvents의 va_event 메시지 json)와 이벤트 이력(ListEvents의 items)으로 받습니다. 모든 이벤트가 같은 공통 필드를 갖고, 종류에 따라 일부 필드가 추가됩니다.

이벤트 흐름

하나의 이벤트는 같은 eventId로 BEGIN → CONTINUE → END 순서의 메시지로 전달됩니다.

• 라인 통과처럼 순간적인 이벤트는 BEGIN과 END가 거의 동시에 옵니다.
• 이벤트 이력(ListEvents)에는 BEGIN 시점에 한 건이 생기고, END가 오면 endTs가 채워집니다. endTs가 없으면 진행 중입니다.
• 메시지가 순서대로 오지 않거나 일부가 빠질 수 있으니 transitionSeq로 순서를 맞추고, END를 받지 못한 이벤트는 ListEvents로 상태를 확인하세요.
• 알림은 BEGIN에서 한 번만 보내고, CONTINUE·END는 같은 이벤트의 갱신으로 처리하는 것을 권장합니다.

이벤트 종류

eventType에 아래 문자열이 옵니다. ListEvents의 eventTypes 필터에도 같은 값을 씁니다.

교통량·차로 방향(좌회전·우회전·유턴)·대기 차량 등 교통 분석 이벤트는 교통 분석 옵션 도입 시 별도로 안내합니다.

공통 필드

실시간 이벤트(va_event)의 json 본문 기준입니다.

종류별 추가 필드

표준 클래스 번호

실시간 이벤트·이벤트 이력의 classId와 ListEvents의 objectTypes 필터가 쓰는 번호입니다.

• 차량은 배포된 모델에 따라 101~133의 세부 차종 번호(세단, SUV, 지게차 등)로 올 수 있습니다.
• 3000 이상은 표준에 없는 모델 고유 클래스, 1000000 이상은 현장에서 정의한 사용자 클래스입니다.
• 값 변화(ValueChange)처럼 영역을 직접 판독하는 이벤트는 classId가 대상 객체를 뜻하지 않습니다.
• SearchMetadata는 다른 번호 체계를 씁니다(사람 0, 승용차 2, 이륜차 3, 버스 4, 트럭 5, 불꽃 50, 연기 51). 같은 숫자라도 뜻이 다르니 API별로 구분하세요.

이벤트별 샘플 데이터

그룹과 이벤트를 고르면 실시간 메시지 본문(va_event의 json, BEGIN 시점)과 이력 항목(ListEvents의 items[])을 보여 줍니다. 값은 모두 예시입니다.

실시간 이벤트와 이벤트 이력의 필드 이름

같은 이벤트라도 두 API에서 일부 이름과 형식이 다릅니다.

버전 이력

v1.3.0 이후 공개·관리 API는 추가만 있었고 제거되거나 이름이 바뀐 API는 없습니다.

유의사항

• v1.3.5부터 역할 기반 권한이 적용되어, 일반 역할 토큰으로 쓰기 API를 호출하면 거부됩니다.
• ResolveSearchQuery는 서버에 로컬 AI 런타임이 설치되어 있어야 동작합니다.
• 토큰·비밀번호를 URL, 공개 저장소, 로그에 남기지 마세요. 운영 서버는 HTTPS로 접속하세요.
• 연동 전 설치된 제품 버전(VersionService/GetVersions)을 확인하고, 해당 버전에서 먼저 시험하세요.
• 관리 화면 전용 기능(사용자·권한 관리, 장비 제어, 설정, 업데이트, AI 장면 설명 관리 등)의 API는 공개하지 않습니다.