コンテンツにスキップ
Prevu3D

ノードタイプと階層

RealityConnect APIのすべてのリソースは、型付けされたノードで構成されるコンテンツ階層を通じてアドレス指定されます。このページでは、10種類のノードタイプ、そのツリーを有効に保つ親子ルール、そしてAPIで直接作成できるタイプと他の操作の結果としてのみ現れるタイプについて解説します。

ノードタイプ

Section titled “ノードタイプ”

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
ProjectRealityPlan Projectです。データバンドルに処理済みで表示可能なコンポーネントができた時点でPOST /v1/bundles/{bundleId}/create-project
Twinサイトの3D空間記述子。Twinはそのサイトのノードidでアドレス指定され、専用の作成ステップはありません。プラットフォーム操作（Twinの公開）
DataBundle取得されたデータセット（点群、メッシュ、パノラマなど）とその処理結果。解決済みのdbuPathを伴うPOST /v1/nodes/{parentId}/bundle
SiteFileデータバンドルに含まれない、アップロードされた生ファイル。POST /v1/site-files（ノード作成エンドポイントではなく専用のアップロードフロー）
ArtifactTwinコンテンツに関連付けられた添付ファイルまたは出力アーティファクト。プラットフォーム/処理操作
AssetLibrary組織レベルの再利用可能なモデルのライブラリ。組織レベルでプロビジョニングされ、APIからは作成できません

親子ルールと深さ

Section titled “親子ルールと深さ”

作成可能な3つのタイプは固定の骨格を形成し、それぞれが正確に1つの親タイプのみを受け入れます。

親受け入れる子タイプルート
OrganizationDivisionPOST /v1/nodes/{parentId}/division
DivisionSitePOST /v1/nodes/{parentId}/site
SiteまたはFolderFolderPOST /v1/nodes/{parentId}/folder

Folderは自分自身のタイプの配下にネストできる唯一のタイプであり、単一のAPI呼び出しから深さが際限なく増える可能性があるのはこの箇所だけです。プラットフォームはこの骨格を超える最大階層深度を強制しますが、正確な数値は公開していません。ただし、以下の2つのエラーコードは、その深さを超える、またはノードを誤った位置に置こうとするリクエストを検出するために存在します。

  • MaxDepthExceeded（PATCH /v1/nodes/{nodeId}/move/{newParentId}から返されます）：移動先がプラットフォームの許容範囲を超えてノードを深くしてしまう場合です。フォルダーを際限なくネストするのではなく、より浅い位置にノードを移動してください。
  • DoesNotMeetHierarchyConstraints（同じく移動エンドポイントから返されます）：移動先の親がこのノードのタイプを受け入れない場合です。移動する前に上記の表（またはブラウズによるタイプの実際の位置）を確認してください。

誤った親タイプの下にノードを作成しようとした場合も同様に拒否されます。DivisionではないparentIdを指定したPOST /v1/nodes/{parentId}/siteは409 { "error": "ParentTypeNotValid" }を返します。

完全なレスポンス構造や他のすべての移動/削除エラーコードについては、エラーコードを参照してください。

DataBundleノードはサイトまたはフォルダー配下に作成され、SiteFileノードはアップロードフローに渡された親idの配下に作成されます。どちらも実質的にはFolderと同じ2つの親タイプを受け入れますが、汎用のノード作成ルートではなく、それぞれ独自のドメイン固有エンドポイントを経由します。残りのタイプ（Twin、Artifact、AssetLibrary）は、それらを生成するプラットフォームまたは処理アクションによって配置されます。固定の位置を想定するのではなく、ツリーをブラウズして見つけてください。

DataNodeの構造

Section titled “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値のいずれか
parentIdOrganizationのルートに対してのみnull
childrenCountサブツリー全体ではなく、直下の子のみ
bytesStoredサブツリーのストレージサイズ（バイト単位）
thumbnailSignedUrl任意。リクエストがincludeThumbnail=trueで明示的にオプトインし、かつサムネイルが存在する場合のみ含まれます

ブラウズと検索の比較

Section titled “ブラウズと検索の比較”

両方のルートは同じDataNode構造を返しますが、答える質問と上限が異なります。

GET /v1/nodes/{id}/browseGET /v1/nodes/search
答える質問「このノードの直下の子は何か？」「アクセス可能な範囲全体で、これらのフィルターに一致するノードを見つける」
範囲1つのノードの直下の子アクセストークンに紐づく組織ツリー全体
limit1〜201〜50
デフォルトのlimit2050
フィルタリングなし、ページネーションとソートのみ名前、タイプ、親/祖先、作成者、タイムスタンプ、ストレージサイズ、子の数

最初のノードidを解決してbrowseを呼び出す仕組みについては、IDの見つけ方を参照してください。searchのクエリパラメータ全体、フィルターの組み合わせ、例については、ビジネスオブジェクトとノードの検索を参照してください。

Twin、DataBundle、AssetLibraryノードは他のノードと同様にブラウズや検索の結果に現れますが、そのidを取得した後は、/v1/nodesではなく別のルートファミリーを通じてそのコンテンツにアクセスします。

ノードタイプidでアドレス指定される先
Twin/v1/twin/{contextId}/...（空間記述子、ビジネスオブジェクト検索）
DataBundle/v1/bundles/{bundleId}/...（コンポーネント、処理、処理オプション）
AssetLibrary/v1/asset-library/...（ownerContextIdとして）

次のステップ

Section titled “次のステップ”