콘텐츠로 이동
Prevu3D

노드 썸네일

데이터 노드(디비전, 사이트, 폴더, 트윈 등 계층 구조의 나머지 요소)는 썸네일 이미지를 가질 수 있습니다. 이 페이지에서는 해당 썸네일의 업로드, 교체, 삭제 방법과 요청 시 반환되는 서명된 URL의 비용 및 수명을 다룹니다.

썸네일 업로드

섹션 제목: “썸네일 업로드”
메서드경로설명
POST/v1/nodes/{nodeId}/thumbnail시작: 업로드 id와 사전 서명된 S3 URL을 반환합니다
POST/v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize완료: 업로드된 이미지를 노드의 썸네일로 적용합니다
DELETE/v1/nodes/{nodeId}/thumbnail삭제: 현재 썸네일을 삭제합니다

세 엔드포인트 모두 write:hierarchy가 필요하며 실험적으로 표시되어 있습니다. 실험적 엔드포인트를 참조하세요.

이는 RealityConnect API의 여러 다른 업로드 엔드포인트에서 사용하는 것과 동일한 시작/업로드/완료 형태입니다. 전체 메커니즘은 공유 멀티파트 업로드 참조를 참조하세요. 노드 썸네일은 이 패턴의 단순한 단일 파일 사례입니다. 시작 호출은 요청 본문을 받지 않고 정확히 하나의 사전 서명된 URL을 반환하며, partNumber도 새로 고침 엔드포인트도 없습니다. 해당 URL로 이미지를 PUT한 다음 finalize를 호출해 적용하세요. 업로드하기 전에 URL이 만료되면 다시 시작하여 새 URL을 받으세요. 새로 고칠 것은 없습니다.

DELETE /v1/nodes/{nodeId}/thumbnail은 멱등적입니다: 노드에 썸네일이 있었든 없었든 204를 반환합니다.

허용되는 형식과 크기 제한

섹션 제목: “허용되는 형식과 크기 제한”

시작 호출은 본문을 받지 않습니다. API의 다른 일부 업로드 흐름과 달리 파일 이름, 크기, 콘텐츠 유형을 미리 선언하지 않습니다. API 자체는 이미지 형식 허용 목록이나 최대 파일 크기를 문서화하거나 강제하지 않습니다. 다운스트림 이미지 처리기가 디코딩할 수 없는 파일은 PUT 단계가 아니라 완료 단계에서 실패합니다. finalize에서 204가 아닌 응답은 모두 “이 파일은 처리되지 않았습니다”로 취급하여 호출자에게 전달하고, PUT할 수 있는 모든 이미지가 받아들여진다고 가정하지 마세요.

썸네일 조회

섹션 제목: “썸네일 조회”

GET /v1/nodes/{id}/browse와 GET /v1/nodes/search 모두 includeThumbnail=true(기본값 false)를 허용합니다. 이 값을 설정하면 응답의 모든 노드에 thumbnailSignedUrl 필드가 추가됩니다. 노드에 썸네일이 없으면 null, 있으면 서명된 URL입니다. DataNode 형태의 나머지 부분은 노드 유형 및 계층 구조를 참조하세요.

includeThumbnail이 기본적으로 false인 이유는 이것이 공짜가 아니기 때문입니다. URL을 생성하고 서명하는 것은 노드마다 추가 작업이며, 호출자가 실제로 렌더링하는 항목뿐 아니라 페이지의 모든 항목에 대해 수행됩니다. 이미 페이지 크기 한도(browse는 20, search는 50)에 가까운 browse 또는 search 호출에서 이를 요청하면 페이지 전체에 대해 그 비용을 지불하게 됩니다. 실제로 이미지를 렌더링하는 화면에서만 요청하고, 대량 목록 조회나 트리의 백그라운드 동기화에서는 요청하지 마세요.

서명된 URL의 수명

섹션 제목: “서명된 URL의 수명”

thumbnailSignedUrl은 사전 서명된 링크이며, RCAPI는 이 URL이 얼마나 오래 유효한지 공개하거나 설정하지 않습니다. 따라서 이를 영구적인 식별자가 아니라 수명이 짧고 불투명한 것으로 취급하세요. thumbnailSignedUrl을 반환한 응답 이후까지 캐시하지 마세요. 통합 시스템이 browse나 search 결과를 캐시했다가 나중에 다시 렌더링한다면, 저장된 URL을 재사용하는 대신 includeThumbnail=true로 다시 조회해 최신 URL을 받으세요. 저장된 URL은 결국 더 이상 해석되지 않아, 응답의 다른 부분에는 아무런 경고 없이 죽은 이미지 링크를 제공하게 됩니다.

썸네일과 소프트 삭제

섹션 제목: “썸네일과 소프트 삭제”

노드를 소프트 삭제하면(DELETE /v1/nodes/{nodeId}) 썸네일은 그대로 둔 채 노드를 휴지통으로 이동합니다. GET /v1/trash는 동일한 includeThumbnail=true를 허용하며, 휴지통에 있는 노드에 대해 삭제되기 전 browse와 search가 반환했을 것과 동일한 thumbnailSignedUrl을 반환합니다. 노드를 복원하면(PATCH /v1/nodes/{nodeId}/restore) 썸네일이 그대로 유지된 채 다시 조회 및 검색이 가능해집니다. 다시 업로드할 필요가 없습니다. 노드를 영구 삭제하거나(DELETE /v1/nodes/{nodeId}/hard) 휴지통의 30일 보존 기간이 지나면, 노드의 다른 모든 것과 함께 썸네일도 삭제됩니다. 전체 삭제/복원/영구 삭제 모델은 리소스별로 실제 삭제가 하는 일을 참조하세요.

다음은?

섹션 제목: “다음은?”