노드 유형 및 계층 구조

RealityConnect API의 모든 리소스는 유형이 지정된 노드로 구성된 콘텐츠 계층 구조를 통해 주소가 지정됩니다. 이 페이지에서는 10가지 노드 유형, 그 트리를 유효하게 유지하는 부모/자식 규칙, 그리고 API로 직접 생성할 수 있는 유형과 다른 작업의 결과로만 나타나는 유형을 정리합니다.

노드 유형

DataNodeType에는 10개의 값이 있습니다. Division, Site, Folder만 노드 생성 엔드포인트를 통해 직접 생성됩니다. 그 외의 모든 유형은 업로드, 번들 생성, 처리, 플랫폼/관리자 작업과 같은 도메인별 작업의 부수적인 결과로 생성됩니다.

유형	설명	생성 방법
`Organization`	트리의 루트입니다. 다른 모든 노드는 그 하위입니다. `parentId`는 `null`입니다.	조직 생성 시 프로비저닝되며, API로는 생성할 수 없습니다
`Division`	조직 하위의 최상위 그룹(예: 사업 단위나 지역).	`POST /v1/nodes/{parentId}/division`
`Site`	디비전 하위의 물리적 위치입니다. 데이터 번들을 보유하며 twin 및 검색 경로가 주소로 지정하는 단위입니다.	`POST /v1/nodes/{parentId}/site`
`Folder`	사이트 또는 다른 폴더 하위에서 콘텐츠를 정리하기 위한 중첩 가능한 그룹입니다.	`POST /v1/nodes/{parentId}/folder`
`Project`	RealityPlan Project입니다.	데이터 번들에 처리되어 표시 가능한 구성 요소가 생기면 `POST /v1/bundles/{bundleId}/create-project`
`Twin`	사이트의 3D 공간 디스크립터입니다. Twin은 해당 사이트의 노드 id로 주소가 지정되며, 별도의 생성 단계는 없습니다.	플랫폼 작업(twin 게시)
`DataBundle`	캡처된 데이터셋(포인트 클라우드, 메시, 파노라마 등)과 그 처리 결과입니다.	확인된 `dbuPath`를 사용한 `POST /v1/nodes/{parentId}/bundle`
`SiteFile`	데이터 번들에 속하지 않는 원본 업로드 파일입니다.	`POST /v1/site-files` (노드 생성 엔드포인트가 아닌 전용 업로드 흐름)
`Artifact`	Twin 콘텐츠와 연결된 첨부 파일 또는 출력 아티팩트입니다.	플랫폼/처리 작업
`AssetLibrary`	조직 수준의 재사용 가능한 모델 라이브러리입니다.	조직 수준에서 프로비저닝되며, API로는 생성할 수 없습니다

부모/자식 규칙과 깊이

생성 가능한 세 가지 유형은 고정된 뼈대를 이루며, 각각 정확히 하나의 부모 유형만 허용합니다.

부모	허용하는 자식 유형	경로
`Organization`	`Division`	`POST /v1/nodes/{parentId}/division`
`Division`	`Site`	`POST /v1/nodes/{parentId}/site`
`Site` 또는 `Folder`	`Folder`	`POST /v1/nodes/{parentId}/folder`

Folder는 자기 자신의 유형 하위에 중첩되는 유일한 유형이므로, 단일 API 호출만으로 깊이가 임의로 커질 수 있는 유일한 지점입니다. 이 뼈대를 넘어서는 최대 계층 깊이는 플랫폼이 강제하며, 정확한 숫자는 공개되지 않습니다. 다만 아래 두 가지 오류 코드는 그 깊이를 초과하거나 노드를 잘못된 위치에 두려는 요청을 정확히 잡아내기 위해 존재합니다.

MaxDepthExceeded (PATCH /v1/nodes/{nodeId}/move/{newParentId}에서 반환): 대상 위치로 이동하면 플랫폼이 허용하는 것보다 노드가 더 깊어집니다. 폴더를 무한정 중첩하는 대신 노드를 더 얕은 위치로 이동하세요.
DoesNotMeetHierarchyConstraints (역시 이동 엔드포인트에서 반환): 대상 부모가 이 노드의 유형을 허용하지 않습니다. 이동하기 전에 위 표(또는 탐색을 통한 해당 유형의 실제 위치)를 확인하세요.

