> 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). 배포 환경에서 클라우드로 연결되는 경로가 없다면 다음을 참조하세요 [비전 이벤트 번들 업로드](/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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%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`** (문자열, 최대 256자): 이벤트의 전역적으로 고유한 식별자입니다. 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": "작업자가 zone B3에서 필수 PPE 없이 감지되었습니다.",
  "externalId": "alert-2024-001"
}
```

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

{% tab title="custom" %}

```json
{
  "value": "문자열 형식의 사용자 지정 이벤트 데이터",
  "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]]
    }
  ],
  "metadata": {
    "verdict": "pass",
    "angle": 42.5
  },
  "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` 에서 반환되는 [주석이 달린 이미지를 업로드할 때](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#http-api).
* **`inputSourceId`** (문자열, 선택 사항): `sourceId` 원본 주석 없는(입력) 이미지를 업로드할 때 반환됩니다.
* **`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개 키포인트).
* **`metadata`** (객체, 최대 100개 키, 선택 사항): 이 한 이미지에 대한 키-값 쌍입니다. 다음을 참조하세요: [이미지 메타데이터](#image-metadata) 아래.

### 이미지 메타데이터

다음을 사용하세요: `metadata` 이미지 객체에, 통과/실패 판정, 시리얼 번호 또는 카메라 각도처럼 해당 이미지에만 속하는 값을 기록하세요. 값은 이벤트 상세 보기에서 이미지와 함께 표시됩니다. 전체 이벤트를 설명하는 값을 첨부하려면 [사용자 지정 메타데이터](#custom-metadata) 대신 사용하세요.

**제약 사항:**

* 키는 다음 패턴과 일치해야 합니다: `[a-zA-Z0-9_ -]+` (문자, 숫자, 밑줄, 하이픈 및 공백), 최대 128자.
* 이미지당 최대 100개 키, 이벤트당 최대 200개의 고유 키까지 허용됩니다.
* 값은 문자열(최대 1000자), 숫자 또는 불리언이어야 합니다. 중첩된 객체와 배열은 허용되지 않습니다.

이 규칙을 위반한 키는 제외되며 다음 항목에 보고됩니다: `warnings` 배열. 나머지 이미지는 계속 저장됩니다.

이벤트에서 어떤 키를 사용하는지 확인하려면 다음을 호출하세요: [이미지 메타데이터 스키마 가져오기](/deployment/ko/monitoring-and-analytics/vision-events/get-image-metadata-schema.md). 이미지 메타데이터는 표시와 검색용입니다. 다음에서는 이를 기준으로 필터링할 수 없습니다: [이벤트 쿼리](/deployment/ko/monitoring-and-analytics/vision-events/query-events.md) 아직은.

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

각 이벤트에 최대 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는 즉시 수집을 사용합니다. 네 개의 필수 필드(`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"
    }
  ]
}
```

응답에는 다음도 포함될 수 있습니다: `사용 중단 항목` 배열이, 사용 중단된 필드 이름을 사용한 경우.

## 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).
* **`customMetadata`** (딕셔너리): 최대 100개의 사용자 지정 메타데이터 키-값 쌍입니다.
* **`comment`** (문자열): 이벤트에 대한 메모로, 주로 다음과 함께 사용됩니다: `operator_feedback`.

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