> 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를 기록합니다.

## 소개

하나의 [비전 이벤트](/deployment/ko/monitoring-and-analytics/vision-events.md) 는 배포된 컴퓨터 비전 모델이 관찰한 내용의 타임스탬프가 포함된 기록입니다. 예를 들어 감지된 결함이나 재고 수량과 함께 선택적 이미지, 예측, 사용자 지정 메타데이터를 포함할 수 있습니다. 이 페이지에서는 하나의 이벤트를 기록하여 검색 및 필터링이 가능한 프로덕션 기록의 일부로 만드는 방법을 보여줍니다. 한 번에 많은 이벤트를 수집하려면 [비전 이벤트 일괄 생성](/deployment/ko/monitoring-and-analytics/vision-events/batch-create-vision-events.md)을 사용하세요. 배포에 클라우드로 연결되는 경로가 없으면 다음을 참조하세요. [비전 이벤트 번들 업로드](/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-90cd0189aea08d3263ce3e004f4958cc7363d4ed%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 이미지 메타데이터

다음을 사용하세요 `메타데이터` 이미지 객체에 기록하여 통과/실패 판정, 일련번호, 카메라 각도처럼 해당 이미지에만 속하는 값을 저장하세요. 값은 이벤트 세부 정보 보기에서 이미지와 함께 표시됩니다. 전체 이벤트를 설명하는 값을 연결하려면 `customMetadata` 를 대신 사용하세요.

제한을 벗어나는 키는 삭제되어 `메타데이터` 경고 배열에 보고됩니다. `warnings` 이미지의 나머지 부분은 계속 저장됩니다.

이벤트에서 어떤 키를 사용하는지 보려면 [이미지 메타데이터 스키마 가져오기](/deployment/ko/monitoring-and-analytics/vision-events/get-image-metadata-schema.md)를 호출하세요. 이러한 키로 이벤트를 필터링하려면 `imageMetadataFilters` 를 [이벤트 조회](/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#query-vision-events).

### 검증 및 경고

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

필수 항목이 아닌 필드의 문제는 거부를 유발하는 대신 응답에서 `warnings` 배열로 반환됩니다. 여기에는 다음이 포함됩니다:

* 다음 항목 내의 필수 필드 누락: `eventData` (예: `relatedEventId` in `operator_feedback`)
* 다음 필드의 잘못된 값: `eventData` (예: 다음에 대한 잘못된 enum 값: `severity`)
* 스키마의 일부가 아닌 인식되지 않은 필드

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

응답에는 `더 이상 사용되지 않는 항목` 배열도 포함될 수 있습니다. 더 이상 사용되지 않는 필드 이름이 사용된 경우입니다.

## 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`** (리스트): 주석이 포함된 이미지 객체입니다. 다음을 참조하세요 [비전 이벤트 이미지 업로드](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#python-sdk).
* **`videos`** (리스트): 비디오 객체입니다. 각 `sourceId` 를 [비전 이벤트 비디오 업로드](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#http-api).
* **`customMetadata`** (딕셔너리): 최대 100개의 키-값 쌍으로 된 사용자 지정 메타데이터입니다.
* **`comment`** (문자열): 이벤트에 대한 메모로, 주로 다음과 함께 사용됩니다. `operator_feedback`.

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