잘못된 부모 유형 하위에 노드를 생성하려는 시도도 동일하게 거부됩니다. Division이 아닌 parentId로 POST /v1/nodes/{parentId}/site를 호출하면 409 { "error": "ParentTypeNotValid" }가 반환됩니다.

전체 응답 구조와 그 외 모든 이동/삭제 오류 코드는 오류 코드를 참조하세요.

DataBundle 노드는 사이트 또는 폴더 하위에 생성되고, SiteFile 노드는 업로드 흐름에 전달된 부모 id 하위에 생성됩니다. 두 유형 모두 실질적으로 Folder와 동일한 두 가지 부모 유형을 허용하지만, 범용 노드 생성 경로가 아닌 각각의 전용 도메인별 엔드포인트를 통해 이루어집니다. 나머지 유형(Twin, Artifact, AssetLibrary)은 이를 생성하는 플랫폼 또는 처리 작업에 의해 위치가 정해집니다. 고정된 위치를 가정하기보다는 트리를 탐색해서 찾으세요.

DataNode 구조

GET /v1/nodes/{id}/browse와 GET /v1/nodes/search는 모두 다음 구조로 노드를 반환합니다.

{
  "id": "a6f75b3c-f261-4b27-9a2a-9a6cc1234c53",
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:00:00.000Z",
  "name": "Building A",
  "type": "Site",
  "createdById": "8f0b9a2c-8f1b-4a10-9e1c-0b3a2d9a4b7d",
  "parentId": "d2a1c4b7-3e10-4f2c-9a6b-7c1d8e2f3a45",
  "childrenCount": 4,
  "bytesStored": 15728640,
  "thumbnailSignedUrl": null
}

필드	참고
`type`	위 10개 `DataNodeType` 값 중 하나
`parentId`	`Organization` 루트에 대해서만 `null`
`childrenCount`	전체 하위 트리가 아닌 직계 자식만
`bytesStored`	하위 트리의 저장소 크기(바이트 단위)
`thumbnailSignedUrl`	선택 사항입니다. 요청이 `includeThumbnail=true`로 명시적으로 요청하고 썸네일이 존재하는 경우에만 포함됩니다

탐색과 검색 비교

두 경로 모두 동일한 DataNode 구조를 반환하지만, 서로 다른 질문에 답하며 제한도 다릅니다.

	`GET /v1/nodes/{id}/browse`	`GET /v1/nodes/search`
답변 대상	”이 노드의 직계 자식은 무엇인가?"	"내가 접근할 수 있는 모든 곳에서 이 필터에 맞는 노드를 찾아라”
범위	한 노드의 직계 자식	액세스 토큰에 연결된 조직 트리 전체
`limit`	1–20	1–50
기본 `limit`	20	50
필터링	없음, 페이지네이션과 정렬만	이름, 유형, 부모/조상, 생성자, 타임스탬프, 저장소 크기, 자식 수

첫 번째 노드 id를 확인하고 browse를 호출하는 방법은 ID 찾기를 참조하세요. search의 전체 쿼리 매개변수, 필터 조합, 예제는 비즈니스 객체 및 노드 검색을 참조하세요.

Twin, DataBundle, AssetLibrary 노드는 다른 노드와 마찬가지로 탐색 및 검색 결과에 나타나지만, id를 확보한 후에는 /v1/nodes가 아닌 다른 경로군을 통해 해당 콘텐츠에 접근합니다.

노드 유형	id로 주소가 지정되는 위치
`Twin`	`/v1/twin/{contextId}/...` (공간 디스크립터, 비즈니스 객체 검색)
`DataBundle`	`/v1/bundles/{bundleId}/...` (구성 요소, 처리, 처리 옵션)
`AssetLibrary`	`/v1/asset-library/...` (`ownerContextId`로서)

다음 단계

모든 이동/삭제/생성 오류 코드와 처리 방법은 오류 코드를 참조하세요.
search의 전체 쿼리 범위는 비즈니스 객체 및 노드 검색을 참조하세요.