> 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 만들기

## 소개

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

### 예시 요청

```bash
curl -X POST "https://api.roboflow.com/vision-events" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "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
    }
  }'
```

### 요청 본문 매개변수

{% hint style="info" %}
각 이벤트에는 전역적으로 고유한 `eventId`. 충돌을 피하려면 UUID(v4)를 사용하는 것을 권장합니다. 중복된 이벤트 ID는 이전에 수집된 이벤트를 덮어씁니다.
{% endhint %}

**필수 필드:**

* **`eventId`** (문자열): 이벤트의 전역 고유 식별자입니다. UUID(v4)를 사용하세요.
* **`eventType`** (문자열): 다음 중 하나: `quality_check`, `inventory_count`, `safety_alert`, `custom`, 또는 `operator_feedback`.
* **`useCaseId`** (문자열, 최대 256자): 이 이벤트가 속한 사용 사례입니다. 다음을 참조하세요. [사용 사례](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md) 를 생성하고 관리하는 방법을 확인하세요.
* **`timestamp`** (문자열, ISO 8601): 이벤트가 발생한 시각입니다. 1년 전부터 내일 사이여야 합니다.
* **`eventData`** (객체): 유형별 이벤트 데이터입니다. 아래의 [이벤트 데이터 스키마](#event-data-schemas) 에서 이벤트 유형별 필수 구조를 확인하세요.

**선택 필드:**

* **`deviceId`** (문자열, 최대 256자): 이벤트를 생성한 디바이스의 식별자입니다.
* **`streamId`** (문자열, 최대 256자): 비디오 스트림의 식별자입니다.
* **`workflowId`** (문자열, 최대 256자): 이벤트를 생성한 워크플로의 식별자입니다.
* **`workflowVersion`** (문자열, 최대 64자): 워크플로 버전입니다.
* **`images`** (배열, 최대 1000개): 주석이 달린 이미지 객체의 배열입니다. 다음을 참조하세요. [이미지 객체](#image-objects) 아래.
* **`displayImagePosition`** (숫자, 0-999): 기본 표시 이미지로 사용할 이미지의 배열 내 인덱스 위치입니다. `images` 예를 들어, `0` 첫 번째 이미지의 경우, `1` 두 번째 이미지의 경우, 이후도 마찬가지입니다.
* **`customMetadata`** (객체, 최대 100개 키): 사용자 지정 메타데이터의 키-값 쌍입니다. 다음을 참조하세요. [사용자 지정 메타데이터](#custom-metadata) 아래.
* **`comment`** (문자열, 최대 1000자): 이벤트에 대한 메모입니다. 함께 사용하면 `operator_feedback`, 검토자의 메모가 들어갑니다.

### 이벤트 데이터 스키마

다음의 구조는 `eventData` 다음에 따라 달라집니다. `eventType`:

{% tabs %}
{% tab title="quality\_check" %}

```json
{
  "result": "pass",
  "externalId": "batch-001"
}
```

* **`result`** (문자열, 선택 사항): `"pass"` 또는 `"fail"`.
* **`externalId`** (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.
  {% endtab %}

{% tab title="inventory\_count" %}

```json
{
  "location": "warehouse-a",
  "itemCount": 42,
  "itemType": "pallets",
  "externalId": "inv-2024-001"
}
```

* **`location`** (문자열, 최대 1000자, 선택 사항): 수량이 측정된 위치입니다.
* **`itemCount`** (정수, 0 이상, 선택 사항): 계산된 항목 수입니다.
* **`itemType`** (문자열, 최대 1000자, 선택 사항): 계산된 항목의 유형입니다.
* **`externalId`** (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.
  {% endtab %}

{% tab title="safety\_alert" %}

```json
{
  "alertType": "no_hardhat",
  "severity": "high",
  "description": "Worker detected without required PPE in zone B3.",
  "externalId": "alert-2024-001"
}
```

* **`alertType`** (문자열, 최대 256자, 선택 사항): 경고 유형(영숫자, 밑줄, 하이픈).
* **`severity`** (문자열, 선택 사항): `"low"`, `"medium"`, 또는 `"high"`.
* **`description`** (문자열, 최대 10000자, 선택 사항): 경고에 대한 설명입니다.
* **`externalId`** (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.
  {% endtab %}

{% tab title="custom" %}

```json
{
  "value": "Custom event data as a string",
  "externalId": "custom-2024-001"
}
```

* **`value`** (문자열, 최대 10000자, 선택 사항): 자유 형식 이벤트 데이터입니다.
* **`externalId`** (문자열, 최대 1000자, 선택 사항): 외부 참조 ID입니다.
  {% endtab %}

{% tab title="operator\_feedback" %}

```json
{
  "relatedEventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "feedback": "incorrect"
}
```

* **`relatedEventId`** (문자열, 필수): 이 피드백이 대상인 이벤트의 이벤트 ID(UUID)입니다.
* **`feedback`** (문자열, 필수): `"correct"`, `"incorrect"`, 또는 `"inconclusive"`.

검토자의 메모는 최상위 `comment` 필드에 들어가며, 다음에는 `eventData`.
{% endtab %}
{% endtabs %}

### 이미지 객체

이벤트에 이미지를 첨부하려면 먼저 각 이미지를 다음을 사용해 업로드해야 합니다. [비전 이벤트 이미지 업로드](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#http-api) 엔드포인트를 사용해 `sourceId`. 각 이미지 객체는 `images` 배열에서 주석이 달린(출력) 이미지를 나타냅니다. 원본 주석 없는(입력) 이미지도 연결하려면 별도로 업로드한 다음 해당 `sourceId` 를 `inputSourceId`.

```json
{
  "label": "inspection-photo",
  "sourceId": "img-source-123",
  "inputSourceId": "camera-1",
  "objectDetections": [
    {
      "class": "defect",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.95
    }
  ],
  "classifications": [
    {
      "class": "damaged",
      "confidence": 0.87
    }
  ],
  "instanceSegmentations": [
    {
      "class": "crack",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.92,
      "points": [[100, 200], [120, 210], [110, 230]]
    }
  ],
  "keypoints": [
    {
      "class": "joint",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.88,
      "keypoints": [
        { "id": 0, "x": 105, "y": 205, "occluded": false },
        { "id": 1, "x": 115, "y": 215 }
      ]
    }
  ]
}
```

**이미지 필드:**

* **`label`** (문자열, 선택 사항): 이미지 레이블입니다.
* **`sourceId`** (문자열, 선택 사항): `sourceId` 주석이 달린 이미지를 업로드하여 반환된 [\`sourceId\`](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#http-api).
* **`inputSourceId`** (문자열, 선택 사항): `sourceId` 원본 주석 없는(입력) 이미지를 업로드하여 반환된 \`inputSourceId\`입니다.
* **`objectDetections`** (배열, 최대 1000개, 선택 사항): 다음 필드를 포함한 바운딩 박스 탐지 결과 `class`, `x`, `y`, `width`, `height`그리고 `confidence` (0-1).
* **`classifications`** (배열, 최대 1000개, 선택 사항): 다음을 포함한 분류 결과 `class` 및 `confidence` (0-1).
* **`instanceSegmentations`** (배열, 최대 1000개, 선택 사항): 바운딩 박스 필드와 다음을 포함한 세분화 결과 `points` (다음으로 이루어진 배열 `[x, y]` 쌍, 최소 3개).
* **`keypoints`** (배열, 최대 1000개, 선택 사항): 바운딩 박스 필드와 다음을 포함한 키포인트 탐지 결과 `keypoints` (다음 속성을 가진 객체 배열 `id`, `x`, `y`, 그리고 선택적 `occluded`, 탐지당 최소 1개 키포인트).

### 사용자 지정 메타데이터

각 이벤트에 최대 100개의 키-값 쌍 형태의 사용자 지정 메타데이터를 첨부할 수 있습니다. 사용자 지정 메타데이터는 다음을 통해 조회할 수 있습니다. [비전 이벤트 조회](/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#http-api) 엔드포인트.

**제약 사항:**

* 키는 다음 패턴과 일치해야 합니다 `[a-zA-Z0-9_ -]+` (문자, 숫자, 밑줄, 하이픈, 공백), 최대 100자.
* 문자열 값은 최대 1000자로 제한됩니다.
* 숫자 값은 소수점 이하 최대 6자리를 지원합니다.
* 불리언 값이 지원됩니다.

```json
{
  "customMetadata": {
    "production_line": "A1",
    "shift": "morning",
    "temperature": 72.5,
    "is_overtime": false
  }
}
```

### 예시 응답

{% tabs %}
{% tab title="201" %}

```json
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "eventType 필드가 필요합니다."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "error": "이 리소스에 대한 권한이 충분하지 않습니다."
}
```

{% endtab %}
{% endtabs %}

### 검증 및 경고

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

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

* 다음 안의 필수 필드 누락 `eventData` (예: `relatedEventId` 다음에 대해 `operator_feedback`)
* 잘못된 값 `eventData` 필드(예: 다음에 대한 잘못된 열거형 값 `severity`)
* 스키마에 포함되지 않은 인식되지 않은 필드

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

```json
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true,
  "warnings": [
    {
      "type": "any.required",
      "path": "eventData.relatedEventId",
      "value": null,
      "valueType": "object"
    }
  ]
}
```

응답에는 다음도 포함될 수 있습니다. `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`** (문자열): 전역 고유 식별자입니다. 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).
* **`customMetadata`** (딕셔너리): 최대 100개의 키-값 쌍을 가진 사용자 지정 메타데이터입니다.
* **`comment`** (문자열): 이벤트에 대한 메모로, 주로 `operator_feedback`.

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