> 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/create-a-vision-event.md).

# Vision Event 생성

배포된 모델의 관측값을 기록하기 위해 HTTP API를 통해 단일 Vision Event를 기록합니다.

## 개요

하나의 [비전 이벤트](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md) 는 배포된 컴퓨터 비전 모델이 관찰한 사항(예: 감지된 결함이나 재고 수량)을 타임스탬프와 함께 기록한 것으로, 이미지, 예측 결과, 사용자 지정 메타데이터를 포함할 수도 있습니다. 이 페이지에서는 단일 이벤트를 기록하여 검색 및 필터링할 수 있는 프로덕션 이력에 추가하는 방법을 설명합니다. 여러 이벤트를 한 번에 수집하려면 [비전 이벤트 일괄 생성](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/batch-create-vision-events.md)을 사용하세요. 배포 환경에서 클라우드에 연결할 수 없다면 [비전 이벤트 번들 업로드](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-bundle.md).

## HTTP API

컴퓨터 비전 배포 환경에서 관찰한 사항을 기록할 단일 비전 이벤트를 생성합니다.

**필수 범위:** `vision-events:write` 또는 `device:update`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 이미지 메타데이터

이미지 객체의 `metadata` 를 사용하여 합격/불합격 판정, 일련번호, 카메라 각도 등 해당 이미지에만 속하는 값을 기록합니다. 이 값은 이벤트 상세 보기에서 이미지와 함께 표시됩니다. 전체 이벤트를 설명하는 값을 첨부하려면 `customMetadata` 를 사용하세요.

이미지의 `metadata` 제한을 초과하는 키는 제외되고 `warnings` 배열에 보고됩니다. 이미지의 나머지 부분은 그대로 저장됩니다.

이벤트에서 사용하는 키를 확인하려면 [이미지 메타데이터 스키마 가져오기](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/get-image-metadata-schema.md)를 호출하세요. 이 키로 이벤트를 필터링하려면 `imageMetadataFilters` 를 다음에서 사용하세요: [이벤트 쿼리](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#query-vision-events).

### 유효성 검사 및 경고

Vision Events API는 즉시 수집 방식을 사용합니다. 네 가지 필수 필드(`eventId`, `eventType`, `useCaseId`, `timestamp`)만 엄격하게 검증합니다. 이 필드가 검증을 통과하면 다른 필드에 오류가 있더라도 이벤트는 항상 수락되어 저장됩니다.

필수가 아닌 필드의 문제는 거부 사유가 되는 대신 응답의 `warnings` 배열로 반환됩니다. 여기에는 다음이 포함됩니다:

* 다음 객체의 필수 필드 누락: `eventData` (예: `relatedEventId` 필드가 필요한 이벤트 유형: `operator_feedback`)
* 다음의 잘못된 값: `eventData` 필드 (예: 잘못된 열거형 값이 사용된 필드: `severity`)
* 스키마에 포함되지 않은 인식할 수 없는 필드

경고가 있으면 유효하지 않은 `eventData` 는 빈 객체로 저장되지만 `{}`, 이벤트 자체는 계속 생성됩니다.

응답에는 지원 중단된 필드 이름을 사용한 경우 `deprecations` 배열이 포함될 수도 있습니다.

## Python SDK

컴퓨터 비전 배포 환경에서 관찰한 사항을 기록할 단일 비전 이벤트를 생성합니다.

```python
import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

ws.write_vision_event({
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
        "result": "fail",
        "externalId": "batch-001",
    },
    "customMetadata": {
        "line": "A1",
        "operator": "John Doe",
        "temperature": 72.5,
    },
})
```

이벤트 페이로드는 클라이언트 측 검증 없이 서버에 직접 전달되므로, SDK를 업데이트하지 않아도 새로운 이벤트 유형과 필드를 사용할 수 있습니다.

**필수 필드:**

* **`eventId`** (문자열, 최대 256자): 전역적으로 고유한 식별자입니다. UUID(v4)를 사용하세요.
* **`eventType`** (문자열): 다음 중 하나입니다. `quality_check`, `inventory_count`, `safety_alert`, `custom`, 또는 `operator_feedback`.
* **`useCaseId`** (문자열): 이 이벤트가 속한 사용 사례입니다.
* **`timestamp`** (문자열, ISO 8601): 이벤트가 발생한 시각입니다.

**선택적 필드:**

* **`eventData`** (딕셔너리): 이벤트 유형별 데이터입니다.
* **`deviceId`**, **`streamId`**, **`workflowId`** (문자열): 컨텍스트 식별자입니다.
* **`images`** (목록): 주석이 포함된 이미지 객체입니다. 자세한 내용은 [비전 이벤트 이미지 업로드](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#python-sdk).
* **`videos`** (목록): 비디오 객체입니다. 각 비디오의 `sourceId` 에서 가져옵니다 [비전 이벤트 비디오 업로드](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#http-api).
* **`customMetadata`** (딕셔너리): 최대 100개의 사용자 지정 메타데이터 키-값 쌍입니다.
* **`comment`** (문자열): 이벤트에 대한 메모입니다. 주로 다음 항목과 함께 사용됩니다 `operator_feedback`.

전체 이벤트 스키마, 유형별 이벤트 데이터 구조, 이미지 주석 형식은 다음을 참조하세요. [REST API 참조](#http-api).
