> 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/roboflow/roboflow-ko/deploy/vision-events/send-events.md).

# 이벤트 전송

## 이벤트 전송

Vision Events는 Workflow 블록, REST API 또는 edge device backup을 사용해 전송할 수 있습니다.

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

### Workflow 블록

대부분의 사용자에게 권장되는 방법입니다. 다음을 추가하세요. **Vision Event** 블록을 모든 Roboflow Workflow에 추가하면 코드 없이 추론 결과로부터 이벤트를 자동으로 생성할 수 있습니다.

{% hint style="info" %}
해당 [Roboflow Agent](/roboflow/roboflow-ko/agents/roboflow-agent.md) 가 이를 대신 설정해 줄 수 있습니다. Agent에게 모델을 실행하는 Workflow를 만들도록 요청하면 Vision Events 블록을 자동으로 추가하고 올바른 [Use Case](/roboflow/roboflow-ko/deploy/vision-events/use-cases.md).
{% endhint %}

#### 설정

{% stepper %}
{% step %}
**Workflow Editor 열기**

다음으로 이동하세요: **Workflows** 작업 공간에서 해당 워크플로를 열고 이벤트를 추가할 워크플로를 선택하세요.
{% endstep %}

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

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

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

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

{% step %}
**Use Case 구성**

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

{% step %}
**Workflow 배포**

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

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

### REST API

Workflows를 사용하지 않는 맞춤 통합 또는 파이프라인의 경우 REST API를 통해 이벤트를 직접 전송할 수 있습니다. 전체 요청 및 응답 스키마는 다음을 참조하세요: [Vision Events API Reference](https://docs.roboflow.com/developer/rest-api/vision-events).

#### 인증

모든 write 엔드포인트에는 다음 scope가 포함된 API 키가 필요합니다 `visionEvents.write` 또는 `device.update` scope를 포함해야 합니다. API 키를 Bearer 토큰으로 전달하세요:

```
Authorization: Bearer YOUR_API_KEY
```

#### 전체 예시: 이미지 업로드 + 이벤트 생성

{% hint style="warning" %}
이벤트를 보내기 전에 Use Case를 생성해야 합니다. 참조하는 이벤트는 `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
}
```

#### 이벤트 일괄 생성

batch 엔드포인트를 사용해 한 번의 요청으로 최대 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" %}
batch 요청당 최대 100개 이벤트입니다.
{% endhint %}

### Edge Device Backup

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

{% hint style="info" %}
Edge Device Backup에는 Deployment Manager가 필요합니다. 다음을 참조하세요: [Deployment Manager 문서](/roboflow/roboflow-ko/deploy/device-manager.md) 설정 방법은 다음을 참조하세요.
{% endhint %}

Vision Events backup을 활성화하려면:

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

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

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

#### 디바이스 내 Event 데이터

디바이스의 Event Store는 디바이스에 남아 Roboflow로는 절대 업로드되지 않는 데이터를 저장할 수 있습니다. 이는 큰 또는 민감한 아티팩트를 로컬에 보관하면서 핵심 이벤트 기록은 백업하려는 edge 배포에 적합합니다.

* 이미지별 메타데이터: 개별 이미지에 첨부되는 작은 key/value 객체입니다(예: pass/fail 판정, 일련번호, 각도 레이블). 이는 디바이스에 저장되며 on-device Event Store API로 반환되지만, 조회할 수 없고 클라우드에 백업되지 않습니다.
* 로컬 전용 파일 첨부: 이벤트에 첨부되는 임의의 파일(예: inspection blobs, thumbnails, JSON)입니다. 이는 디바이스에만 저장되며 절대 업로드되지 않고, 파일당 크기 제한(기본 100 MB)을 설정할 수 있습니다. 파일은 이벤트가 draft 상태일 때만 첨부할 수 있으므로, draft로 이벤트를 생성한 뒤 파일을 첨부하고 최종 확정하세요.

이 데이터는 디바이스의 Event Store REST API를 통해 쓰고 읽습니다. 엔드포인트와 검증 제한은 Device Manager의 디바이스 "Configuration" 탭에서 Event Store 도움말을 여세요.