> 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/send-events.md).

# 이벤트 보내기

## 이벤트 전송

Workflow 블록, REST API 또는 엣지 디바이스 백업을 사용하여 Vision Events를 보낼 수 있습니다.

* [Workflow 블록](#workflow-block) - Workflows 사용자는 공식 Roboflow 블록을 사용하는 것이 가장 쉬울 것입니다
* [REST API](#rest-api) - Workflows 밖에서 모델을 배포하려는 사용자는 REST API를 사용할 수 있습니다
* [엣지 디바이스 백업](#edge-device-backup) - Roboflow Edge 디바이스를 배포하는 사용자는 디바이스의 로컬 이벤트 저장소에서 자동 백업을 구성하는 것이 가장 편리합니다

### Workflow 블록

대부분의 사용자에게 권장되는 방법입니다. 다음을 추가하세요. **비전 이벤트** 블록을 어떤 Roboflow Workflow에든 추가하면 코드 없이 추론 결과로부터 이벤트가 자동으로 생성됩니다.

{% hint style="info" %}
다음 [Roboflow Agent](https://docs.roboflow.com/agents/agents/roboflow-agent) 가 이를 설정해 드릴 수 있습니다. Agent에게 모델을 실행하는 Workflow를 만들라고 요청하면, Vision Events 블록을 자동으로 추가하고 올바른 [사용 사례](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md).
{% endhint %}

#### 설정

{% stepper %}
{% step %}
**Workflow 편집기 열기**

다음으로 이동하세요: **워크플로** 워크스페이스에서 이벤트를 추가하려는 워크플로를 엽니다.
{% endstep %}

{% step %}
**Vision Events 블록 추가**

블록 카탈로그에서 "Vision Event"를 검색하여 워크플로에 추가하세요.
{% endstep %}

{% step %}
**입력 연결**

이미지 입력과 모델 예측 출력을 Vision Events 블록에 연결하세요.
{% endstep %}

{% step %}
**사용 사례 구성**

사용 사례 이름을 설정하세요 (`useCaseId`). 상위 블록의 사용자 정의 메타데이터를 매핑할 수도 있습니다. 사용 사례가 선택되면 드롭다운 아래의 "Vision Events에서 열기"를 클릭하여 새 탭에서 해당 사용 사례의 이벤트 페이지로 이동하세요.
{% endstep %}

{% step %}
**워크플로 배포**

워크플로를 배포하거나 업데이트하세요. 워크플로가 실행될 때마다 이벤트가 자동으로 생성됩니다.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Workflow 블록은 이미지 업로드와 이벤트 생성을 한 단계에서 처리합니다.
{% endhint %}

### REST API

Workflows를 사용하지 않는 사용자 정의 통합이나 파이프라인의 경우, REST API를 통해 이벤트를 직접 보낼 수 있습니다. 전체 요청 및 응답 스키마는 다음을 참조하세요. [Vision Events API 레퍼런스](/deployment/ko/monitoring-and-analytics/vision-events.md#http-api).

#### 인증

모든 쓰기 엔드포인트에는 다음이 포함된 API 키가 필요합니다 `visionEvents.write` 또는 `device.update` 권한 범위. API 키를 Bearer 토큰으로 전달하세요:

```
Authorization: Bearer YOUR_API_KEY
```

#### 엔드투엔드 예시: 이미지 업로드 + 이벤트 생성

{% hint style="warning" %}
이벤트를 보내기 전에 사용 사례를 생성해야 합니다. 다음을 참조하는 이벤트는 `useCaseId` 존재하지 않는 경우 거부됩니다.
{% endhint %}

API를 통해 이벤트를 보낼 때는 먼저 이미지를 업로드한 다음, 업로드한 이미지를 참조하는 이벤트를 생성합니다.

**1단계: 이미지 업로드**

```bash
curl -X POST "https://api.roboflow.com/vision-events/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -F "file=@inspection_photo.jpg"
```

**응답:**

```json
{
  "success": true,
  "sourceId": "abc123def456",
  "url": "https://storage.googleapis.com/your-workspace/abc123def456/original.jpg"
}
```

**2단계: 업로드한 이미지를 참조하여 이벤트 생성**

```bash
curl -X POST "https://api.roboflow.com/vision-events" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -d '{
    "eventType": "quality_check",
    "useCaseId": "assembly-line-qa",
    "timestamp": "2026-03-30T14:30:00.000Z",
    "deviceId": "factory-cam-01",
    "streamId": "line-3",
    "images": [
      {
        "sourceId": "abc123def456",
        "objectDetections": [
          {
            "class": "defect",
            "x": 320,
            "y": 240,
            "width": 50,
            "height": 40,
            "confidence": 0.95
          }
        ]
      }
    ],
    "eventData": {
      "result": "fail"
    },
    "customMetadata": {
      "line_id": "line-3",
      "shift": "morning",
      "part_number": "PN-4421"
    }
  }'
```

**응답:**

```json
{
  "eventId": "evt-789ghi",
  "created": true
}
```

#### 배치 이벤트 생성

배치 엔드포인트를 사용하면 한 번의 요청으로 최대 100개의 이벤트를 보낼 수 있습니다:

```bash
curl -X POST "https://api.roboflow.com/vision-events/batch" \
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -d '{
    "events": [
      {
        "eventType": "quality_check",
        "useCaseId": "alksjdflaalsf32",
        "eventData": { "result": "pass" },
        "customMetadata": { "line_id": "line-1" }
      },
      {
        "eventType": "quality_check",
        "useCaseId": "alksjdflaalsf32",
        "eventData": { "result": "fail" },
        "customMetadata": { "line_id": "line-2" }
      }
    ]
  }'
```

{% hint style="info" %}
배치 요청당 최대 100개 이벤트입니다.
{% endhint %}

### 엣지 디바이스 백업

연결이 간헐적일 수 있는 엔터프라이즈 배포의 경우, 엣지 디바이스는 이벤트를 로컬에 저장하고 연결이 복구되면 Roboflow와 동기화합니다.

{% hint style="info" %}
엣지 디바이스 백업에는 Deployment Manager가 필요합니다. 다음을 참조하세요. [Deployment Manager 문서](/deployment/ko/self-hosted/enterprise/deployment-manager.md) 설정 안내는 다음을 참조하세요.
{% endhint %}

Vision Events 백업을 활성화하려면:

1. 열기 **Deployment Manager** 워크스페이스에서
2. 구성할 디바이스를 선택하세요
3. 활성화 **Vision Events 백업** 디바이스의 Event Store 구성에서
4. 이벤트는 디바이스의 로컬 이벤트 저장소에 기록됩니다
5. 디바이스가 다시 연결되면 이벤트가 Roboflow에 자동으로 동기화됩니다

동기화가 완료되면 이벤트가 Vision Events 대시보드에 표시됩니다.

<figure><img src="/files/d6c23859cdb801d2fe076566d23ad0d869f45752" alt="" width="375"><figcaption></figcaption></figure>