Tipi di nodo e gerarchia

Ogni risorsa dell’API RealityConnect viene indirizzata tramite una gerarchia di contenuti composta da nodi tipizzati. Questa pagina cataloga i 10 tipi di nodo, le regole padre/figlio che mantengono valido quell’albero, e quali tipi possono essere creati direttamente rispetto a quelli che compaiono solo come risultato di un’altra azione.

Tipi di nodo

DataNodeType ha 10 valori. Solo Division, Site e Folder vengono creati direttamente tramite un endpoint di creazione nodo; ogni altro tipo viene prodotto come effetto collaterale di un’azione specifica di dominio: un upload, la creazione di un bundle, un’elaborazione o un’operazione di piattaforma/amministrazione.

Tipo	Cos’è	Creato da
`Organization`	La radice dell’albero. Ogni altro nodo ne è discendente. `parentId` è `null`.	Predisposto alla creazione dell’organizzazione; mai tramite l’API
`Division`	Un raggruppamento di primo livello sotto l’organizzazione (ad es. un’unità aziendale o una regione).	`POST /v1/nodes/{parentId}/division`
`Site`	Una sede fisica sotto una divisione. Contiene data bundle ed è l’unità indirizzata dalle route di twin e ricerca.	`POST /v1/nodes/{parentId}/site`
`Folder`	Un raggruppamento annidabile per organizzare i contenuti sotto un site o un’altra cartella.	`POST /v1/nodes/{parentId}/folder`
`Project`	Un RealityPlan Project.	`POST /v1/bundles/{bundleId}/create-project`, una volta che un data bundle ha un componente elaborato e visualizzabile
`Twin`	Il descrittore dello spazio 3D di un site. Un twin viene indirizzato tramite l’id nodo del suo site, quindi non esiste un passaggio di creazione dedicato.	Azione di piattaforma (pubblicazione di un twin)
`DataBundle`	Un set di dati acquisito (point cloud, mesh, panorami, ecc.) e i relativi risultati di elaborazione.	`POST /v1/nodes/{parentId}/bundle`, con un `dbuPath` risolto
`SiteFile`	Un file caricato grezzo che non fa parte di un data bundle.	`POST /v1/site-files` (un flusso di upload dedicato, non un endpoint di creazione nodo)
`Artifact`	Un allegato o artefatto di output associato al contenuto di un twin.	Azione di piattaforma/elaborazione
`AssetLibrary`	Una libreria di modelli riutilizzabili a livello di organizzazione.	Predisposta a livello di organizzazione; mai tramite l’API

Regole padre/figlio e profondità

I tre tipi creabili formano una struttura fissa, ciascuno accetta esattamente un tipo padre:

Padre	Accetta il tipo figlio	Route
`Organization`	`Division`	`POST /v1/nodes/{parentId}/division`
`Division`	`Site`	`POST /v1/nodes/{parentId}/site`
`Site` o `Folder`	`Folder`	`POST /v1/nodes/{parentId}/folder`

Folder è l’unico tipo che si annida sotto il proprio stesso tipo, quindi è l’unico punto in cui la profondità può crescere arbitrariamente a partire da una singola chiamata API. Oltre a questa struttura, la piattaforma impone una profondità massima della gerarchia; non pubblica un numero esatto, ma i due codici di errore seguenti esistono proprio per intercettare una richiesta che la supererebbe o posizionerebbe un nodo nel posto sbagliato:

MaxDepthExceeded (restituito da PATCH /v1/nodes/{nodeId}/move/{newParentId}): la destinazione porterebbe il nodo più in profondità di quanto consentito dalla piattaforma. Spostare il nodo in una posizione meno profonda invece di annidare le cartelle indefinitamente.
DoesNotMeetHierarchyConstraints (restituito anch’esso dall’endpoint di spostamento): il padre di destinazione non accetta il tipo di questo nodo. Controllare la tabella precedente (o la posizione effettiva del tipo, tramite l’esplorazione) prima di spostarlo.

Creare un nodo sotto il tipo di padre sbagliato viene rifiutato allo stesso modo: POST /v1/nodes/{parentId}/site con un parentId che non è una Division restituisce 409 { "error": "ParentTypeNotValid" }.

Per la struttura completa della risposta e tutti gli altri codici di spostamento/eliminazione, vedere Codici di errore.

I nodi DataBundle vengono creati sotto un site o una cartella, e i nodi SiteFile vengono creati sotto un id padre passato al flusso di upload. Entrambi accettano in pratica gli stessi due tipi di padre di Folder, ma tramite i propri endpoint specifici di dominio anziché una route generica di creazione nodo. I tipi rimanenti (Twin, Artifact, AssetLibrary) vengono posizionati dall’azione di piattaforma o elaborazione che li produce, quindi esplorate l’albero per trovarli invece di presumere una posizione fissa.

La struttura del DataNode

GET /v1/nodes/{id}/browse e GET /v1/nodes/search restituiscono entrambi i nodi in questa struttura:

{
  "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
}

Campo	Note
`type`	Uno dei 10 valori `DataNodeType` sopra elencati
`parentId`	`null` solo per la radice `Organization`
`childrenCount`	Solo i figli diretti, non l’intero sottoalbero
`bytesStored`	Dimensione di storage del sottoalbero in byte
`thumbnailSignedUrl`	Opzionale. Presente solo se la richiesta lo attiva con `includeThumbnail=true`, e solo se esiste una miniatura

Esplorare rispetto a cercare

Entrambe le route restituiscono la stessa struttura DataNode, ma rispondono a domande diverse e hanno limiti diversi:

	`GET /v1/nodes/{id}/browse`	`GET /v1/nodes/search`
Risponde a	”Quali sono i figli diretti di questo nodo?"	"Trova i nodi che corrispondono a questi filtri, ovunque io abbia accesso”
Ambito	Figli diretti di un nodo	L’intero albero dell’organizzazione legato al token di accesso
`limit`	1–20	1–50
`limit` predefinito	20	50
Filtraggio	Nessuno, solo paginazione e ordinamento	Nome, tipo, padre/antenato, creatore, timestamp, dimensione di storage, numero di figli

Per la meccanica di risoluzione del primo id nodo e la chiamata a browse, vedere Trovare i propri ID. Per l’intero insieme di parametri di query di search, combinazioni di filtri ed esempi, vedere Ricerca di oggetti business e nodi.

I nodi Twin, DataBundle e AssetLibrary compaiono nei risultati di esplorazione e ricerca come qualsiasi altro nodo, ma una volta ottenuto il loro id se ne indirizza il contenuto tramite un’altra famiglia di route anziché /v1/nodes:

Tipo di nodo	Indirizzato tramite id su
`Twin`	`/v1/twin/{contextId}/...` (descrittore di spazio, ricerca oggetti business)
`DataBundle`	`/v1/bundles/{bundleId}/...` (componenti, elaborazioni, opzioni di elaborazione)
`AssetLibrary`	`/v1/asset-library/...` (come `ownerContextId`)

Prossimi passi

Codici di errore per tutti i codici di errore di spostamento/eliminazione/creazione e come gestirli.
Ricerca di oggetti business e nodi per l’intera superficie di parametri di search.