节点类型与层级结构

RealityConnect API 的每个资源都通过由类型化节点组成的内容层级结构来寻址。本页整理了 10 种节点类型、维持该树结构有效的父子规则,以及哪些类型可以直接创建、哪些类型只会作为其他操作的结果出现。

节点类型

DataNodeType 共有 10 个值。只有 Division、Site 和 Folder 通过节点创建端点直接创建;其他所有类型都是上传、创建 bundle、处理或平台/管理操作等特定领域动作的副产物。

类型	是什么	创建方式
`Organization`	树的根节点。其他所有节点都是它的后代。`parentId` 为 `null`。	在创建组织时预置,永远不能通过 API 创建
`Division`	组织下的顶层分组(例如业务单元或地区)。	`POST /v1/nodes/{parentId}/division`
`Site`	部门下的一个实体位置。包含数据包(data bundle),是 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 的完整查询参数范围,请参见搜索业务对象与节点。