> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/services/event-store/rest-api.md). # Event Store REST API 이벤트 스키마와 관리 경로를 포함한 온디바이스 Event Store v2 API의 엔드포인트 레퍼런스입니다. Event Store는 관리형 디바이스에서 실행되며 해당 디바이스에서 파이프라인이 생성한 추론 이벤트를 저장합니다. 기본 URL은 `http://:8001`, 그리고 대화형 Swagger 문서는 다음에서 제공됩니다 `/docs`. 다음을 참조하세요 [서비스](/deployment/ko/self-hosted/enterprise/deployment-manager/services.md#using-the-apis) 기본 URL, 인증, 그리고 디바이스 내 모든 서비스 API가 공유하는 오류 형식 규칙은 다음을 참조하세요. v2 API는 camelCase 입력을 허용합니다(예: `base64Image`, `objectDetections`) 그리고 snake\_case 응답을 반환합니다. {% hint style="warning" %} 이것은 클라우드용이 아닙니다 [비전 이벤트 API](/deployment/ko/monitoring-and-analytics/vision-events.md). 로컬 계약은 다음을 사용합니다 `event_schema`, `event_data`, 그리고 `inference_timestamp` 반면 클라우드는 다음을 사용합니다 `eventType`, `useCaseId`, 그리고 `timestamp`, 그리고 업로드된 이미지에 대한 참조가 아니라 이미지 바이트를 직접 받습니다. 클라우드 페이로드는 여기서 유효하지 않습니다. {% endhint %} 만약 `API_KEY` 가 서비스에 설정되어 있으면, 다음을 제외한 모든 엔드포인트는 `/health` 다음이 필요합니다 `X-API-Key` 헤더가 필요합니다. 다음을 참조하세요 [인증](/deployment/ko/self-hosted/enterprise/deployment-manager/services/event-store.md#authentication). ```bash curl -H "X-API-Key: $EVENT_STORE_API_KEY" \\ "http://:8001/v2/events/latest/query?limit=5" ``` ## 이벤트 생성 바운딩 박스 좌표는 중심 기준 절대 픽셀입니다: `x` 그리고 `y` 는 박스의 중심이며, `너비` 그리고 `높이` 는 전체 크기입니다. 신뢰도는 0.0에서 1.0까지입니다. 설정 `draft: true` 이벤트를 열어 둔 상태로 유지해 나중에 비디오나 로컬 전용 파일을 첨부할 수 있게 한 다음, 이를 최종 확정합니다. 생략하면 `draft` 생성 시 이벤트가 최종 확정되므로 기존 프로듀서에는 영향이 없습니다. {% hint style="warning" %} `솔루션` 는 스키마에서는 선택 사항이지만 런타임에서는 조건부로 필요합니다. 서비스에서 클라우드 업로드가 활성화되어 있고 `DEFAULT_SOLUTION_ID` 가 설정되지 않은 경우, 다음 없이 이벤트를 생성하면 `솔루션` 를 반환합니다 `400`. 모든 이벤트에 보내거나 환경 변수를 설정하세요. {% endhint %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} ## 이벤트 조회 `GET /v2/events` 시간 범위, 소스, 사용자 정의 메타데이터로 필터링합니다. `metadata_filter` 는 `key:value` 또는 `key:op:value` 다음 연산자를 사용합니다 `eq`, `ne`, `gt`, `lt`, `gte`, 그리고 `lte`, 그리고 AND 논리로 반복됩니다. 이미지별 `메타데이터` 는 다음을 통해 조회할 수 없습니다 `metadata_filter`. 오직 `custom_metadata` 이벤트에 있는 것만 가능합니다. {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events/{event\_id}" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events/latest/query" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/events/count/stats" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} ## 초안 라이프사이클 합격/불합격 결정 후 인코딩된 비디오를 첨부해야 하는 프로듀서는 이벤트를 초안으로 생성하고, 파일이 준비되면 업로드한 다음, 최종 확정합니다: ```bash EVENT_ID=$(curl -s -X POST http://:8001/v2/events \\ -H "Content-Type: application/json" \\ -d '{"inference_timestamp":"2025-01-30T14:30:00Z","event_schema":"quality_check","event_data":{"result":"pass"},"solution":"a1b2c3d4e5f67890","draft":true}' \\ | jq -r '.id') curl -X POST "http://:8001/v2/events/$EVENT_ID/videos" -F "file=@clip.mp4" curl -X POST "http://:8001/v2/events/$EVENT_ID/finalize" ``` 이벤트가 최종 확정되기 전까지는 클라우드 업로드에서 건너뜁니다. 또한 정리 대상에서도 보호되지만, 이는 서비스에서 클라우드 업로드가 활성화되어 있는 동안에만 그렇습니다. 클라우드 업로드가 꺼져 있으면 초안은 다른 레코드와 마찬가지로 삭제 가능하므로, 보존 및 용량 정리가 아직 작성 중인 항목도 제거할 수 있습니다. 프로듀서가 finalize를 호출하지 않는 초안은 다음 후 강제 종료됩니다 `DRAFT_AUTO_FINALIZE_SECONDS`. 둘 다 `finalized_at` 그리고 `auto_finalized_at` 가 그 경우에 설정되므로 `auto_finalized_at` 강제 종료된 이벤트와 프로듀서가 직접 최종 확정한 이벤트를 구분하려면 이를 읽으세요. 첨부 경로는 바이트를 추가하므로 finalize와 달리 용량 백프레셔의 영향을 받습니다. 저장소가 한도를 초과하면 다음을 반환합니다 `529` 그리고 업로드는 허용되지 않습니다. {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events/{event\_id}/videos" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events/{event\_id}/local-only-files" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/v2/events/{event\_id}/finalize" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} ## 이벤트 스키마 `event_schema` 의 구조를 선택합니다 `event_data`. 각 스키마는 정의하지 않은 필드를 금지하며, 모든 필드는 camelCase와 snake\_case 표기 모두를 허용합니다. 두 필드는 서로 다르게 실패합니다. 잘못된 `event_schema` 를 반환합니다 `422`. `event_data` 지정된 스키마를 따르지 않는 페이로드는 다음을 반환합니다 `400`, 그리고 문자열을 함께 반환합니다 `detail` 스키마 이름을 명시합니다. {% tabs %} {% tab title="quality\_check" %}
필드형식필수제약
result"pass" 또는 "fail"예
externalId문자열아니요최대 1000자
```json { "result": "pass", "externalId": "SKU-12345" } ``` {% endtab %} {% tab title="inventory\_count" %}
필드형식필수제약
location문자열아니요최대 1000자
itemCount정수아니요0 이상
itemType문자열아니요최대 1000자
externalId문자열아니요최대 1000자
```json { "location": "warehouse-A", "itemCount": 42, "itemType": "widgets" } ``` {% endtab %} {% tab title="safety\_alert" %}
필드형식필수제약
alertType문자열아니요최대 256자, 문자, 숫자, 밑줄, 공백, 하이픈만 허용
severity"low", "medium"또는 "high"아니요
설명문자열아니요최대 10000자
externalId문자열아니요최대 1000자
```json { "alertType": "no_ppe", "severity": "high", "description": "Worker entered area without hard hat" } ``` {% endtab %} {% tab title="operator\_feedback" %}
필드형식필수제약
relatedEventId문자열예평가 대상 이벤트의 ID
피드백"correct", "incorrect"또는 "inconclusive"예
```json { "relatedEventId": "550e8400-e29b-41d4-a716-446655440000", "feedback": "correct" } ``` 다음으로 이들을 다시 조회하세요 `related_event_id` 필터를 사용한 `GET /v2/events`. {% endtab %} {% tab title="사용자 정의" %}
필드형식필수제약
externalId문자열아니요최대 1000자
값문자열아니요최대 10000자
```json { "externalId": "sensor-123", "value": "temperature:72.5" } ``` 이 필드에 맞지 않는 구조화된 데이터는 다음을 사용하세요 `custom_metadata` 이벤트의 다음을 사용하면 조회할 수 있으며, 또는 이미지별 `메타데이터`, 이는 조회할 수 없습니다. {% endtab %} {% endtabs %} ## 파일 다운로드 이미지 ID는 일시적입니다. 정리 작업은 언제든 파일을 제거할 수 있으므로, 이를 처리하세요 `404` 하고 ID를 단일 세션 이상 캐시하지 마세요. 다음을 비교하세요 `current_file_count` 와 `original_file_count` 와 비교하여 이벤트의 파일이 정리되었는지 확인합니다. {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/images/{image\_id}" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/videos/{video\_id}" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/local-only-files/{file\_id}" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} ## 통계 및 상태 `/stats` 현재 사용량, 활성 구성, 각 한도 대비 용량, 그리고 다음 정리 작업에서 삭제될 항목을 보고합니다. 다음에 대해 알림을 설정하세요 `capacity.storage.percent_used` 그리고 `capacity.records.percent_used` 80% 초과. {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/stats" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/health" method="get" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} ## 관리 {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/admin/cleanup" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} 초기화는 두 번 호출해야 하므로 실수로 발생할 수 없습니다. `/reset/request` 는 60초 동안 유효한 일회용 토큰을 반환하며, `/reset/confirm` 삭제를 수행합니다. {% hint style="danger" %} 확인된 초기화는 저장소의 모든 이벤트와 파일을 영구적으로 삭제합니다. 되돌릴 수 없습니다. {% endhint %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/reset/request" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %} {% openapi src="/files/289194a9c55be7019fdb42739dee6781cda7f4df" path="/reset/confirm" method="post" %} [edge-event-store.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-649d4e0cb1dff61d7b5026b17f0f0793798ea350%2Fedge-event-store.yaml?alt=media) {% endopenapi %}