입력 파일 다운로드

입력 파일이 업로드되고 마무리되면, API를 통해 다시 다운로드할 수 있습니다.

번들에 마무리된 입력 파일이 있고 read:bundle 스코프를 보유하고 있다고 가정합니다.

---

작동 방식

다운로드 엔드포인트는 바로 사용 가능한 서명된 URL을 반환합니다. 스캔 파일 다운로드에 사용되는 것과 동일한 패턴으로, GET 요청에 Authorization 헤더 없이 CDN/S3에서 직접 파일 바이트를 다운로드하세요.

sequenceDiagram
  participant Client as RCAPI client
  participant RCAPI as RCAPI
  participant CDN as CDN / S3

  Client->>RCAPI: GET input-files (page, limit)
  RCAPI-->>Client: items with signed urls + total
  loop for each item
    Client->>CDN: GET url
    CDN-->>Client: file bytes
  end

RCAPI는 요청당 한 번 번들의 입력 접두사에 서명합니다. 각 항목의 url은 와일드카드를 파일의 저장소 경로로 바꾼 그 서명이므로, 단일 응답의 모든 URL은 동일한 만료 시간을 공유합니다.

엔드포인트

메서드	경로	스코프	목적
GET	/v1/bundles/{bundleId}/input-files	read:bundle	마무리된 입력 파일에 대한 서명된 다운로드 URL 나열

입력 파일 다운로드 URL 나열

GET {api_url}/v1/bundles/{bundleId}/input-files?page=1&limit=20
Authorization: Bearer {access_token}

쿼리 매개변수

매개변수	유형	설명
page	number	1부터 시작하는 페이지 인덱스(기본값 1)
limit	number	페이지 크기(기본값 20, 최대 20)
sessionId	uuid	선택 사항. 결과를 하나의 업로드 세션의 파일로 제한

정렬은 제공되지 않습니다. 파일은 안정적인 저장소 순서로 반환됩니다.

응답

페이지 단위 목록({ items, total }):

{
  "items": [
    {
      "fileName": "scan.las",
      "url": "https://cdn…/bundles/…/scan.las?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    },
    {
      "fileName": "panorama/2024-07-scan-idx40.jpg",
      "url": "https://cdn…/bundles/…/panorama/2024-07-scan-idx40.jpg?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    }
  ],
  "total": 28
}

필드	의미
fileName	입력 파일의 이름(서명된 접두사에 대체된 경로)
url	인증 헤더 없이 GET할 준비가 된 서명된 다운로드 URL
sessionId	파일이 속한 업로드 세션
total	모든 페이지에 걸친 마무리된 입력 파일의 총 수

바이트 다운로드

각 항목에 대해 url을 직접 GET하세요. 베어러 토큰이 필요하지 않습니다. 서명이 쿼리 문자열에 포함되어 있습니다.

import requests

response = requests.get(item["url"])
response.raise_for_status()

with open(local_path, "wb") as handle:
    handle.write(response.content)

만료된 URL

한 응답의 모든 URL은 단일 서명 만료 시간(약 24시간, API의 다른 서명된 링크와 일치)을 공유합니다. 다운로드가 403 Forbidden을 반환하면 URL이 만료된 것입니다. 목록 엔드포인트에서 새 페이지를 요청하고 재시도하세요.

대규모 번들 페이지 처리

total이 limit을 초과하면 결과를 페이지 단위로 처리하세요.

import requests

API_URL = "https://<your-regional-api-url>"
TOKEN = "<access_token>"
BUNDLE_ID = "<bundleId>"
LIMIT = 20

headers = {"Authorization": f"Bearer {TOKEN}"}
base = f"{API_URL}/v1/bundles/{BUNDLE_ID}/input-files"

page = 1
while True:
    listing = requests.get(
        base, headers=headers, params={"page": page, "limit": LIMIT}
    ).json()

    for item in listing["items"]:
        local_name = item["fileName"].replace("/", "_")
        data = requests.get(item["url"])
        data.raise_for_status()
        with open(local_name, "wb") as handle:
            handle.write(data.content)
        print(f"Downloaded {item['fileName']}")

    if page * LIMIT >= listing["total"]:
        break
    page += 1

이 엔드포인트를 사용해야 하는 경우

사용 사례	참고
보관	업로드 후 원시 캡처를 자체 저장소로 복사
재처리	입력을 로컬로 다운로드한 다음 새 번들에 업로드
감사 / 검증	처리 전에 어떤 파일이 번들에 도착했는지 확인
통합 테스트	CI 파이프라인에서 업로드 및 다운로드 왕복

이 엔드포인트는 입력 파일(업로드한 것)만 반환합니다. 처리된 출력물(HLOD, 표준화된 포인트 클라우드 등)은 GET /v1/site/{siteId}/bundles/{bundleId}에서 번들 컴포넌트의 서명된 링크로 노출됩니다. 처리된 출력물 가져오기를 참조하세요.

오류 케이스

상태	원인
403 Forbidden	read:bundle 스코프 누락 또는 번들에 대한 읽기 권한 없음
404 Not Found	알 수 없는 bundleId

total: 0인 빈 items 배열은 번들에 아직 마무리된 입력 파일이 없음을 의미합니다. 먼저 업로드 세션을 완료하세요. Data Bundle에 데이터 업로드를 참조하세요.