공유 멀티파트 업로드 참조

여러 RealityConnect API 업로드 엔드포인트는 동일한 기본 패턴을 공유합니다. 업로드를 개시하고, 파일을 하나 이상의 서명된 URL로 직접 **업로드(PUT)**한 다음 마무리하는 방식입니다. 이 페이지는 이 패턴, 파트 번호 규칙, 업로드 도중 URL을 갱신·재개하고 진행 상황을 확인하는 방법에 대한 공유 참조입니다. 엔드포인트별 가이드에서는 이 메커니즘을 반복하는 대신 이 페이지로 연결하세요.

이 패턴을 사용하는 엔드포인트

플로우	개시	마무리	파트로 분할?	갱신 엔드포인트?
Data Bundle 업로드	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	예	예
객체 첨부 파일	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	예	예
사이트 파일	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	예	아니요
애셋 라이브러리 모델	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	아니요(단일 파일)	아니요
노드 썸네일	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	아니요(단일 파일)	아니요

개시, 업로드, 마무리 패턴

sequenceDiagram
  participant Client as Client
  participant RCAPI as RCAPI
  participant S3 as S3

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + 서명된 URL
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (ETag 포함)
  RCAPI-->>Client: 업로드 완료

개시: 파일 이름과 크기(그리고 Data Bundle 파일의 type과 같은 플로우별 필드)를 사용해 해당 플로우의 개시 엔드포인트를 호출합니다. 응답에는 마무리에 사용할 식별자와, 파일을 PUT할 하나 이상의 서명된 S3 url이 반환됩니다.
업로드: 반환된 URL로 파일의 바이트를 직접 PUT합니다. 이 요청에는 Authorization 헤더가 전송되지 않습니다. URL 자체가 이미 서명되어 있기 때문입니다. 각 PUT의 ETag 응답 헤더를 보관해 두세요.
마무리: 수집한 ETag(들)을 사용해 해당 플로우의 마무리 엔드포인트를 호출하여 업로드를 완료합니다.

애셋 라이브러리 모델과 노드 썸네일은 현재 하나의 PUT으로 단일 파일만 허용하므로, URL 하나, ETag 하나만 있고 partNumber는 전혀 없습니다. 이 두 가지는 동일한 패턴의 단순한 단일 파트 사례로 간주하세요.

파트 번호: `partNumber` 대 `startIndex`

이는 갱신을 지원하는 두 플로우에 적용됩니다.

실습 예제. 개시가 3개의 파트를 반환한다고 가정합니다.

{
  "urls": [
    { "partNumber": 1, "url": "https://s3…/part-1?…" },
    { "partNumber": 2, "url": "https://s3…/part-2?…" },
    { "partNumber": 3, "url": "https://s3…/part-3?…" }
  ]
}

partNumber: 2부터 갱신하려면 1을 뺀 다음 startIndex = 1로 갱신을 호출합니다.

GET {api_url}/.../refresh/1

응답의 startIndex에는 1이 그대로 반영되고, urls에는 2부터 시작하는 1부터 시작하는 partNumber가 다시 담겨 있습니다.

{ "startIndex": 1, "urls": [ { "partNumber": 2, "url": "…" }, { "partNumber": 3, "url": "…" } ] }

partNumber를 그대로(1이 아니라 2로) startIndex로 전달하면 파트 2를 건너뛰고 파트 3부터만 갱신됩니다.

업로드 도중 만료된 서명된 URL 갱신하기

서명된 PUT URL은 만료됩니다. 업로드가 오래 걸려서 어떤 파트의 PUT이 403을 반환하기 시작하면, 멈춘 지점의 파트를 대상으로(startIndex = partNumber - 1로) 갱신 엔드포인트를 호출하세요. 갱신은 해당 파트와 그 이후의 모든 파트에 대한 새로운 URL을 반환합니다. 각 파트를 개별적으로 갱신할 필요가 없고, 파일을 다시 개시할 필요도 없습니다.

갱신은 다음 플로우에서 사용할 수 있습니다.

Data Bundle 업로드: GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
객체 첨부 파일: GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

사이트 파일, 애셋 라이브러리 모델, 노드 썸네일에는 갱신 엔드포인트가 없습니다. 이러한 플로우 중 하나에서 업로드 도중 URL이 만료되면, 파일을 다시 개시하여 새 URL을 받으세요.

부분 업로드 재개 및 진행 상황 확인

재개 방법과 진행 상황 확인 방법은 플로우에 따라 다릅니다.

Data Bundle 업로드는 세션 수준에서 진행 상황을 추적합니다. 번들의 업로드 세션을 나열하고(GET /v1/bundles/{bundleId}/upload-sessions) finalizedFileCount를 expectedFileCount와 비교하세요. 재개하려면 아직 마무리된 것으로 나타나지 않은 type과 fileName을 기준으로, 완료되지 않은 파일만 개시하고 마무리하세요.
객체 첨부 파일, 사이트 파일, 애셋 라이브러리 모델, 노드 썸네일은 조회할 세션이나 목록이 없는 단일 파일 작업입니다. 진행 상황은 단순히 받은 fileId(또는 uploadId)에 대해 마무리가 이미 성공했는지 여부입니다. 애셋 라이브러리 모델의 경우 모델 자체의 status 필드에서도 이를 확인할 수 있으며, 마무리가 완료될 때까지 uploading 상태로 유지됩니다. 중단 후 이러한 플로우 중 하나를 재개하려면, 개시 시 받은 식별자를 보관한 상태로 나머지 파트 업로드를 계속하거나(가능한 경우 필요에 따라 URL을 갱신), 식별자나 그 URL을 더 이상 사용할 수 없다면 다시 개시하세요.

스토리지 한도 및 기존 파일 재업로드

업로드 개시는 요청 자체가 유효하지 않은 경우 바이트가 전송되기도 전에 거부될 수 있습니다. 가장 흔한 경우는 조직의 스토리지 할당량이 이미 초과된 경우의 StorageLimitExceeded와, 동일한 식별자를 가진 파일에 재업로드할 때의 FileAlreadyExists입니다. 이는 응답 본문에 포함된 명명된 오류 코드로, 엔드포인트별 정확한 상태 코드와 함께 오류 코드: 파일 업로드에 정리되어 있습니다.

다음 단계

엔드포인트별 StorageLimitExceeded 및 FileAlreadyExists를 포함한 명명된 코드의 전체 목록은 오류 코드를 참조하세요.
재개 가능한 배치 업로드를 포함해 이 패턴의 가장 상세한 실습 예제는 Data Bundle에 데이터 업로드를 참조하세요.