> 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) 블록은 각 이벤트마다 tarball 하나를 Roboflow로 보내는 대신 로컬 디스크에 씁니다. 추론 서버가 클라우드로 가는 경로가 없는 네트워크에서 실행될 때 사용하세요. 이 엔드포인트는 해당 tarball을 있는 그대로 받습니다. 업로더가 각 파일을 전송하면 Roboflow가 압축을 풀고, 이미지를 업로드한 뒤, [Vision 이벤트](/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-dca3d4f164ead71d7f0d6953b9ac101065bf210f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 번들 형식

각 번들은 하나의 이벤트를 담습니다. 블록은 gzipped tar 파일을 쓰며, 일반 tar도 작동합니다.

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

`payload.json` 다음과 같은 구조를 가집니다. [비전 이벤트 생성](/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#request-body-parameters) 요청 본문과 같지만, 두 가지 차이점이 있습니다:

* `bundleFormatVersion` 는 `1`.
* `images[].file` 과 `images[].inputFile` 아카이브 멤버 경로를 보관합니다(예: `images/9f0c1b2a.jpg`) 대신 `sourceId` 과 `inputSourceId`. Roboflow는 각 멤버를 업로드하고 소스 ID를 이벤트에 저장합니다.

이미지는 반드시 `images/` 디렉터리 아래에 있어야 합니다. 어떤 이미지도 참조하지 않는 멤버와, `images/`를 제외한 최상위 디렉터리는 수집 경고를 추가하지만 이벤트를 중단하지는 않습니다. 번들은 이미지만 포함합니다: `videos/` 디렉터리는 경고와 함께 무시됩니다. 클립을 첨부하려면, [동영상을 업로드하세요](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md) 별도로.

다음 내부의 필드 오류는 `payload.json` JSON 엔드포인트와 동일하게 동작합니다. 다음을 참조하세요: [유효성 검사 및 경고](/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>25 MB</td><td>413</td></tr><tr><td>압축 해제된 아카이브</td><td>75 MB</td><td>413</td></tr><tr><td><code>payload.json</code></td><td>10 MB</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>80 MP</td><td>413</td></tr></tbody></table>

### 재시도

실패했거나 결과가 불분명한 업로드 후에는 같은 번들을 다시 전송할 수 있습니다. 이미지는 내용으로 매칭되며, 두 번 도착한 이벤트는 이전 것을 대체합니다. 요금은 한 번만 부과됩니다.