> 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/monitoring-and-analytics/vision-events/query-events.md). # 이벤트 조회 ## 소개 이 페이지에서는 특정 [Vision Events](/deployment/ko/monitoring-and-analytics/vision-events.md) - 배포된 모델이 관찰한 내용의 타임스탬프가 찍힌 기록 - 을 Vision Events 대시보드에서 필터링하고 검색하거나 REST API를 통해 프로그래밍 방식으로 확인하는 방법을 다룹니다. 날짜 범위, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지된 클래스 또는 피드백 상태로 결과를 좁혀 운영 동작을 감사하고 보고서를 작성하세요. ## 웹 앱 ### 이벤트 쿼리 및 필터링 Vision Events 대시보드의 필터를 사용하거나 REST API를 통해 프로그래밍 방식으로 쿼리하여 특정 이벤트를 찾습니다. #### 대시보드에서 이벤트 찾아보기 **사용 사례 선택** Vision Events 페이지에서 사용 사례를 클릭하여 해당 이벤트를 봅니다. 이벤트는 최신순으로 표시됩니다.
**이벤트 필터링** 이벤트 목록 상단의 필터 컨트롤을 사용하여 다음 기준으로 결과를 좁힐 수 있습니다: * **날짜 범위** - 시작 및 종료 타임스탬프 * **이벤트 유형** - quality\_check, inventory\_count, safety\_alert, custom, operator\_feedback * **디바이스** - 디바이스 ID로 필터링 * **스트림** - 스트림 또는 카메라 ID로 필터링 * **워크플로** - 이벤트를 생성한 워크플로로 필터링 * **감지** - 감지된 객체 클래스로 필터링하며, 선택적으로 신뢰도 임계값을 설정할 수 있습니다 * **피드백 상태** - correct, incorrect, inconclusive 또는 no feedback * **사용자 정의 메타데이터** - 모든 사용자 지정 메타데이터 필드 및 값으로 필터링 * **경고** - 수집 경고가 있었던 이벤트만 표시 또한 이벤트 세부 정보 사이드바의 값(예: 디바이스 ID, 스트림, 품질 검사 결과 또는 사용자 지정 메타데이터 값)을 클릭하여 빠르게 필터로 추가할 수 있습니다. 필터 칩은 편집할 수 있습니다. 활성 필터 칩을 클릭하면 제거했다가 다시 추가하지 않아도 값이나 연산자를 수정할 수 있습니다. 필터가 적용되면 **총 개수** 의 일치하는 이벤트가 결과 목록 상단에 표시됩니다. 이 개수는 이벤트 목록과 독립적으로 업데이트되므로, 이벤트가 아직 로드 중이더라도 필터와 일치하는 이벤트 수를 확인할 수 있습니다.
**이벤트 세부 정보 보기** 목록의 아무 이벤트나 클릭하여 전체 세부 정보를 볼 수 있습니다: * 소스 이미지 및 출력 이미지 * 모든 소스 메타데이터(디바이스, 스트림, 워크플로) * 신뢰도 점수가 포함된 객체 감지, 분류 및 세그멘테이션 * 이벤트 유형별 데이터(예: 통과/실패 결과, 항목 수, 경고 심각도) * 사용자 지정 메타데이터 키-값 쌍 **감지 결과 그리기** 이벤트에 예측 데이터(객체 감지, 인스턴스 세그멘테이션 또는 키포인트)가 포함되어 있으면 이미지 위에 "감지 결과 그리기" 체크박스가 나타납니다. 이를 활성화하면 소스 이미지 위에 바운딩 박스, 세그멘테이션 폴리곤 및 신뢰도 점수가 포함된 레이블을 오버레이할 수 있습니다. 이는 파이프라인이 원본 입력 이미지만 저장하고 별도의 출력 이미지를 저장하지 않은 상태에서 모델이 무엇을 감지했는지 시각화하고 싶을 때 유용합니다. {% hint style="info" %} 별도의 출력 이미지를 볼 때는 이미 감지 결과가 렌더링되어 있으므로 이 체크박스는 숨겨집니다. {% endhint %} **자동 확정된 이벤트** 자동 확정으로 표시된 이벤트는 비디오 업로드가 끝나기 전에 엣지 디바이스에서 자동으로 종료되었으므로 비디오가 없습니다. 그래도 이벤트에는 결과와 정지 이미지가 포함됩니다. 이벤트 카드에는 표시가 나타나고, 세부 정보 보기에는 확정된 시간이 표시됩니다. 이는 다음을 통해 동기화된 이벤트에만 적용됩니다 [엣지 디바이스 백업](/deployment/ko/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup). ## HTTP API ### API를 통해 이벤트 쿼리 쿼리 엔드포인트는 대시보드와 동일한 필터를 지원하며, 커서 기반 페이지 매김도 지원합니다. 전체 매개변수와 응답 필드 목록은 [Vision Events API 레퍼런스](/deployment/ko/monitoring-and-analytics/vision-events.md#http-api). #### 기본 쿼리 ```bash curl -X POST "https://api.roboflow.com/vision-events/query" \ -H "Content-Type: application/json" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -d '{ "useCaseId": "assembly-line-qa", "startTime": "2026-03-01T00:00:00Z", "endTime": "2026-03-31T23:59:59Z", "limit": 25 }' ``` **응답:** ```json { "events": [ { "eventId": "evt-789ghi", "eventType": "quality_check", "timestamp": "2026-03-30T14:30:00.000Z", "deviceId": "factory-cam-01", "streamId": "line-3", "images": [], "eventData": { "result": "fail" }, "customMetadata": { "line_id": "line-3", "shift": "morning", "part_number": "PN-4421" } } ], "nextCursor": "eyJ0cyI6IjIwMjYtMDMtMzAifQ==", "hasMore": true } ``` #### 페이지 매김 결과는 커서를 사용하여 페이지 매김됩니다. 응답에 `nextCursor` 값과 `hasMore` 은 `true`가 포함되어 있으면, 다음 요청에서 커서를 전달하여 다음 페이지를 가져오세요: ```bash curl -X POST "https://api.roboflow.com/vision-events/query" \ -H "Content-Type: application/json" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -d '{ "useCaseId": "assembly-line-qa", "limit": 25, "cursor": "eyJ0cyI6IjIwMjYtMDMtMzAifQ==" }' ``` 까지 계속 `hasMore` 은 `false`. #### 이벤트 유형별 필터링 단일 이벤트 유형을 쿼리합니다: ```json { "useCaseId": "assembly-line-qa", "eventType": "quality_check" } ``` 또는 여러 이벤트 유형(최대 20개): ```json { "useCaseId": "assembly-line-qa", "eventTypes": ["quality_check", "operator_feedback"] } ``` #### 피드백 상태별 필터링 다음을 사용하세요 `feedbackStatus` 이벤트가 운영자에 의해 검토되었는지와 어떻게 평가되었는지를 기준으로 이벤트를 찾습니다: ```json { "useCaseId": "assembly-line-qa", "feedbackStatus": ["incorrect", "none"] } ``` 유효한 값: `correct`, `incorrect`, `inconclusive`, `none`를 반환합니다. `none` 아직 검토되지 않은 이벤트를 찾습니다. #### 사용자 지정 메타데이터별 필터링 다음을 사용하세요 `customMetadataFilters` 자신의 메타데이터 필드로 이벤트를 필터링합니다: ```json { "useCaseId": "assembly-line-qa", "customMetadataFilters": [ { "key": "line_id", "operator": "eq", "value": "line-3" }, { "key": "shift", "operator": "eq", "value": "morning" } ] } ``` ### 비전 이벤트 조회 필터, 시간 범위 및 페이지 매김을 사용해 비전 이벤트를 쿼리합니다. 이 엔드포인트는 이벤트 유형, 디바이스 컨텍스트, 감지 클래스, 사용자 지정 메타데이터 및 이벤트별 필드로 필터링을 지원합니다. **필수 스코프:** `vision-events:read` 또는 `device:read` {% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/query" method="post" %} [openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-dfdc1702ad3d1a62ad0a661e9609f6bbe2fc8d4c%2Fopenapi.yaml?alt=media) {% endopenapi %} #### 예시 요청 ```bash curl -X POST "https://api.roboflow.com/vision-events/query" \ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "useCaseId": "a1b3c8e1", "startTime": "2024-01-14T00:00:00Z", "endTime": "2024-01-15T23:59:59Z", "eventTypes": ["quality_check", "safety_alert"], "customMetadataFilters": [ { "field": "temperature", "operator": "gt", "value": 70, "type": "number" } ], "limit": 50 }' ``` #### 요청 본문 매개변수 **필수 필드:** * **`useCaseId`** (string): 이벤트를 쿼리할 사용 사례 ID입니다. 방법은 [사용 사례](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md) 에서 사용 사례 ID를 찾는 방법을 참조하세요. **시간 범위 필터:** * **`startTime`** (string, ISO 8601, 선택 사항): 시간 범위의 시작입니다. * **`endTime`** (string, ISO 8601, 선택 사항): 시간 범위의 끝입니다. **이벤트 유형 필터:** * **`eventTypes`** (문자열 배열, 최대 20개, 선택 사항): 하나 이상의 이벤트 유형으로 필터링합니다. **컨텍스트 필터:** 각 컨텍스트 필터는 다음을 가진 객체입니다 `operator` 및 `value`: * **`deviceId`** (object, 선택 사항): 디바이스별 필터링. 연산자: `eq`, `neq`. * **`streamId`** (object, 선택 사항): 스트림별 필터링. 연산자: `eq`, `neq`. * **`workflowId`** (object, 선택 사항): 워크플로별 필터링. 연산자: `eq`, `neq`. * **`externalId`** (object, 선택 사항): 외부 ID별 필터링. 연산자: `eq`, `neq`. ```json { "deviceId": { "operator": "eq", "value": "camera-node-5" } } ``` **감지 필터:** * **`detection`** (object, 선택 사항): 감지 클래스 이름으로 이벤트를 필터링하며, 선택적으로 감지별 신뢰도 임계값과 결합할 수 있습니다. 연산자: `eq`, `neq`, `in`, `not_in`. `in` 및 `not_in`의 경우, 값으로 문자열 배열을 전달합니다(최대 50개). * **`confidence`** (object, 선택 사항): 감지별 신뢰도 임계값입니다. 다음과 함께만 지원됩니다 `eq` 및 `in` 클래스 연산자. 클래스와 신뢰도는 동일한 감지에서 일치해야 합니다. * **`operator`** (문자열): 다음 중 하나: `gt`, `gte`, `lt`, `lte`. * **`value`** (숫자): 0과 1 사이의 신뢰도 임계값입니다. ```json { "detection": { "operator": "in", "value": ["defect", "crack"] } } ``` 최소 신뢰도로 클래스를 필터링: ```json { "detection": { "operator": "eq", "value": "scratch", "confidence": { "operator": "gte", "value": 0.8 } } } ``` {% hint style="info" %} 다음 `detection` 필터는 이전에 다음 이름으로 불렸습니다 `detectionClass`. 이전 이름은 더 이상 허용되지 않습니다. {% endhint %} **이미지 및 경고 필터:** * **`imageCount`** (object, 선택 사항): 이벤트에 첨부된 이미지 수로 필터링합니다. 연산자: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`. * **`hasWarnings`** (boolean, 선택 사항): 수집 경고가 있는 이벤트 또는 없는 이벤트로 필터링합니다. ```json { "imageCount": { "operator": "gte", "value": 1 } } ``` **사용자 지정 메타데이터 필터:** * **`customMetadataFilters`** (array, 최대 20개, 선택 사항): 사용자 지정 메타데이터 필드로 필터링합니다. 각 필터에는 다음이 있습니다: * **`필드`** (string): 메타데이터 필드 이름. * **`operator`** (string): 비교 연산자. * **`value`**: 비교할 값. * **`type`** (string): 값 유형, 다음 중 하나 `문자열`, `숫자`, 또는 `boolean`. 유형별 사용 가능한 연산자: | 유형 | 연산자 | | --------- | ------------------------------------- | | `문자열` | `eq`, `neq`, `in`, `not_in` | | `숫자` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` | | `boolean` | `eq`, `neq` | **이벤트 필드 필터:** * **`eventFieldFilters`** (array, 최대 20개, 선택 사항): 이벤트별 필드로 필터링합니다. 각 필터에는 다음이 있습니다: * **`열`** (문자열): 다음 중 하나: `result`, `location`, `item_count`, `item_type`, `alert_type`, `severity`, 또는 `feedback`. * **`operator`** (string): 비교 연산자(`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`). * **`value`**: 비교할 값. ```json { "eventFieldFilters": [ { "column": "result", "operator": "eq", "value": "fail" } ] } ``` **페이지 매김:** * **`커서`** (string, 선택 사항): 다음 페이지를 가져오기 위해 이전 응답의 커서입니다. * **`limit`** (number, 선택 사항, 기본값 100, 최대 1000): 페이지당 반환할 이벤트 수. #### 예시 응답 {% tabs %} {% tab title="200" %} ```json { "events": [ { "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "eventType": "quality_check", "timestamp": "2024-01-15T10:30:00.000Z", "images": [ { "label": "inspection-photo", "objectDetections": [ { "class": "defect", "x": 100, "y": 200, "width": 50, "height": 30, "confidence": 0.95 } ] } ], "eventData": { "result": "fail", "externalId": "batch-001" }, "customMetadata": { "line": "A1", "temperature": 72.5 } } ], "hasMore": false, "lookbackDays": 14 } ``` 다음일 때 `hasMore` 은 `true`, 다음을 사용하세요. `nextCursor` 를 다음 요청의 값으로 사용해 결과의 다음 페이지를 가져오세요: ```json { "events": [...], "hasMore": true, "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAxLTE1IiwiZXZlbnRJZCI6InFjLTAwMSJ9", "lookbackDays": 14 } ``` {% endtab %} {% tab title="400" %} ```json { "error": "잘못된 쿼리: useCaseId가 필요합니다" } ``` {% endtab %} {% tab title="403" %} ```json { "error": "이 리소스에 대한 권한이 충분하지 않습니다." } ``` {% endtab %} {% endtabs %} ## Python SDK 필터, 시간 범위 및 페이지 매김을 사용해 비전 이벤트를 쿼리합니다. ### 단일 페이지 쿼리 다음을 사용하세요 `query_vision_events()` 단일 결과 페이지를 가져오려면: ```python import roboflow roboflow.login() rf = roboflow.Roboflow() ws = rf.workspace() page = ws.query_vision_events( "a1b3c8e1", # 사용 사례 ID(필수) event_type="quality_check", # 단일 이벤트 유형으로 필터링 start_time="2024-01-14T00:00:00Z", # ISO 8601 시작 시간 end_time="2024-01-15T23:59:59Z", # ISO 8601 종료 시간 limit=50, # 페이지당 최대 이벤트 수 ) for evt in page["events"]: print(evt["eventId"], evt["eventData"]) ``` 추가 필터도 키워드 인수로 전달할 수 있습니다. 이는 API로 직접 전달됩니다: ```python page = ws.query_vision_events( "a1b3c8e1", event_types=["quality_check", "safety_alert"], deviceId={"operator": "eq", "value": "camera-node-5"}, customMetadataFilters=[ {"field": "temperature", "operator": "gt", "value": 70, "type": "number"} ], eventFieldFilters=[ {"column": "result", "operator": "eq", "value": "fail"} ], ) ``` 수동 페이지 매김의 경우 `커서` 매개변수와 `nextCursor` 이전 응답의 값을 사용하세요: ```python all_events = [] page = ws.query_vision_events("a1b3c8e1", limit=100) all_events.extend(page.get("events", [])) while page.get("hasMore"): page = ws.query_vision_events("a1b3c8e1", cursor=page["nextCursor"], limit=100) all_events.extend(page.get("events", [])) ``` ### 모든 결과를 통해 페이지 매김 다음을 사용하세요 `query_all_vision_events()` 모든 일치 이벤트를 자동으로 페이지 매김합니다. 한 번에 한 페이지씩 이벤트를 반환합니다: ```python all_events = [] for page in ws.query_all_vision_events( "a1b3c8e1", event_type="quality_check", start_time="2024-01-14T00:00:00Z", end_time="2024-01-15T23:59:59Z", ): all_events.extend(page) print(f"{len(all_events)}개의 이벤트를 찾았습니다") ``` 사용 가능한 필터, 연산자 및 응답 형식에 대한 전체 세부 정보는 다음을 참조하세요 [REST API 참조](#http-api).