> 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/upload-a-vision-event-bundle.md).

# Vision Event 번들 업로드

에어갭 배포가 작성한 tarball 번들을 수집하여 Vision Event를 생성합니다.

## 개요

이 [Vision 이벤트 번들 쓰기](https://docs.roboflow.com/workflows/blocks/blocks/data-storage/vision-event-bundle) 블록은 Roboflow로 전송하는 대신 이벤트마다 하나의 tarball을 로컬 디스크에 씁니다. 추론 서버가 클라우드로 연결되는 경로가 없는 네트워크에서 실행될 때 사용하세요. 이 엔드포인트는 tarball을 있는 그대로 받습니다. 업로더가 각 파일을 게시하면 Roboflow가 압축을 풀고 이미지를 업로드한 다음 [Vision 이벤트](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md).

## HTTP API

를 생성합니다. 요청 본문으로 원시 아카이브 바이트를 전송하세요. JSON이나 multipart는 사용하지 마세요. 본문은 바이너리이므로 API 키는 `Authorization: Bearer` 헤더 또는 `api_key` 쿼리 매개변수로 전송하세요.

**필수 범위:** `vision-events:write` 또는 `device:update`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/bundle" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 번들 형식

각 번들에는 이벤트 하나가 들어 있습니다. 블록은 gzip으로 압축된 tar 파일을 쓰며, 일반 tar도 사용할 수 있습니다.

```
event_<timestamp>_<eventId>.tar.gz
├── payload.json
└── images/<file_id>.jpg
```

`payload.json` 의 구조는 [Vision 이벤트 생성](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api) 요청 본문과 동일하지만 다음 두 가지 차이가 있습니다.

* `bundleFormatVersion` 은 `1`.
* `images[].file` 및 `images[].inputFile` 에는 `images/9f0c1b2a.jpg`sourceId `대신` 및 `inputSourceId`아카이브 멤버 경로(예:

)가 들어갑니다. Roboflow는 각 멤버를 업로드하고 해당 소스 ID를 이벤트에 저장합니다. `이미지는` images/ `이미지는`디렉터리 아래에 있어야 합니다. 이미지에서 참조하지 않는 멤버와 `이외의 최상위 디렉터리는 수집 경고를 추가하지만 이벤트 처리를 중단하지는 않습니다. 번들에는 이미지만 포함됩니다.` videos/ [디렉터리는 경고와 함께 무시됩니다. 클립을 첨부하려면](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md) 동영상을 별도로 업로드하세요.

payload.json `내 필드 오류는` JSON 엔드포인트에서와 동일하게 처리됩니다. 자세한 내용은 [유효성 검사 및 경고](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#validation-and-warnings).

### 사용 사례

를 참조하세요. `useCaseId` 쿼리 매개변수는 `useCaseId` 의 `payload.json`값보다 우선합니다. 둘 다 설정되지 않으면 요청은 400 오류와 함께 실패합니다. 에어갭 환경의 사이트에서는 일반적으로 사용 사례를 번들에서 제외하여 클라우드 식별자가 로컬 네트워크 내부에 저장되지 않도록 하고, 대신 업로드 시 지정합니다.

### 제한 사항

<table data-search="false"><thead><tr><th>제한</th><th>값</th><th>실패 시 상태</th></tr></thead><tbody><tr><td>요청 본문</td><td>25MB</td><td>413</td></tr><tr><td>압축 해제된 아카이브</td><td>75MB</td><td>413</td></tr><tr><td><code>payload.json</code></td><td>10MB</td><td>413</td></tr><tr><td>아카이브 항목</td><td>217</td><td>413</td></tr><tr><td>번들당 이미지 수</td><td>100</td><td>400</td></tr><tr><td>이미지당 픽셀 수</td><td>80MP</td><td>413</td></tr></tbody></table>

### 재시도

업로드가 실패했거나 결과가 불분명한 경우 동일한 번들을 다시 전송할 수 있습니다. 이미지는 콘텐츠를 기준으로 일치 여부를 확인하며, 두 번 도착한 이벤트는 이전 이벤트를 대체합니다. 해당 이벤트에 대한 요금은 한 번만 청구됩니다.
