Data Bundle 소개

Data Bundle은 하나의 캡처를 담는 컨테이너입니다. 원시 입력 파일(포인트 클라우드, 궤적, 이미지 등)과 플랫폼이 이를 통해 생성한 처리된 출력물을 포함합니다. RealityConnect API는 Prevu3D UI가 사용하는 것과 동일한 번들 수명 주기를 노출하므로, 통합에서 브라우저 없이 번들을 생성하고, 데이터를 업로드하고, 처리를 시작하고, 진행 상황을 추적하고, 입력 파일을 검색할 수 있습니다.

이 문서는 OAuth 플로를 완료하여 access_token, 지역별 api_url, organization_id를 보유하고 있다고 가정합니다. 그렇지 않다면 플로 가이드를 참조하세요.

모든 data bundle 워크플로 엔드포인트(/v1/bundles/..., /v1/organization/.../data-bundle-input-tree, /v1/nodes/.../bundle)는 실험적으로 표시되어 있습니다. 안정 단계로 승격될 때까지 계약이 변경될 수 있습니다. 실험적 엔드포인트를 참조하세요.

필요한 스코프

스코프	용도
read:bundle	디바이스 입력 트리 가져오기, 업로드 세션 나열, 처리 옵션 나열, 처리 레코드 나열, 입력 파일 다운로드 URL 나열
write:bundle	번들 생성, 업로드 세션 열기 및 마무리, 처리 시작

또한 번들이 생성되는 상위 노드와, 이후 단계에서는 번들 자체에 대한 콘텐츠 접근 권한과 노드 권한이 필요합니다.

엔드투엔드 플로우

flowchart LR
  A["1. Get input tree"] --> B["2. Create bundle"]
  B --> C["3. Upload input files"]
  C --> D["4. List processing options"]
  D --> E["5. Start processing"]
  E --> F["6. Poll processing records"]

번호가 매겨진 각 단계는 전용 가이드에 매핑됩니다.

단계	가이드	요약
1–2	Data Bundle 생성	디바이스 입력 트리를 가져오고, 리프 dbuPath를 선택하고, 상위 노드 아래에 번들 생성
3	Data Bundle에 데이터 업로드	업로드 세션을 열고, 각 파일을 S3에 멀티파트 업로드하고, 마무리
4–6	처리 및 모니터링	사용 가능한 출력물을 나열하고, 처리를 시작하고, 모든 작업이 종료 상태에 도달할 때까지 폴링

입력 파일 다운로드는 선택 사항입니다. 번들의 업로드된 입력 파일을 다시 검색해야 할 때만 사용하세요.

검증 모델

구조적 규칙(필수 파일 유형, 허용된 확장자, 유형 간 종속성, 다중성)은 업로드 세션을 열 때 반환되는 requirements 배열에 설명되어 있습니다. 업로드 전과 처리 시작 전에 해당 구조를 따르는 것은 사용자의 책임입니다.

업로드 API는 제공한 type 아래에 각 파일을 기록하고 개수만으로 세션을 완료합니다. 심층 콘텐츠 검증(.las가 실제 디바이스 캡처인지, 메타데이터 JSON이 이미지를 올바르게 참조하는지)은 업로드 시가 아니라 처리 시작 후에 이루어집니다. 이름은 올바르지만 형식이 잘못된 파일은 오류 없이 업로드되지만 나중에 처리 중에 실패합니다.

잘못된 업로드 구조(누락된 필수 유형, 깨진 종속성, 잘못된 확장자 등)로 인한 처리 실패는 환불되지 않습니다.